Configuring CXGCICS

You can tailor the ConnecX Attachment Facility (CXGCICS) for use at your installation. You can:

  • Specify unique module name prefixes, thus allowing you to install multiple instances of the product;

  • Configure basic and runtime options for use by CXGCICS.

The configuration options are stored in modules in the installation directory. Three modules are provided: CXGCIDEF, CXGCIOPT, and CXGCIACF.

This document describes the purposes of these modules, the options contained within them, and how to maintain the options.

Specifying Default Options in CXGCIDEF

The CXGCIDEF module specifies default options used during PLT initialization and startup. Specifically, it allows you to modify the module prefix (first five characters) used for this installation. By modifying the module prefix, you can install multiple instances of the product, if needed.

Note:
Once you have modified CXGCIDEF, be sure to execute the CXGCICS JCL found in member AJ01INST of the dsnhlq.CXGCICS.CNTL data set. This will rebuild the load library and pick up your site-specific settings.

Use the CXGMINST macro to define the default configuration options in CXGCIDEF. At this time, CXGMINST has only one available parameter that you can set: PREFIX. The PREFIX parameter defines the first five characters of the module names used by CXGCICS; this value is used to build the module names and must reflect the module names used in the installation JCL AJ01INST. The default is "CXGCI".

Configuring Runtime Options in CXGCIOPT

Runtime options are loaded and processed during PLT initialization. Macro definitions in the source module CXGCIOPT define the runtime options for the ConnecX SQL Gateway. You must modify this to source module to meet the requirements of your installation.

The following table summarizes the macro entries you will find in the CXGCIOPT module:

Macro Description Occurrence
CXGMCONN ConnecX Attachment Facility (CXGCICS) parameters First entry
CXGMSRV TYPE=CXG ConnecX Multiclient Subsystem (CXGSERV) definitions One or more entries
CXGMSRV TYPE=CXX CONNX JDBC Server definitions One or more entries
CXGMTRAN Transaction definitions One or more entries
CXGMJOB Batch job definitions Optional
CXGMCODE Adabas SQL Gateway code-to-DB2 code definitions Optional
CXGMEND Validation check Last entry

Each of these macro entries is now described in depth.

CXGMCONN Macro

The CXGMCONN macro settings configure the processing of the CXGCICS component of the ConnecX SQL Gateway. This includes settings related to connection processing logic, assignment of TD queues, and assignment of CICS trace points.

The CXGMCONN macro entry must be the first entry in the CXGCIOPT module. Only one CXGMCONN macro can be specified in the CXGCIOPT module.

The following table describes the parameters that can be set by the CXGMCONN macro.

Parameter Description Length Default
ABCODE The value used as a prefix of the abend code when a transaction dump or an abend is requested. The value must be two characters long. 2 UQ
CONNECTERROR The way that information is reported back to an application that has issued an SQL request when CICS is not connected because CXGCICS is in standby mode.

The following are valid values: SQLCODE or ABEND:

  • ABEND indicates that the application should terminate with system completion code xxY9 (where xx is the setting of the ABCODE parameter).

  • SQLCODE indicates that the application should receive a -10923 SQL code.

Note:
SQLCODE cannot be specified for this parameter when the STANDBYMODE parameter is set to NOCONNECT.

--- ABEND
DESCRIPTION The description of the connection definition. There are no restrictions to the characters used in this description, but a maximum of 58 characters can be specified. 58 ---
MSGDESTINATION The destination of messages. Valid values include:

  • CONSOLE (issue messages as WTO);

  • TDQ (issue messages to the transient data queue defined by parameter MSGQUEUE1); and

  • BOTH (issue to both CONSOLE and TDQ).

--- BOTH
MSGQUEUE1 The transient data destinations to which unsolicited messages from CXGCICS are sent. The first destination cannot be blank. 4 CSSL
NAME The name of a connection definition. This name is used in messages and in the administration utility to identify the occurrence of the ConnecX Attachment Facility. The name can be up to eight characters long. The following characters are allowed: A-Z, 0-9, $, @ and #.

All lowercase characters will be converted to uppercase.

