The CorrelationId contains the correlation name you want in your accounting records. The AcctToken is another field that will show up in the accounting records. The AcctInterval field contains either “SIGNON” or “COMMIT” and controls the frequency with which DB2 will cut accounting records for your application activity. To keep the number of accounting records to a minimum, just specify “SIGNON.”
The third call, “CREATE THREAD,” provides the plan or collection information necessary for DB2 to execute the programs used in the application. It looks like Figure 3. The plan name here should contain all the packages generated when the programs went through the DB2 precompile and bind processes. If you like, you can instead put a question mark in the plan name and specify a collection name or list of specific packages, but this will probably just lead to confusion, since most of us don’t manage our applications that way. The Reuse parameter should contain either “INITIAL” or “RESET” to indicate the action taken if another “SIGNON” call is issued. The default is “INITIAL” and should be used unless you want to get more complicated in your program design.
After each call, the results of the call in fnret should be tested to verify that the call itself worked, then the ReturnCode should be checked to ensure the call was successful. In diagnosing problems, it may be helpful to print the ReturnCode and ReasonCode contents if there’s a failure in any of the calls.
Managing Units of Work
Now that you have a function to let your programs connect to DB2, you’ll need to make sure your units of work are properly controlled. Programs that use only DB2 resources can just issue the SQL COMMIT or ROLLBACK statements. To play it safe, you can instead go ahead and code the calls to SRRCMIT and SRRBACK. The only parameter to these function calls is the integer return code. Here’s a sample commit:
fnret = srrcmit(&ReturnCode);
Implicit RRSAF Calls
DB2 for z/OS Version 8 lets you do all this without actually calling DSNRLI if you’re willing to take a few defaults. You lose a bit of control this way, but you may be able to convert more programs to use RRSAF without any code changes. Using the implicit method, you just precompile and link your program using the RRSAF settings and issue your embedded SQL statements as you would in a TSO attach facility program. When the first SQL statement is issued, the RRSAF module will take the subsystem name from the DSNHDECP module and do the “IDENTIFY” call. It will then take the program name and use that as the plan name for the “CREATE THREAD” call. The implicit connection skips the “SIGNON” call. #Sample Programs
You now have nearly enough information to code your own OpenDB2 function. To make it even easier to get started, you can access a sample program at www.db2expert.com.
The sample source code includes the db2rrsaf.c module. This contains a C version of OpenDB2 and a few helper functions. You must compile this into a library module that’s included during the link step of the programs that call the functions.
A CloseDB2 function is also included for programs that want to explicitly close their connection. You can see in the online sample that the calls required to disconnect are “Terminate Thread” and “Terminate Identity.” Before calling the CloseDB2 function, any open unit of work must be committed or rolled back or the close operation will fail.