Developing a DB2 CLI application using nonvisual parts

You have been able to use nonvisual parts available with the VA: Database, DB2 CLI feature to develop a DB2 application that runs on a server. The application uses CLI to access a DB2 database. For information on which version of DB2 is required to use CLI, refer to the Supported Platforms and System Requirements. section of the VA Smalltalk web page. Your configuration for CLI must be set up correctly. A sample JCL file for configuring CLI is as follows:

//BIND EXEC PGM=IKJEFT01,DYNAMNBR=20

//STEPLIB DD DSN=DSNLNK.V5R1M0.SDSNEXIT,DISP=SHR

// DD DSN=DSNLNK.V5R1M0.SDSNLOAD,DISP=SHR

//DBRMLIB DD DISP=SHR,DSN=DSN.V5R1M0.SDSNDBRM

//SYSTSPRT DD SYSOUT=*

//SYSPRINT DD SYSOUT=*

//SYSUDUMP DD SYSOUT=*

//SYSTSIN DD *

DSN SYSTEM(DSN3) /*Must match Subsystem identifier of your DB2 system */ 02210001

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLICS) ISOLATION(CS)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLINC) ISOLATION(NC)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIRR) ISOLATION(RR)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIRS) ISOLATION(RS)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIUR) ISOLATION(UR)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIC1)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIC2)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIV2)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIF4)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIMS)

BIND PACKAGE (DSNAOCLI) MEMBER(DSNCLIQR)

BIND PLAN(DSNACLI) -

PKLIST(LOC1.DSNAOCLI.DSNCLICS -

LOC1.DSNAOCLI.DSNCLINC -

LOC1.DSNAOCLI.DSNCLIRR -

LOC1.DSNAOCLI.DSNCLIRS -

LOC1.DSNAOCLI.DSNCLIUR -

LOC1.DSNAOCLI.DSNCLIC1 -

LOC1.DSNAOCLI.DSNCLIC2 -

LOC1.DSNAOCLI.DSNCLIV2 -

LOC1.DSNAOCLI.DSNCLIF4 -

LOC1.DSNAOCLI.DSNCLIMS -

LOC1.DSNAOCLI.DSNCLIQR ) -

ACTION(REP) DISCONNECT(EXPLICIT)

END

//*********************************************************************

//* GRANT

//*********************************************************************

//GRANT EXEC PGM=IKJEFT01,COND=(4,LT)

//STEPLIB DD DSN=DSNLNK.V5R1M0.SDSNEXIT,DISP=SHR

// DD DSN=DSNLNK.V5R1M0.SDSNLOAD,DISP=SHR

// DD DISP=SHR,DSN=DSNC510.V5R1M0.RUNLIB.LOAD

// DD DISP=SHR,DSN=PLI.V2R3M0.SIBMLINK

// DD DISP=SHR,DSN=PLI.V2R3M0.PLILINK

//DBRMLIB DD DISP=SHR,DSN=DSN.V5R1M0.SDSNDBRM

//SYSPRINT DD SYSOUT=*

//SYSTSPRT DD SYSOUT=*

//SYSUDUMP DD SYSOUT=*

//SYSTSIN DD *

DSN SYSTEM(DSN3)

RUN PROGRAM(DSNTEP2) PLAN(DSNTEP51)

//SYSIN DD *

REVOKE EXECUTE ON PLAN DSNACLI FROM PUBLIC;

GRANT EXECUTE ON PLAN DSNACLI TO PUBLIC;

The environments in which you can run applications that have nonvisual parts using CLI, nonvisual parts static, query specs, static SQL code, or dynamic SQL code are shown in Table 1.

Step 1: Develop the server application

With the VA: Database, DB2 CLI feature loaded in your development image, define your server application using the feature's nonvisual parts. To define your server application, use the database parts as you would for an application that runs solely on the workstation. The VA Smalltalk Database Guide and the VA Smalltalk help provide information on using database parts.

For example, follow the instructions in the VA Smalltalk Database Guide to make a database server application that uses dynamic SQL. Then, package and run it as described.

Packaging a database server application

After you complete the database server application on the workstation, create a passive image using CLI database support for image and simulation, load the application into the passive image, precompile for any transction environment, and package the application using the XD packaging function. The VA Smalltalk Server Guide and Deploying your application on the target environment describe how to create a passive image and package a server application.

