CICS

Team-Fly

---

 

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

---

CICS

All CICS programs that access DB2 use the CICS attachment facility. CICS provides components that establish the connection to DB2. Many connections, called threads, can be established between a single CICS region and a DB2 subsystem. Each CICS region can attach to only one DB2 subsystem at a time. CICS/DB2 programs using embedded SQL can be written in COBOL, PL/I, C, C++, or Assembler.

CICS programs can also be written in Java using JDBC or SQLJ to access DB2. JDBC does not allow connections to be shared, so non-Java programs that call a Java program should commit or rollback their UOW prior to that call. Unlike SQLJ and JDBC applications that use other attachment facilities, SQLJ and JDBC applications that use the CICS attachment facility can create only one JDBC java.sql.Connection object within a UOW. Multithreading is supported, but Java child threads may not issue JDBC or SQLJ statements.

Capabilities

CICS regions provide a high-performance multithreaded execution environment for application programs. Programs running under CICS share resources like files and access these resources using the CICS command-level interface. CICS/DB2 programs also share database resources. When CICS is started, the CICS attachment facility modules allocate subtask task control blocks ( TCBs) that are shared among the programs that execute SQL statements. These TCBs can be preconnected to DB2, and the CICS attachment facility includes a transaction (DSNC) that can be used to issue DB2 commands.

Restrictions

The CICS regions that connect to DB2 must run on the same MVS system as the DB2 subsystem. This restriction does not apply to other CICS regions, like terminal-owning regions that may execute on other MVS systems. Programs may use the IBM-supplied routine DSNTIAC instead of DSNTIAR to generate error messages under CICS.

Requirements

There are some requirements unique to executing in a CICS environment.

Resource Control Table (RCT)

The CICS attachment is controlled by the RCT. In current levels of CICS, the DB2 interface modules are shipped as part of CICS and take advantage of its online resource definition capabilities. The RCT definitions are very flexible allowing the specification of

• Plan names

• Authorization checking options

• Thread limits and pooling options

• Error processing options

The RCT has three sets of components that must be defined. The DB2CONN object defines global attributes for the CICS DB2 interface, including pool thread and command thread attributes. There is only one DB2CONN entry for a CICS region. Command threads are used by the attachment interface when issuing commands. Pool threads are a group of threads that may be used by any transaction if no dedicated, or entry, threads are defined for that transaction. Pool threads are not reusable.

The DB2ENTRY objects contain attributes for DB2 threads that may be used by a group of transactions. These define the entry, or dedicated, threads that are available for a transaction. The transaction ID can include wildcards to simplify definition. Entry threads are reusable.

The DB2TRAN objects define additional transaction IDs that may be associated with a DB2ENTRY object.

Coordinating DB2 and CICS Security

CICS manages end- user authentication with the system-supplied security system. The CICS attachment has several options for passing authorization IDs to DB2. The authorization ID that is passed to DB2 is controlled by the RCT entry for the transaction and can be

• The CICS region's sign-on user ID

• The terminal operator's authorization ID

• The terminal name

• The transaction ID

• The terminal operator's group ID

• A fixed string defined in the RCT

DB2 Commands

The CICS interface to DB2 has a transaction, DSNC, which can be used to

• Start the interface

• Stop the interface

• Display thread statistics

• Execute DB2 commands

To start the CICS DB2 interface to subsystem DSN1, the command is

 DSNC STRT DSN1 

The subsystem doesn't need to be specified on the command unless you want to override the subsystem defined in the DB2CONN object in the RCT.

Stopping the attachment between CICS and DB2 is simply

 DSNC STOP QUIESCE 

The QUIESCE option will allow work to complete before terminating the attachment. There is also a FORCE option.

The DSNC DISPLAY command allows you to monitor the CICS attachment to DB2 and collect statistical information about the threads that have been used. The following command will display a report showing the number of calls, high watermarks, and commits:

 DSNC DISPLAY STATISTICS 

Preparing CICS Applications for DB2

The following tasks must be performed for CICS applications accessing DB2 resources:

1. Precompile the application using the DB2 precompiler.

2. Translate the application using the CICS command translator.

3. Compile or assemble the application.

4. Link-edit the application, including the CICS-supplied SQL language interface module DSNCLI and the appropriate CICS command-level interface module. If the application also accesses DL/I, the corresponding IMS language interface must also be included.

5. Bind the application to its application plan.

The CICS command translation can be done before the DB2 precompilation, but the CICS translator will issue a warning message for each EXEC SQL statement.

Execution

CICS programs may execute only in CICS address spaces. Load libraries containing programs to run under CICS must be specified in the concatenation of libraries in the DFHRPL DD statement for the CICS region in which the program executes.

CICS programs run under a transaction ID that may require one or more CICS address spaces. A common configuration separates different kinds of work into task-specific regions. Configurations often include Terminal Owning Regions (TOR), Application Owning Regions (AOR), and File Owning Regions (FOR). In this case, the AOR address spaces run the CICS/DB2 attachment code and the application programs. The application load library needs to be present only in the JCL for these AORs.

