RRSAF

Team-Fly    

 
DB2 Universal Database for OS/390 v7.1 Application Certification Guide
By Susan Lawson
Table of Contents
Chapter 14.  Attachment Programming


An application program can use the RRSAF to connect to and use DB2 to process SQL statements, commands, or IFI calls. Programs that run in MVS batch, TSO foreground, and TSO background can use RRSAF.

RRSAF uses OS/390 Transaction Management and Recoverable Resource Manager Services (OS/390 RRS). With RRSAF, you can coordinate DB2 updates with updates made by all other resource managers that also use OS/390 RRS in an MVS system.

Capabilities

Programs that use RRSAF can

  • Run under UNIX System Services.

  • Sign on to DB2 with an alternate user ID.

  • Access DB2 from one or more tasks in an address space.

  • Use the IFI.

  • Control the exact state of the DB2 connection.

  • Capture DB2 startup and termination events.

Programs using RRSAF can be run from almost every environment available under z/OS and OS/390. They can be invoked from the command prompt in TSO, from a shell prompt under UNIX System Services, and like any non-DB2 on the EXEC card in JCL. Each TCB can have only one connection to DB2. Using RRSAF, this connection can be switched between tasks within the address space.

Restrictions

Stored procedures that execute in WLM environments use RRSAF implicitly. No calls to DSNRLI should be made by the stored procedure code.

Requirements

To use RRSAF to communicate with DB2, a program must call the DSNRLI program, passing it the appropriate functions. Several calls are required to identify the program to DB2, sign on, and create a thread. The program has considerable control over the process when compared to the TSO attachment where the program has to assume the connection has already been established.

Loading DSNRLI Explicitly

To load DSNRLI, issue MVS LOAD macros for entry points DSNRLI and DSNHLIR. If you use IFI services, you must also load DSNWLIR. Save the entry point address that LOAD returns and use it in the CALL macro.

By explicitly loading the DSNRLI module, you can isolate the maintenance of your application from future IBM service to the language interface. If the language interface changes, the change will probably not affect your load module. You must indicate to DB2 which entry point to use. You can do this in one of two ways:

  • Specify the precompiler option ATTACH(RRSAF). This causes DB2 to generate calls that specify entry point DSNHLIR.

  • Code a dummy entry point named DSNHLI within your load module. If you do not specify the precompiler option ATTACH, the DB2 precompiler generates calls to entry point DSNHLI for each SQL request. The precompiler does not know and is independent of the different DB2 attachment facilities.

When the calls generated by the DB2 precompiler pass control to DSNHLI, your code corresponding to the dummy entry point must preserve the option list passed in R1 and call DSNHLIR specifying the same option list.

Execution

Programs using RRSAF can be invoked from command lines under TSO or UNIX System Services, or directly from JCL, as in the following:

 //MYJOB1  JOB  //STEP1   EXEC PGM=MYPGM //STEPLIB  DD  DSN=MY.LOADLIB,DISP=SHR //SYSPRINT DD  SYSOUT=* //SYSOUT   DD  SYSOUT=* //SYSIN    DD  DUMMY 

The ability to code your DB2 program in JCL this way is a big bonus when operations staff are unfamiliar with batch-mode TSO.

Units of Work

To commit work in RRSAF applications, use the CPIC SRRCMIT function or the DB2 COMMIT statement. To roll back work, use the CPIC SRRBACK function or the DB2 ROLLBACK statement.

Use DB2 COMMIT and ROLLBACK statements when you know that the following conditions are true:

  • The only recoverable resource accessed by your application is DB2 data managed by a single DB2 instance.

  • The address space from which syncpoint processing is initiated is the same as the address space that is connected to DB2.

If your application accesses other recoverable resources, or syncpoint processing and DB2 access are initiated from different address spaces, use SRRCMIT and SRRBACK.

How to Program

To use RRSAF, you must first make available the RRSAF language interface load module, DSNRLI. This can be achieved by linking DSNRLI into your load module or loading it dynamically at execution time. Your program then calls DSNRLI to establish the connection to DB2.

The DSNRLI interface includes the program DSNRLI, which takes several parameters. The first parameter is the function you want performed. The functions listed in Table 14-4 are available.

Table 14-4. DSNRLI Functions

Function

Description

IDENTIFY

Establishes the task as a user of the named DB2 subsystem. When the first task within an address space issues a connection request, the address space is initialized as a user of DB2.

SWITCH TO

Directs RRSAF, SQL, or IFI requests to a specified DB2 subsystem.

SIGNON

Provides to DB2 a user ID and, optionally , one or more secondary authorization IDs that are associated with the connection.

AUTH SIGNON

Provides to DB2 a user ID, an Accessor Environment Element (ACEE), and optionally one or more secondary authorization IDs that are associated with the connection.

CONTEXT SIGNON

Provides to DB2 a user ID and optionally one or more secondary authorization IDs that are associated with the connection. You can execute CONTEXT SIGNON from an unauthorized program.

CREATE THREAD

Allocates a DB2 plan or package. CREATE THREAD must complete before the application can execute SQL statements.

TERMINATE THREAD

Deallocates the plan.

TERMINATE IDENTIFY

Removes the task as a user of DB2 and, if this is the last or only task in the address space that has a DB2 connection, terminates the address space connection to DB2.