8 ---
SIGNID The authorization ID to be used by CXGCICS when signing onto the Adabas SQL Gateway when AUTHTYPE(SIGN) is specified. The default is blanks, which are replaced by the application ID of the CICS system. A maximum of eight characters can be specified. The following characters are allowed: A-Z, 0-9, $, @ and #.

All lowercase characters will be converted to uppercase.

8 blanks
STANDBYMODE The action that should be taken by CXGCICS when CXGSERV is not active and an attempt to connect occurs.

The following are valid values: RECONNECT, CONNECT, or NOCONNECT.

  • CONNECT indicates that CXGCICS should wait in standby mode for CXGSERV to become active. If the connection is made and CXGSERV later fails, CXGCICS will terminate.

  • NOCONNECT indicates that CXGCICS should terminate when a connection to CXGSERV cannot be established or if the connection fails or is terminated.

  • RECONNECT indicates that CXGCICS should go into standby mode and wait for CXGSERV to become active. If CXGSERV later fails after the connection is made, CXGCICS reverts back to standby mode and CICS then reconnects to CXGSERV when CXGSERV recovers.

--- RECONNECT
STATSQUEUE The transient data destination to which statistics from CXGCICS are sent. 4 CSSL
TRACE Whether or not trace entries should be issued. Valid values are YES or NO. --- YES
TRACEEXCEPTION Whether or not exception trace entries should be issued. Valid values are YES (issue exception trace entries) or NO (do not issue exception trace entries). --- YES
TRACELEVEL1 The trace point number to be used, when issuing Level 1 trace records. Valid values range from 0 through 199. A value of 0 (zero) forces unique trace point numbers to be used. --- 0
TRACELEVEL2 The trace point number to be used, when issuing Level 2 trace records and for trace exception records. Valid values range from 0 through 199. A value of 0 (zero) forces unique trace point numbers to be used. --- 0

CXGMSRV Macro

One or more CXGMSRV macros can be specified in the CXGCIOPT module. CXGMSRV macro entries define server entries for the ConnecX Multiclient Subsystem (CXGSERV) component of the ConnecX SQL Gateway as well as JDBC server entries for CONNX JDBC Server.

  • Server definitions with TYPE=CXG define CXGSERV servers that will be used by a specific CICS system. The assignment is by CICS system ID.

  • Server definitions with TYPE=CXX define JDBC servers that will be used by a specific CICS system. The assignment is by CICS system ID.

This section covers the following topics:

Requirements and Restrictions

The following requirements and restrictions must be met when specifying server entries in CXGCIOPT:

  • A default entry for each server type (CXG and CXX) must be provided.

  • Multiple CXGMSRV entries for each server type are allowed. But a maximum of one entry per system ID is permitted.

  • The JDBC hostname DISTRIBUTE syntax is allowed (up to 255 characters). This feature is only available for server definitions of TYPE=CXX .

CXGMSRV Parameters

The following table describes the parameters that can be set by the CXGMSRV macro.

Parameter Description Length Default
DESCRIPTION The description of the server definition. There are no restrictions to the characters used in this description, but a maximum of 58 characters can be specified. 58 ---
HOSTNAME The host name or IP address of the server. Server lists, defining multiple JDBC servers, are supported. T

he syntax is described in Server List Syntax.

--- ---
PORT The port number of the service on the server named in the HOSTNAME parameter. Default port numbers for the different server types are:

  • CXG: no default port number

  • CXX: 7500

Note:
The PORT parameter must be omitted when a server list is provided in the HOST parameter.

4 ---
SYSID The name of the CICS system for which the definition applies. This parameter is optional. 8 ---
TYPE The type of server definition being specified. Valid values are "CXG" (for CXGSERV server definitions) and "CXX" (for JDBC server definitions). --- ---

CXGMTRAN Macro

One or more CXGMTRAN macros can be specified in the CXGCIOPT module. CXGMTRAN macro entries allocate resources to a CICS transaction or application. These resources are used during CONNECT processing and include the JDBC data source name (DSN) assignment and user identification schema.