Note that you will need to separate the strings in your application because it uses nonvisual parts. See Step 2: Separating strings in your application.

Finally, transfer the packaged image to the server environment and deploy it. (If you are deploying the application on OS/390, see Running a database application.)

Running a database application

To run your database application, you must complete additional steps. For dynamic SQL, you must simulate information about the OS/390 connection on the workstation.

With DB2 Version 5.1 installed on OS/390, set up the DB2 runtime environment as described in the CLI documentation.

To run your application on OS/390, also do the following:

1.	Ensure that the CLIINI file setting for MVSDEFAULTSSID matches the the subsystem ID specified for your DB2 database (DSN3). For example, if you use CAF, your CLIINI might resemble:

; COMMON STANZA

[COMMON]

MVSDEFAULTSSID=DSN3

CLITRACE=1

; SUBSYSTEM STANZA FOR DSN3 SUBSYSTEM

[DSN3]

MVSATTACHTYPE=CAF

PLANNAME = USERPLAN

If you use RRSAF for a multithreaded connection to DB2 for OS/390 V5.0, instead of CAF, your CLIINI might resemble:

; COMMON STANZA

[COMMON]

MVSDEFAULTSSID=DSN3

CLITRACE=1

TRACEFILENAME=DD:CLITRACE

MULTICONTEXT=1

CONNECTTYPE=1

; SUBSYSTEM STANZA FOR DSN3 SUBSYSTEM

[DSN3]

MVSATTACHTYPE=RRSAF

;MVSATTACHTYPE=CAF

PLANNAME=USERPLAN

The Recoverable Resource Manager Services Attachment Facility (RRSAF) is a DB2 attachment facility that relies on an OS/390 component call OS/390 Transaction Management and Recoverable Resource Manager Services (OS/390 RRS). OS/390 RRS provides system-wide services for coordinating two-phase commit operations across OS/390 products. Before you can run an RRSAF application, you must start OS/390 RRS in its own address space. You can stop and start the RRS imdependently of DB2. For more information, refer to the DB2 for OS/390 Administration Guide.

2.	Ensure that the execution JCL file contains entries specifying Version 5.1 of DB2 in the STEPLIB and the entry pointing to your CLIINI file. For example, your execution JCL might resemble:

// EXECNAT JOB ,'HSC',CLASS=A,MSGCLASS=H,

// NOTIFY=&SYSUID,MSGLEVEL=(1,1),REGION=8192K,TIME=1440

//*------------------------------------------------------------

//EXECUTE EXEC PGM=DBMVS,COND=(0,LT)

//STEPLIB DD DISP=SHR,DSN=ABT.DEV430.NATIVE.LOAD

// DD DISP=SHR,DSN=DSNLNK.V5R1M0.SDSNEXIT

// DD DISP=SHR,DSN=DSNLNK.V5R1M0.SDSNLOAD

// DD DISP=SHR,DSN=CEE.SCEERUN

//SYSPRINT DD SYSOUT=*

//SYSOUT DD SYSOUT=*

//DSNAOINI DD DISP=SHR,DSN=HSC.JCL(CLIINI)

//CLITRACE DD SYSOUT=*

For static SQL, add to your connection specs "Alias" method the following three statements:

caf: <true/false>; "false deletes everything"

subsystemIdentifier: <MVS DB2 subsystem identifier>;

planName: <plan name>; "On MVS, the DBRM file is bound to the plan name"

As long as caf: is true, values specified for these three statements will be unchanged. Further, even if you change the connection spec in the development environment, values for the statements will remain unchanged.

A sample connection spec definition for the dbsample "Alias" is as follows:

dbsample

^AbtDatabaseConnectionSpec new

dbmClass: AbtIbmCliDatabaseManager;

dsn: 'LOC1';

promptEnabled: true;

caf: true;

subsystemIdentifier: 'DSN3';

planName: 'USERPLAN';

yourself

After you complete these steps, do the following:

1.	Precompile the access set in the development environment.

2.	Version and release your work.

3.	Load the application into an XD image.

4.	Precompile for OS/390.

5.	Ensure that environment variables are set correctly.

6.	Transfer the packaged image to OS/390.

7.	Create a load module.

8.	Run the load module.

For information on precompiling static SQL, refer to the VA Smalltalk Database Guide.