Units of Work

CICS is a transaction manager and controls the UOW for all programs. The SQL COMMIT and SQL ROLLBACK statements must not be used in DB2/CICS programs. Instead, code the appropriate CICS command-level statements.

 EXEC SQL UPDATE MYTABLE              SET COL2 = 'Y'           WHERE COL1 = 'A'             AND COL2 = 'N' if(SQLCODE == 0) {   /* Commit work */   EXEC CICS SYNCPOINT } else if(SQLCODE < 0) {   /* Rollback work */   EXEC CICS SYNCPOINT ROLLBACK } 

CICS controls the synchronization point processing using either one-phase or two-phase commits as appropriate. Each UOW is marked as complete by a synchronization point, defined as follows :

• Implicitly at the end of a transaction when the program issues a CICS RETURN command from the initial program.

• Explicitly by CICS SYNCPOINT commands.

• Implicitly through a DL/I PSB termination ( TERM ) call or command.

• Implicitly when a batch DL/I program issues a DL/I checkpoint call.

If the system fails, DB2 backs out uncommitted changes to data. Changed data returns to its original condition without interfering with other system activities. Sometimes, DB2 data does not return to a consistent state immediately. DB2 does not process in-doubt data (data that is neither uncommitted nor committed) until the CICS attachment facility is also restarted. To ensure that DB2 and CICS are synchronized, both DB2 and the CICS attachment facility must be restarted.

For JDBC applications under CICS, the autocommit setting is turned off by default. You can use native JDBC and SQLJ commit and rollback processing, because the SQLJ/JDBC driver translates commit and rollback statements to CICS syncpoint calls.

Program Characteristics

There are some characteristics specific to developing programs to run under CICS.

Initialization

Application programs running under CICS use the attachment facilities supplied by CICS. There is no need for the application code to load the interface modules. The high-level interface module for the CICS attachment facility is DSNCLI, and all DB2/CICS programs must include it in the link-edit step.

In CICS version 4 and higher, you can tell the attachment to wait for DB2 to start and make itself available at that time. You can also specify that the interface return a SQLCODE of 923 with a reason code that indicates that the attachment facility is not available. In prior releases of CICS, an AEY9 abend was received when an attempt was made to execute a SQL statement before the attachment was available. You can check to see if the DB2 interface is active in the CICS region by using

 EXEC CICS INQUIRE EXITPROGRAM 

If the command returns an invalid exit request (INVEXITREQ), then the attachment facility is not available. A NORMAL return, however, does not guarantee that the attachment facility is available. The CONNECTST parameter should be used to test whether the attachment facility is ready to process SQL statements, as in

 EXEC CICS INQUIRE EXITPROGRAM CONNECTST 

The shared resources are called threads. In many cases, the CICS/DB2 interface can take steps to reuse these threads for multiple transactions. This saves significant time in establishing the connection to DB2.

In general, you want transactions to reuse threads whenever possible, because there is a high processor cost associated with thread creation. An existing thread can be reused by a new transaction with the same plan and on the same RCT entry. Nonterminal transactions release their threads at the end of a task. Terminal-driven transactions may release their threads at SYNCPOINT if the following conditions are true.

• The following special registers must be in their initial state:

  - CURRENT APPLICATION ENCODING SCHEME

  - CURRENT PACKAGESET

  - CURRENT PRECISION

  - CURRENT RULES

  - CURRENT SERVER

  - CURRENT SQLID

• The CURRENT DEGREE special register must not have been modified during the life of the thread.

• Declared temporary tables that were defined with ON COMMIT PRESERVE ROWS must have been explicitly dropped.

• All cursors declared WITH HOLD must be closed.

The most important step in maximizing thread reuse is closing all cursors declared WITH HOLD. A thread for an application that contains an open cursor cannot be reused. A recommended programming practice is to close cursors immediately after you finish using them.

Programs do not need to code CONNECT statements, since the DB2 subsystem specification is controlled by the RCT. They can issue CONNECT statements to connect to remote databases defined in the local communications database.

SQL Processing

Programs use embedded SQL statements. The DB2 precompiler translates the statements into the appropriate language calls to the high-level interface module.

Error Checking

As with the TSO attachment, programs should check the SQLCODE or SQLSTATE returned in the SQLCA after every SQL statement to determine its status. Rather than using DSNTIAR to format error messages, programs running under CICS must use the routine DSNTIAC.

Termination

Normal termination for CICS/DB2 programs consists of closing cursors, if any, and returning to the caller via

 EXEC CICS RETURN 

During transaction termination, CICS will process an implicit synchronization point and tell DB2 to commit the UOW.

In a CICS SQLJ or JDBC application, you need to explicitly close the java.sql.Connection before the program ends to ensure that work is committed and make the java.sql.Connection object available for reuse. If a CICS program aborts, CICS controls the termination and backout processing. During abort processing, CICS tells the DB2 attachment to back out the UOW.

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 of both DB2 and the CICS attachment facility. Coordinating the cleanup of threads that were "in commit" is the responsibility of CICS.

---

Team-Fly

Top