Note:
A definition for the service transaction (UQST) is required. The service transaction (UQST) monitors the availability of the JDBC server and requires connection information. This can be provided via the mandatory DEFAULT entry or in an optional entry for the transaction UQST.

This section covers the following topics:

Requirements and Restrictions

The following requirements and restrictions must be met when specifying transaction or application entries in CXGCIOPT:

  • A default transaction entry must be specified.

  • Multiple CXGMTRAN entries are allowed. But a maximum of one entry per transaction is permitted.

CXGMTRAN Parameters

The following table describes the parameters that can be set by the CXGMTRAN macro.

Parameter Description Length Default
AUTH The password associated with the ID specified by the AUTHID parameter. 8 ---
AUTHID The ID to be used when the AUTHTYPE parameter is set to "AUTHID". The authorization is ciphered using a public/private key pair. The password associated with the AUTHID is specified in the AUTH parameter.

Note:
Tokens defined in the Access Control Table may be entered.

8 ---
AUTHTYPE The type of ID that can be used for the transaction. Valid values are USERID, GROUPID, AUTHID, SIGNID, or TX:

  • USERID: The user ID associated with the CICS transaction should be used as the resource authorization ID. If the user ID is less than eight characters long, it is padded on the right with blanks.

  • GROUPID: The group ID associated with the user session should be used as the resource authorization ID. If the ID is less than eight characters long, it is padded on the right with blanks.

  • AUTHID: The value of the AUTHID parameter should be used as the resource authorization ID.

  • SIGNID: The SIGNID attribute of the connection definition (defined by the CXGMCONN macro) should be used as the resource authorization ID.

  • TX: The transaction ID should be used as the resource authorization ID. The four-character transaction ID is padded on the right with blanks to for the eight-character authorization ID.

Note:
If you are using RACF for some or all security checking in the address space, use the GROUP, SIGNID, or USERID options. One of these options must be used in this circumstance because only threads defined with these options pass the required RACF access control environment element (ACEE).

--- USERID
DSN The data source name (DSN) to be used for the transaction. 32 ---
NAME The four-byte transaction name. Use the name DEFAULT to specify a default transaction entry. One DEFAULT transaction entry is required. 4 DEFAULT
OPTIONS Additional options that should be appended to the server identifier in the CONNECT statement. The following are valid options:

  • APPLICATION=ONDEMAND: Indicates that the database should only be connected to on demand (when accessed).

  • APPLICATION=ALL: Indicates that access to all databases should be available when the session starts.

  • APPLICATION=dbname: indicates that connection to the specified database should be available when the session starts.

--- ---
RMI How connections to the Adabas SQL Gateway will be managed. Valid values are ESQ or YES:

  • ESQ: CXGCICS should manage the connection to the Adabas SQL Gateway and process CICS Syncpoint Manager requests. Attempts to execute a CONNECT or DISCONNECT statement will result in an SQLCODE (-30175). The ROLLBACK and COMMIT statements will be executed.

  • YES: CXGCICS should manage the connection to the Adabas SQL Gateway and process CICS Syncpoint Manager requests. Attempts to execute a CONNECT or DISCONNECT statement will result in an SQLCODE (-30175). The ROLLBACK and COMMIT statements will also result in an SQLCODE (-30176).

ESQ Migration Tip: The RMI setting ESQ is intended as a migration aid and should only be used temporarily. Please modify the CICS application replacing the ROLLBACK and COMMIT statements with the appropriate EXEC CICS SYNCPOINT commands and then change the RMI setting to YES. 		--- ESQ

CXGMJOB Macro

Use of this macro is optional. These macro entries are only used during CONNECT processing by the ConnecX Connect Manager (CXGCONM).

One or more CXGMJOB macros can be specified in the CXGCIOPT module. CXGMJOB macro entries allocate resources to a batch job (for example, the JDBC DSN and the user identification schema).

This section covers the following topics:

Requirements and Restrictions

The following requirements and restrictions must be met when specifying transaction or application entries in CXGMJOB:

  • A default job entry must be specified.

  • Multiple CXGMJOB entries are allowed. But a maximum of one entry per job ID is permitted.

CXGMJOB Parameters

The following table describes the parameters that can be set by the CXGMJOB macro.