TRANSLATE

Returns an SQL code and printable text, in the SQLCA, that describes a DB2 error reason code. You cannot call the TRANSLATE function from the FORTRAN language.

The effect of any function depends in part on what functions the program has already performed. Before using any function, be sure to read the description of its usage. To better understand how functions can be used, we'll provide code samples for some common routines that can be used to make this easy.

Initialization

The following code section shows the initialization portion of the OpenDB2() function implemented in C. This particular function takes the DB2 subsystem ID and the plan name to be used for this connection.

 extern int OpenDB2(const char* db2ssid, const char* db2plan)  {    char funcIdentify[19]          = "IDENTIFY          ";    char funcSignon[19]            = "SIGNON            ";    char funcCreateThread[19]      = "CREATE THREAD     ";    long     fnret;    char     Ssid[5] = "DSN ";    char     Plan[9] = "TEST    ";    char     Collection[19] = "                  ";    char     Reuse[9] = "INITIAL ";    char *   ribptr;    char *   eibptr;    long     startecb = 0;    long     termecb = 0;    long     ReturnCode = 0;    long     ReasonCode = 0;    char     CorrelationId[13];    char     AcctToken[23];    char     AcctInterval[7]   = "SIGNON";    char     UserId[17];    char     ApplId[33];    char     WsId[19];    long     i = 0; 

Now that the housekeeping functions are out of the way, we use the IDENTIFY function to start the communication with DB2. This is where the DB2 subsystem ID gets specified to the attachment.

 strncpy(Ssid, db2ssid, 4);  i = strlen(Ssid); if (i < 4)  /* SSID must be blank padded */ {     i = 4 - i;     strncat(Ssid, "    ", i); } fnret = DSNRLI(&funcIdentify[0],                &Ssid[0],                &ribptr,                &eibptr,                &termecb,                &startecb,                &ReturnCode,                &ReasonCode); if (fnret != 0) { } 

Then we use the SIGNON function. This provides an accounting token that can be used to identify our connection for charge-back purposes. We also get to set the correlation ID that is used to identify the connection to DB2 display commands and performance monitors .

 strncpy(CorrelationId, "TEST", 4);  strncpy(&(CorrelationId[4]), db2plan, 8); fnret = DSNRLI(&funcSignon[0],                &CorrelationId[0],                &AcctToken[0],                &AcctInterval[0],                &ReturnCode,                &ReasonCode); if (fnret != 0) {    /* Error handling */ } 

The last part of establishing the connection is thread creation, where we specify the DB2 plan name for our application.

 Strncpy(Plan, db2plan, 8);   fnret = DSNRLI(&funcCreateThread[0],                 &Plan[0],                 &Collection[0],                 &Reuse[0],                 &ReturnCode,                 &ReasonCode);  if (fnret != 0)  {     /* Error handling */  }  return 0; } 

When the OpenDB2() function returns, we are connected to DB2 and ready to execute SQL statements.

SQL Processing

SQL statements are embedded in RRSAF programs just as they are in programs that use any of the other attachment facilities.

Error Checking

Calls to DSNRLI return a status return code and reason code. The reason codes correspond to standard DB2 reason codes available in the IBM DB2 Message and Codes Manual-GC26-9940 . Programs should check the SQLCODE or SQLSTATE returned in the SQLCA after every SQL statement to determine its status.

Termination

Closing the RRSAF connection to DB2 is optional and is almost the reverse of the initialization steps. Here is a bit of sample code to perform the close. Before calling this routine, the UOW must be committed. If the UOW is not committed, your program will abend. The routine first terminates the thread.

 extern int CloseDB2()  {     long     fnret;     long     ReturnCode = 0;     long     ReasonCode = 0;     fnret = DSNRLI(&funcTerminateThread[0],                    &ReturnCode,                    &ReasonCode);     if (fnret != 0)     {        /* Error Handling */     } 

It then terminates the identify.

 fnret = DSNRLI(&funcTerminateIdentify[0],                    &ReturnCode,                   &ReasonCode);    if (fnret != 0)    {       /* Error Handling */    }   return 0; } 

If an application that is connected to DB2 through RRSAF terminates normally before the TERMINATE THREAD or TERMINATE IDENTIFY functions deallocate the plan, then OS/390 RRS commits any changes made after the last commit point.

If the application terminates abnormally before the TERMINATE THREAD or TERMINATE IDENTIFY functions deallocate the plan, then OS/390 RRS rolls back any changes made after the last commit point.

In either case, DB2 deallocates the plan, if necessary, and terminates the application's connection. A tracing facility provides diagnostic messages that help you debug programs and diagnose errors in the RRSAF code. The trace information is available only in a SYSABEND or SYSUDUMP dump.

DB2 Abend

If DB2 abends while an application is running, the application is rolled back to the last commit point. If DB2 terminates while processing a commit request, DB2 either commits or rolls back any changes at the next restart. The action taken depends on the state of the commit request when DB2 terminates.


Team-Fly    
Top


DB2 Universal Database for OS. 390 v7. 1 Application Certification Guide
DB2(R) Universal Database for OS/390 V7.1 Application Certification Guide (IBM DB2 Certification Guide Series)
ISBN: 0131007718
EAN: 2147483647
Year: 2002
Pages: 163
Authors: Susan Lawson

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net