The following topics are described in this document:
This section describes the programming considerations specific to CICS application program development, including:
The ConnecX Attachment Facility (CXGCICS) includes a task-related user exit, CXGCIEX1, which is invoked when an application program makes an SQL request. It manages the connections to the Adabas SQL Gateway, and returns control to the application program when processing is complete.
CXGCICS exploits the open transaction environment (OTE) that enables the CXGCICS task-related user exit to be invoked and to return without switching TCBs. The CXGCICS task-related user exit operates as a threadsafe and open API task-related user exit program. It is enabled using the OPENAPI option on the ENABLE PROGRAM command; consequently, it is able to receive control on an open L8 mode TCB.
In the open transaction environment, if the user application program conforms to threadsafe coding conventions and is defined to CICS as threadsafe, it can also run on the L8 TCB. Before its first SQL request, the application program runs on the CICS main TCB, the QR TCB. When it makes an SQL request and invokes the task-related user exit, control passes to the L8 TCB, and CXGCICS processing is carried out. On return from CXGCICS, if the application program is threadsafe, it continues to run on the L8 TCB; otherwise control passes to a QR TCB.
When running on the L8 TCB, CICS continues to run the application on the L8 TCB until it is necessary to switch back, for example to run a non-threadsafe API request. The number of switches incurred and the cost incurred by the switches can be significant.
The threadsafe coding conventions are described in the section Multithreading: Reentrant, quasi-reentrant, and threadsafe programs of Chapter 18. Application Design in the IBM Manual CICS Transaction Server for z/OS Version 5 Release 1 Application Programming Guide.
The complete SQL language is available to the CICS programmer with only minor restrictions. In a CICS program, it is possible to use:
Data manipulating language (DML);
Data description language (DDL); and
Data control language (DCL).
CICS also supports both dynamic and static SQL statements.
The following statements should not be used in a CICS application:
CONNECT;
DISCONNECT;
COMMIT;
ROLLBACK.
CXGCICS manages, creates, and terminates the SQL session under CICS.
A session is created when the first SQL statement of a CICS transaction is executed.
The session is terminated when the CICS task manager indicates an "End-Of-Task".
Understanding SQL Processing lists the main activities that happen during SQL processing.
The CICS synchronization manager transfers control to CXGCICS when synchronization points are required. Depending upon what has been requested; CXGCICS executes one of the following statements:
COMMIT;
ROLLBACK.
CXGCICS takes advantage of the following SYNCPOINT optimization features:
Read-Only;
Single-Phase COMMIT.
Note:
The CICS application should not execute COMMIT or ROLLBACK
statements.
Recovery processing is performed during the initialization of CXGCICS or during reconnect processing after a connection to the CXGSERV has been lost.
The process consists of executing an EXEC CICS RESYNC command to determine the disposition of the units of work (UOWs) that are in doubt. Two examples of in doubt UOWs are:
CXGSERV sessions which no longer have an associated unit of work; and
Units of work that may be in doubt because they do not have a state in flight.
This results in CICS creating CRSY recovery tasks for each unit of work that is in doubt. These tasks are then processed by CXGCICS accordingly.
This section describes the programming considerations specific to batch application program development, including:
The complete SQL language is available to the ConnecX SQL Gateway programmer. In a program, programmers may use:
Data manipulating language (DML);
Data description language (DDL); and
GRANT and REVOKE statements.
Both dynamic and static SQL statements are supported.
The batch application controls when an SQL session is created and terminated. The CONNECT and DISCONNECT statements are used to manage an SQL session.
When using the CXGCONM functionality, the syntax and usage of the CONNECT statement is non-standard. Please read Configuring CXGCONM and Using CXGCONM for further details.
It is the responsibility of the batch application to commit or rollback database transactions.
The features described below imply that the ConnecX Connect Manager (CXGCONM) allows applications to use the CXGCICS runtime options and user identification schema to access data via the CONNX JDBC server. It optionally enables the translation of response codes.
There are minor differences in CONNECT statement processing between CICS applications and batch applications using CXGCONM.
Both use the CXGCIOPT definitions to identify server connections, authorization IDs, and application-specific attributes, as described in this section:
The CXGMSRV definitions in the CXGCIOPT module define the location and use of servers. Server definitions are uniquely identified by server type (CXG or CXX) and name.
In a CICS environment, the system ID (SYSID) is used to locate the associated server definition. If not found, the DEFAULT server definition is used.
In a batch environment, the value of the server name in the CONNECT statement is used to locate a server definition. If not found, the DEFAULT server definition is used.
The authorization ID used to create an SQL session is determined by the user identification schema associated with the transaction or batch job. The user identification schema used to connect to the Adabas SQL Gateway is defined in the CXGCIOPT module and is CICS transaction or batch job specific.
The following user identification schemata are possible:
| Identification Schema | Description |
|---|---|
| User ID | The user ID associated with the CICS transaction. |
| Group ID | The group ID associated with the CICS transaction. |
| Authorization ID | One of the following are possible: a CXGCIACF security token or a literal value. |
| Transaction ID | The CICS transaction identification (4 characters). |
| Sign ID | The value of the SIGNID parameter in the CXGMCONN macro. |
| Job Name | The job name attribute of the batch job. |
| Job ID | The job ID attribute associated with the batch job. |
Note:
If the value is less than eight characters long, it is padded on the
right with blanks.
The attributes to be used with a CICS transaction or batch job are taken from the CXGMTRAN and CXGMJOB definitions in the CXGCIOPT module.
In a CICS environment, the transaction ID is used to locate the associated CXGMTRAN definition. If it is not found, the DEFAULT definition is used.
In a batch environment, the value of the user name in the CONNECT statement is used to locate a CXGMJOB definition. If it is not found, the DEFAULT definition is used.
In both cases, it is possible to associate the connection attributes (such as the following) to a transaction or a batch job:
JDBC DSN;
User identification schema; and
CONNECT-options.
The Access Control Table (CXGCIACF) module enables the definition of security tokens. The tokens can then be used as a value for either the AUTHID or for the AUTH parameter in the CXGMTRAN or CXGMJOB macros in the CXGCIOPT module.
This implementation enables a separation of roles such as the following roles: security officer, database administrator, and program developer.
The security officer defines the security tokens and the associated encrypted values.
The database administrator assigns security tokens to one or more transaction or job definitions as user identification schema; as either an authorization (AUTH) or an authorization ID (AUTHID).
The program developer can then use the name of the job definition in the CONNECT statement of a batch application.
The response codes returned by the Adabas SQL Gateway can, optionally, be translated. This feature is provided as a migration aid and is available to both CICS and batch application programs.
Code translation is only performed on the following values: SQLCODE, SQLSTATE, and SQLCA. The values returned by the GET DIAGNOSTICS statement are not translated. The values used to perform code translation are defined via the CXGMCODE macro in the CXGCIOPT module.
The following restrictions apply:
The values returned by the GET DIAGNOSTICS statements are not translated.
In batch, the CXGCODE module must be included in the interface routine.