Parameter Description Length Default
AUTH The password associated with the ID specified by the AUTHID parameter. 8 ---
AUTHID The ID to be used when the AUTHTYPE parameter is set to "AUTHID". The authorization is ciphered using a public/private key pair. The password associated with the AUTHID is specified in the AUTH parameter.

Note:
Tokens defined in the Access Control Table may be entered.

8 ---
AUTHTYPE The type of ID that can be used for the job. Valid values are USERID, JOBNAME, JOBID, AUTHID, or SIGNID:

  • USERID: The user ID associated with the job should be used as the resource authorization ID. If the user ID is less than eight characters long, it is padded on the right with blanks.

  • JOBNAME: The job name attribute of the job should be used as the resource authorization ID.

  • JOBID: The job ID attribute of the job should be used as the resource authorization ID. If the ID is less than eight characters long, it is padded on the right with blanks.

  • AUTHID: The value of the AUTHID parameter should be used as the resource authorization ID.

  • SIGNID: The SIGNID attribute of the connection definition (defined by the CXGMCONN macro) should be used as the resource authorization ID.

Note:
If you are using RACF for some or all security checking in the address space, use the AUTHID, SIGNID, or USERID options. One of these options must be used in this circumstance because only threads defined with these options pass the required RACF access control environment element (ACEE).

--- USERID
DSN The data source name (DSN) to be used for the job. 32 ---
NAME The eight-byte job ID. Use the name DEFAULT to specify a default job ID entry. One DEFAULT job ID entry is required. 4 DEFAULT
OPTIONS Additional options that should be appended to the server identifier in the CONNECT statement. The following are valid options:

  • APPLICATION=ONDEMAND: Indicates that the database should only be connected to on demand (when accessed).

  • APPLICATION=ALL: Indicates that access to all databases should be available when the session starts.

  • APPLICATION=dbname: indicates that connection to the specified database should be available when the session starts.

--- ---

CXGMCODE Macro

Use of this macro is optional. When provided, these macro entries are used to translate SQLCODEs both by the ConnecX Attachment Facility (CXGCICS) and by the ConnecX Connect Manager (CXGCONM). Code translation is only performed on the following values: SQLCODE, SQLSTATE, and SQLCA. The values returned by the GET DIAGNOSTICS statement are not translated.

One or more CXGMCODE macros can be specified in the CXGCIOPT module. CXGMCODE macro entries define a translation table between Adabas SQL Gateway codes and DB2 codes.

This section covers the following topics:

Requirements and Restrictions

While the use of CXGMCODE is optional, when it is specified, the CXGCODE module must be included in the ACECALL module. The ACECALL module contains the modules CXGCONM and CXGCODE after the installation of CXGCONM. For more information, read Installing and Configuring CXGCONM.

CXGMCODE Parameters

The following table describes the parameters that can be set by the CXGMCODE macro.

Parameter Description Length Default
<code> The Adabas SQL Gateway SQLCODE to be translated. --- ---
REASONCODE The DB2 reason code to be used for the translation. This is an optional parameter. --- ---
SQLCODE The DB2 SQLCODE to which the Adabas SQL Gateway code should be translated. --- ---
SQLSTATE The DB2 SQLSTATE to be used for the translation. This is an optional parameter. --- ---

CXGMEND Macro

Use of the CXGMEND macro is mandatory. Only one CXGMEND macro may be specified and it must be the last entry in the CXGCIOPT module.

The CXGMEND macro performs validation checks on the other configuration definitions to ensure completeness.

CXGCIOPT Module Sample

Here is an example of a CXGCIOPT module:

