Programs that use RRSAF can run under TSO, USS, and as batch programs. This is the same program, not different versions for each environment. Under TSO, programs that use RRSAF run as executable programs directly without the use of the DSN command. In fact, you cannot run an RRSAF program using the RUN subcommand of DSN.
Under USS, you run your program simply by making it an executable program file and storing it in one of your file systems. Then, execute the program from a shell prompt as you would any Unix command.
In batch, use your EXEC card and specify “PGM=MYPGM” just like you would for a non-DB2 program. The return code from the program will translate directly into the condition code for your job step.
To simplify the application programs you write, you can program sample functions that implement the RRSAF calls to abend if any calls fail. This means that the programs can call the OpenDB2 function and, if it returns, the connection was successful.
The DB2 subsystem and plan names are input parameters to the programs to simplify migration from test to production without requiring code changes. This also provides the flexibility to run the programs using different schemas in your test environment. Remember that these parameters will need to be passed into the programs using slightly different syntax based on the execution environment.
Basic API Calls
The DSNRLI program acts as the interface for RRSAF and accepts a variety of parameters. The first parameter is always the function you want the interface to perform. This function is a text field that contains the name of the function you want performed. Establishing a connection to DB2 generally requires three calls to DSNRLI with functions of “IDENTIFY,” “SIGNON,” and “CREATE THREAD.” Each of these functions has a list of additional parameters that are required. All the functions also require output parameters that will receive the return code and reason code for the function call itself.
The first call, “IDENTIFY,” accepts the DB2 subsystem name as its primary input parameter. The input function string is always an 18-byte field and should include spaces as padding. An implementation of OpenDB2 in C would use the call shown in Figure 1.
The ribptr and eibptr fields will contain pointers to information blocks that you probably won’t need to reference. The termecb and startecb fields can be used to specify Event Control Blocks (ECBs) that will be posted when the DB2 subsystem stops and starts. The last parameter, GroupOverride, can contain “NOGROUP” if you want the subsystem name to be used to connect to a DB2 member subsystem that has the same name as a data sharing group. The second call, “SIGNON,” would look like Figure 2.