CXGCIOPT CXGMCONN NAME=DEFAULT,          Connection Name               X
            ABCODE=UQ,                   ABEND Prefix                  X
            CONNECTERROR=SQLCODE,        Connection Error              X
            MSGDESTINATION=BOTH,         Message Destination           X
            MSGQUEUE1=CSSL,              TD Queue Message 1            X
            STATSQUEUE=CSSL,             TD Queue Statistics           X
            STANDBYMODE=RECONNECT,                                     X
            SIGNID=,                                                   X
            TRACELEVEL1=198,             Range: 0 to 199               X
            TRACELEVEL2=199,             Range: 0 to 199               X
            TRACEEXCEPTION=NO,                                         X
            DESCRIPTION='this is a Descriptive Text'                    
                                                                        
         CXGMSRV SYSID=DEFAULT,TYPE=CXF,HOSTNAME=host.cxg,PORT=1234     
         CXGMSRV SYSID=DEFAULT,TYPE=CXX,HOSTNAME=host.jdbc,PORT=5678    
                                                                        
         CXGMTRAN NAME=UQST,                                           X
            AUTHTYPE=AUTHID,                                           X
            AUTHID=userid,                                             X
            AUTH=password,                                             X
            DSN=dsname,                                                X
            OPTIONS='APPLICATION=ONDEMAND'                             
                                                                       
         CXGMTRAN NAME=DEFAULT,DSN=mydsn                               
                                                                       
         CXGMJOB NAME=DEFAULT,DSN=mydsn                                
                                                                       
         CXGMCODE -9,                                                  X
            SQLCODE=-911,                                              X
            SQLSTATE=HY000,                                            X
            TEXT='TIMEOUT OCCURRED WHILE PROCESSING UNIT OF WORK'      
                                                                       
         CXGMEND

Configuring the Access Control Table (CXGCIACF)

Use of the Access Control Table (CXGCIACF) is optional. When present, it is loaded and processed during PLT initialization.

Each macro definition in the source module CXGCIACF of TYPE=ENTRY defines a security token that is used in one or more transaction definitions (CXGMTRAN) or job definitions (CXGMJOB) in the runtime options module CXGCIOPT. A security token can either be used as a value for the AUTHID or for the AUTH parameter in the CXGMTRAN or CXGMJOB macros.

You must modify this to source module to meet the requirements of your installation. The following table summarizes the macro entries you will find in the CXGCIACF module:

Macro Description Occurrence
CXGMACF TYPE=CSECT ConnecX Attachment Facility (CXGCICS) access control tokens First entry
CXGMACF TYPE=ENTRY Access Token definition One or more entries

This section covers the following topics:

CXGMACF Macro

The CXGMACF macro is used in two different manners in the CXGCIACF module:

  • CXGMACF TYPE=CSECT: This macro entry must be the first entry in the CXGCIACF module. Only one CXGMACF TYPE=CSECT macro entry can be specified in the CXGCIACF module

  • CXGMACF TYPE=ENTRY: There may be one or more of these entries in the CXGCIACF module.

Each of these entries define a security token. The following table describes the parameters that can be set by the CXGMACF macro.

Parameter Description Length Default
TYPE Defines the type of table entry that is to be created. Valid values are CSECT and ENTRY:

  • CSECT: This entry initializes the Access Control Table and must be the first entry in CXGCIACF.

  • ENTRY: Each entry with this type defines an individual security token in the access control table.

--- ENTRY
NAME The identifier of the security token in the access control table. The value must be unique.

This identifier can be used as a value for either the AUTH or the AUTHID parameter in the CXGMTRAN or CXGJOB macro definitions in the runtime options in the CXGCIOPT module.

Note:
The values entered here are case-sensitive.

8 ---
VALUE The value associated with the security token. This value is encrypted.

Note:
The values entered here are case-sensitive.

8 ---

CXGCIACF Module Sample

Here is an example of a CXGCIACF module: 

CXGCIACF CXGMACF TYPE=CSECT       
*
TK00001  CXGMACF  TYPE=ENTRY,                                          X
               NAME=tk00001,                                           X
               VALUE=myuid
*
TK00815  CXGMACF  TYPE=ENTRY,                                          X
               NAME=tk00815,                                           X
               VALUE=mypsw

         END

Here is an example showing how the security tokens are used in the CXGMTRAN macro in the CXGCIOPT module: 

TXUQT0   CXGMTRAN  NAME=UQT0,                                          X
               AUTHTYPE=AUTHID,                                        X
               AUTHID=tk00001,          (ACF: User ID)                 X
               AUTH=tk00815,            (ACF: Password)                X
               DSN=mydsn