Standard CICS Interface

The standard CA IDMS interface requires CICS at a version level that is supported by IBM. Additionally, CA IDMS requires a minimum CICS level as follows:
idms19
The standard CA IDMS interface requires CICS at a version level that is supported by IBM. Additionally, CA IDMS requires a minimum CICS level as follows:
  • CICS Transaction Server for z/OS V3.1
  • CICS Transaction Server for z/VSE V1.1.1
Check ca.com/support for compatibility with later releases of CICS.
A standard site-specific CICS interface is generically referred to as IDMSINTC throughout this document. A basic site-specific version of the standard CICS interface program is installed and configured during installation. That basic version is linked as z/OS load module or z/VSE phase IDMSINTC. Other versions of the interface module can be created and configured with site-selected names. Normally, a separate z/OS load module or z/VSE phase is required for each CA IDMS central version that is to be accessed. If the proper options are chosen, a single version of the site-specific interface can be used to access a given CA IDMS central version from multiple CICS regions.
Each site-specific CICS interface load module or phase is composed of several precompiled objects as well as an options table that is compiled on site during the installation process as follows:
  • The CICSOPT macro is compiled onsite and provides a table of your selected options. The macro for the basic version of the interface is compiled during installation.
  • IDMSCSTB is a Stub module that contains minimal code to access a common CICS interface module, IDMSCCMN. The Stub module provides a linkage between the CICSOPT options table and the common module.
  • IBM supplied CICS interface modules DFHEAI and DFHEAI0.
  • An optional OPTIXIT.
  • An optional OPTIQXIT.
  • An optional USRIDXIT. For more information see the section USRIDXIT.
For more information on the OPTIXIT and OPTIQXIT parameters, see the CICSOPT Parameters.
If maintenance is applied to IDMSCCMN, it is not necessary to recompile or relink any site-specific interface modules. A new site-specific interface would only be needed to implement new or different options.
Each interface module must be defined in the CICS CSD. The program name is automatically detected and used at runtime to establish a TRUE (Task Related User Exit).
IDMSINTC interface requirements
The following requirements must be observed when using the IDMSINTC interface:
  • Ensure that every CICS system has a consistent and unique identifier. You can do this by changing TPNAME parameters or by specifying a CICS_NAME SYSIDMS parameter.
  • If you use the auto-commit feature to commit your CA IDMS database transactions through a CICS syncpoint operation, you must take additional steps to implement two-phase commit support between CICS and CA IDMS For more information, see Two-Phase Commit Support with CICS.
    This requirement also applies to CA IDMS VSAM Transparency users.
  • Install the CA IDMS entity definitions into the CICS CSD. These definitions are contained in the CAGJSRC library member CICSCSD. Consult the appropriate IBM documentation to ensure that these definitions take precedence over any previously installed definitions for the corresponding entities.
  • You can no longer use macro-level CICS programs to access CA IDMS.
  • Ensure that the DFHRPL concatenation in the CICS startup JCL contains the IDMS custom.loadlib and CAGJLOAD libraries.
IDMSINTC Startup
When the IDMSINTC program is started, through the PLT or by invoking its associated TRANSID, it performs the following functions:
  • Stores the address of the IDMSINTC entry point address in the CWA
  • Reads any SYSCTL files, specified or implied, by the CICSOPT SYSCTL and MAXCVNO parameters
  • Establishes the CA IDMS front-end runtime environment
  • If using CICS Transaction Server with two-phase commit enabled for IDMSINTC, and there are outstanding units of work (UOW) at CICS startup, resynchronization processing is initiated to ensure database integrity.
It is recommended that the same TPNAME value be specified or defaulted for all IDMSINTC interfaces used in a single CICS region. If different TPNAME values are used in two IDMSINTC interfaces in the same region, the CICS startup JCL must contain a SYSIDMS parameter that specifies a
CICS_NAME
value.
IDMSINTC
Automatically starting IDMSINTC
It is useful to have the IDMSINTC interface module started automatically at CICS startup. To do this, perform the following steps:
  1. Code the following entry for IDMSINTC in the program list table. The IDMSINTC entry should follow the one for DFHDELIM so that IDMSINTC is executed during phase 3 of CICS initialization.
    DFHPLT TYPE=ENTRY PROGRAM=IDMSINTC
  2. Enter the name of the program list table (PLTPI) in the system initialization table.
If you do not have IDMSINTC started as a function of the CICS startup routine, be sure to execute the IDMSINTC interface module before attempting communication with DC/UCF at runtime. To execute the IDMSINTC module, enter a TRANSID that corresponds to the IDMSINTC module in the PCT tables.
To start up IDMSINTC automatically
after
control is given to CICS, perform the following steps:
  1. Code the following operands on the CICSOPT macro:
    PLT=NO, TRANSID=
    task-code
  2. Perform steps 1 and 2 above and define
    task-code
    in the program control table (PCT) to invoke IDMSINTC.
For more information on the PCT table, see UCF Operations.
Runtime processing
IDMSINTC must be resident in CICS and must be executed before the execution of any CA IDMS database application for that instance of the CICS region.
Application processing
When an application program accesses a back-end DC/UCF system, control is passed to the IDMSCINT module linked with the program. Using the CWADISP value, IDMSCINT determines the address of the appropriate entry point in the IDMSINTC interface.
IDMSINTC performs the following functions:
  • Allocates dynamic storage required by the CA IDMS interface to service the request.
  • Enables the recovery exit program for the current CICS task. The exit program, IDMSTRUE, performs the necessary cleanup when the CICS task terminates.
    For more information on IDMSTRUE, see
    IDMSTRUE exit
    .
  • Passes control to CA IDMS, which sends the request to the DC/UCF region. The CA IDMS interface implicitly issues a CICS WAIT command, which places the current task in a wait state until the request is serviced.
  • Passes the requested database record and/or error status to the user program.
For more information on runtime processing, see What Happens when a CA IDMS Instruction is Executed.
IDMSTRUE exit
IDMSTRUE is a task termination exit, which is defined to CICS as a Task Related User Exit (TRUE).
IDMSTRUE features include the following:
  • Standard CICS facilities (that is, it doesn't modify CICS control programs)
  • Minimal overhead; IDMSTRUE gets control only for tasks performing CA IDMS database calls.
At task termination, IDMSTRUE detects the following conditions:
  • Transactions still active at abnormal task termination. When IDMSTRUE detects this condition, database updates associated with the transaction are backed out immediately. This conserves the resources that would be held until the IDMS EXTERNAL WAIT INTERVAL expires or the DC/UCF system is recycled.
    To monitor transactions active at abnormal task termination, use the DFHPEP examiner or the SCP user-exit examiner.
  • Transactions still active at normal task termination.
    This condition usually indicates a program logic error. That is, the program issued a BIND but never issued a FINISH. When IDMSTRUE detects this condition, database updates associated with the BIND are backed out immediately. This conserves the resources that would be held until the IDMS EXTERNAL WAIT INTERVAL expires or the DC/UCF system is recycled.
    The action described previously can be modified through the use of the AUTOCMT, AUTONLY, ONBACK, and ONCOMT parameters. For more information on these options, see
    CICSOPT syntax
    parameters and the IDMSINTC macro.
Transparency applications do not explicitly issue the BIND RUN-UNIT and FINISH. Rather, a Transparency transaction's first request results in an implicit BIND RUN-UNIT. IDMSTRUE issues an implicit FINISH when the task terminates.
CICSOPT Syntax
►►─┬───────────────┬─ CICSOPT CWADISP=
cwa-intc-address-disp
──────────────────► ├─
module-name
─┤ └─ CICSOPTS ◄───┘ ►─ ,OPSYS=
operating-system
──────────────────────────────────────────────────► ►─┬──────────────────────────────────────────────┬───────────────────────────► └─ ,AUTOCMT=─ ( ┬─ ON ──┬─┬───────────────┬ ) ─┘ └─ OFF ─┘ ├─ ,ALWAYS ─────┤ └─ ,DEFAULT ◄───┘ ►─┬──────────────────────────────────────────────┬───────────────────────────► └─ ,AUTONLY=─ ( ┬─ ON ──┬─┬───────────────┬ ) ─┘ └─ OFF ─┘ ├─ ,ALWAYS ─────┤ └─ ,DEFAULT ◄───┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ ,CVNUM= ─┬─
cv-number
─┤ └─ 0 ◄────────┘ ►─┬───────────────────────────────────────┬──────────────────────────────────► └─ ,DBNAME=(
db-name
─┬─ ,ALWAYS ─┬─ ) ─┘ └─ ,DEFAULT ◄┘ ►─┬────────────────────────────────────────┬─────────────────────────────────► └─ ,DBUGDCT= ( ┬─ DBUG ◄────────────┬ ) ─┘ └─
destination-name
─┘ ►─┬───────────────────────────┬──────────────────────────────────────────────► └─ ,DEBUG= ─ ( ┬─ YES ─┬ ) ─┘ ├─ NO ◄─┤ └─ QTS ─┘ ►─┬─────────────────────────────┬────────────────────────────────────────────► └─ ,DICTNAM=
dictionary-name
─┘ ►─┬─────────────────────────────┬────────────────────────────────────────────► └─ ,DICTNOD=
dictionary-node
─┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,DL1MAC= ─┬─ YES ─┤ └─ NO ◄─┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,DSECT= ─┬─ YES ◄─┤ └─ NO ───┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ ,ERRDCT= ─┬─
destination-name
─┤ └─ CSMT ◄────────────┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,ESCDLI= ─┬─ YES ─┤ └─ NO ◄─┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,EXTXIT= ─┬─ YES ─┤ └─ NO ◄─┘ ►─┬──────────────────┬───────────────────────────────────────────────────────► └─ ,HLPI= ─┬─ YES ─┤ └─ NO ◄─┘ ►─┬─────────────────────┬────────────────────────────────────────────────────► └─ ,MACLVL= ─┬─ YES ──┤ └─ NO ◄──┘ ►─┬─────────────────────────────────────────┬────────────────────────────────► └─ ,MAXCVNO= ──┬─
additional-sysctl-cnt
──┤ └─ 0 ◄─────────────────────┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ ,MAXCON=
maximum-connections
─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ ,MAXIDMS=
maximum-IDMS-systems
─┘ ►─┬─────────────────────────────────────────┬────────────────────────────────► └─ ,NODENAM=(
nodename
─┬─ ,ALWAYS ─┬─ ) ─┘ └─ ,DEFAULT ◄┘ ►─┬───────────────────────────────────────────────────────────┬──────────────► └─ ,ONBACK=─ ( ┬─ ROLLBACK ◄─────────┬─┬───────────────┬ ) ─┘ └─ ROLLBACK-CONTINUE ─┘ ├─ ,ALWAYS ─────┤ └─ ,DEFAULT ◄───┘ ►─┬───────────────────────────────────────────────────────────┬──────────────► └─ ,ONCOMT=─ ( ┬─ COMMIT-CONTINUE ───┬─┬───────────────┬ ) ─┘ ├─ COMMIT-ALL ────────┤ ├─ ,ALWAYS ─────┤ └─ FINISH ◄───────────┘ └─ ,DEFAULT ◄───┘ ►─┬─────────────────────┬────────────────────────────────────────────────────► └─ ,OPTIXIT= ─┬─ YES ─┤ └─ NO ◄─┘ ►─┬──────────────────┬───────────────────────────────────────────────────────► └─ ,PLT= ─┬─ YES ◄─┤ └─ NO ───┘ ►─┬──────────────────────────────────┬───────────────────────────────────────► └─ ,RSYNTXN=
rsyn-transaction-name
─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,SVC= ─┬─
svc-number
─┤ └─ NO ◄────────┘ ►─┬───────────────────┬──────────────────────────────────────────────────────► └─ ,SYSCTL=
ddname
─┘ ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ ,TIMEOUT= ─┬─
number-of-minutes
──┤ ├─ 0 ──────────────────┤ └─ IMMEDIATE ◄─────────┘ ►─┬───────────────────────┬──────────────────────────────────────────────────► └─ ,TPNAME=
system-name
─┘ ►─┬───────────────────────┬──────────────────────────────────────────────────► └─ ,TRANSID=
task-code
─┘ ►─┬──────────────────────────┬───────────────────────────────────────────────► └─ ,TRUE=
true-prefix-name
─┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─ ,TRUEAPI= ( ┬─ CICS ─┬ ) ─┘ └─ OPEN ─┘ ►─┬───────────────────────────────────────────────┬──────────────────────────► └─ ,TXNSHR=─ ( ┬─ ON ────┬─┬───────────────┬ ) ─┘ └─ OFF ◄──┘ ├─ ,ALWAYS ─────┤ └─ ,DEFAULT ◄───┘ ►─┬────────────────────────────────────────────┬─────────────────────────────► └─ ,UOWID= ──┬─ YES ─┤ └─ NO ◄─┤ ►─┬────────────────────────────────────────────┬─────────────────────────────► └─ ,USERCNT= ──┬─
max-concurrent-CICS-tasks
─┤ └─ 100 ◄──────────────────────┘ ►─┬────────────────┬─────────────────────────────────────────────────────────►◄ └─ ,XA= ─┬─ YES ─┤ └─ NO ◄─┘
The following parameters are for use in a CICSOPT module tailored for SQL:
  • DICTNAM
  • DICTNOD
CICSOPT Parameters
  • module-name
    Identifies the CSECT name of the generated module. The default is CICSOPT.
  • CWADISP
    Identifies the displacement within the CICS CWA of a fullword containing the address of an entry point within the CICSOPT module.
    • cwa-intc-address-disp
      cwa-intc-address-disp
      must specify an integer representing an offset within the CWA. The lowest allowable value is zero. The highest allowable value is 4 less than the size of the CWA. This displacement within the CWA must not be used for any other purpose by any CICS application. The value specified must begin on a fullword boundary and be the same value that is specified in the CWADISP parameter of the IDMSCINT macro.
  • OPSYS
    Identifies the operating system under which the DC/UCF (or CICS) system will run.
    • operating-system
      The valid values are the following:
      • OS390
      • MVS
      • VSE
      • DVS
      • DOS
      • DOSVS
  • AUTOCMT
    Specifies whether database sessions opened by a program using this interface module are eligible for participation in a CICS UOW (Unit of Work).
    • ON
      Specifies that database sessions are eligible to participate in a CICS unit of work (UOW). If the database session is active at the time a CICS syncpoint operation is performed, the session's updates are committed as part of the CICS UOW.
    • OFF
      Specifies that database sessions are not eligible to participate in a CICS unit of work (UOW).
      If TXNSHR=ON is specified, the default for AUTOCMT is ON; otherwise it is OFF. An assembly error results if TXNSHR=ON and AUTOCMT=OFF are specified.
      ALWAYS Specifies that the AUTOCMT behavior specified in the CICSOPT parameter overrides whatever was specified in the IDMSCINT module with which the application is linked.
      DEFAULT Specifies that the AUTOCMT behavior specified in the CICSOPT parameter applies only if the corresponding IDMSCINT parameter specifies DEFAULT. This is the default.
  • AUTONLY
    Specifies if database sessions opened by a program using this interface module are forced to participate in a CICS UOW.
    • ON
      Specifies that database sessions are forced to participate in a CICS Unit Of Work (UOW). Even if the database session is terminated prior to the CICS syncpoint operation, the session's updates are committed as part of the CICS UOW. DML commands that would normally cause the session's updates to be committed (such as FINISH or COMMIT WORK) have no impact on the session's transaction, although they do impact the session. Conversely, if the session's transaction is forced to back out (either because of a DML ROLLBACK request or because of events such as a deadlock), a CICS SYNCPOINT BACKOUT is issued forcing the entire CICS UOW to be backed out.
    • OFF
      Specifies that database sessions are not forced to participate in a CICS Unit Of Work (UOW).
      If TXNSHR=ON is specified, the default for AUTONLY is ON; otherwise it is OFF. An assembly error results if TXNSHR=ON and AUTONLY=OFF are specified.
      ALWAYS Specifies that the AUTONLY behavior specified in the CICSOPT parameter overrides the specifications in the IDMSCINT module with which the application is linked.
      DEFAULT Specifies that the AUTONLY behavior specified in the CICSOPT parameter applies only if the corresponding IDMSCINT parameter specifies DEFAULT. This is the default.
  • CVNUM
    Identifies the number of the DC/UCF system to be accessed from CICS.
    • cv-number
      For
      cv-number
      , specify the number used for the CVNUM parameter in the system definition of the DC/UCF system.
  • DBNAME
    Identifies the database (or data dictionary) name to be contained in the CICSOPT module. This parameter also identifies the conditions under which programs signing on to the DC/UCF system access the named database. This parameter has no effect on SQL database sessions. For SQL sessions, see the DICTNAM parameter.
    • db-name
      For
      db-name
      , specify the name of the database that programs are to access when running under the DC/UCF system. If the database name is not specified, DC/UCF obtains the appropriate database name from the application program or from the SYSCTL file (z/OS only).
      ALWAYS Indicates that
      db-name
      is to override any database named by the program. Programs signing on to DC/UCF always execute against the named database regardless of database name specifications made by the program.
      DEFAULT Indicates that programs signing on to DC/UCF are to execute against the named database only if the program does not name a database.
Under z/OS and z/VSE, SYSCTL database name specifications can override CICSOPT and program specifications.
  • DBUGDCT
    Identifies the CICS transient data or temporary storage destination to use as the target for error messages produced if DEBUG=YES or DEBUG=QTS is specified. This is also the CICS transient data or temporary storage destination to use as a target for application tracing that is enabled using the SYSIDMS parameter IDMSIN01_ONLY.
    • destination-name
      The default
      destination-name
      is DBUG. Use another destination if you want to route diagnostic messages to another CICS destination. If DEBUG=YES is specified, the DCT entry should be defined with a variable length record of at least 136 characters. We recommend that you use the values provided in source library member CICSCSD.
  • DEBUG
    Specifies whether IDMSINTC produces extra debugging information on internal processing.
    • YES
      Specifies that IDMSINTC produces extra information. This information is written using WRITEQ TD to the destination specified on the DBUGDCT parameter.
    • NO
      Specifies that IDMSINTC does not produce debugging information. This is the default. You should always use DEBUG=NO unless otherwise requested by Technical Support to resolve a system problem.
    • QTS
      Specifies that IDMSINTC produces extra information. This information is written using WRITEQ TS to the queue specified on the DBUGDCT parameter.
  • DICTNAM
    dictionary-name
    Sets the dictionary to which an SQL session will be connected unless it is overridden by the application program. This parameter has no effect on non-SQL database sessions.
  • DICTNOD
    dictionary-node
    Sets the node to which an SQL session will be connected. This parameter has no effect on non-SQL database sessions.
  • DL1MAC
    Always NO. Provided solely for upward compatibility.
  • DSECT
    Specifies whether to generate a DSECT only version of the CICSOPT macro.
    The parameter defaults to YES. However, to generate a working CICS interface module, you must specify DSECT=NO in the assembly of CICSOPT.
  • ERRDCT
    Identifies the CICS transient data destination to use as the target for error messages produced by IDMSINTC and IDMSTRUE.
    • destination-name
      The default
      destination-name
      is CSMT. Use another destination if you want to route CA IDMS error messages to another CICS destination. The DCT entry should be defined with a logical record length of at least 130 characters.
  • ESCDLI
    Specifies whether DLI/T transparency is in use with this interface.
  • EXTXIT
    Specifies whether the IDMSINTC interface loads and calls the general use exits IDMSCEON and IDMSCEOX. The IDMSCEON exit is called before the requested IDMS function call is serviced. The IDMSCEOX exit is called immediately after the requested IDMS function call has been processed. The default is NO.
  • HLPI
    Specifies whether HLPI support is required for DL1.
  • MACLVL
    This parameter is obsolete. Macro level programs are no longer supported in CICS.
  • MAXCVNO
    additional-sysctl-cnt
    Specifies the number of additional SYSCTL DD cards that can be accessed through this interface. DDNAMEs for the additional SYSCTL files are derived by replacing the first blank or the last character (if all 8-bytes are in use) of the SYSCTL operand value by the numbers 1 through MAXCVNO.
  • MAXCON
    Specifies the maximum number of different back-end central versions that a CICS task can access simultaneously through this CICS interface module. This limit applies only to database sessions for which AUTOCMT is enabled. If an application uses different interface modules, each one has its own limit.
    • maximum-connections
      Must be a numeric value between 1 and 1000. If
      maximum-connections
      is not specified, the default maximum number of connections is 2.
  • MAXIDMS
    Specifies the maximum number of different back-end central versions that a CICS interface module can access throughout the life of a CICS system. This limit applies only to database sessions for which AUTOCMT is enabled. If an application uses different interface modules, each one has its own limit.
    • maximum-IDMS-systems
      Must be a numeric value between 1 and 1000. The default maximum number of back-end systems is the larger of 2 and 2 * the value of the MAXCVNO parameter.
  • NODENAM
    Identifies a system defined to the DC/UCF communications network to be contained in the CICSOPT module and the conditions under which programs signing on to the DC/UCF system will be directed to the named node for execution. This parameter has no effect on SQL database sessions. For SQL sessions, see the DICTNOD parameter.
    • nodename
      For
      nodename
      , specify the one- to eight-character name of a remote system. If
      nodename
      is not specified, the DC/UCF obtains the appropriate node name from the application program or from the SYSCTL file (z/OS only).
      ALWAYS Indicates that
      nodename
      is to override any node named by the program. Requests from programs signing on to DC/UCF are always directed to the named node regardless of node name specifications made by the program.
      DEFAULT Indicates that requests from programs signing on to DC/UCF are to be directed to the named node only if the program does not name a node.
    Note:
    Under z/OS and z/VSE, SYSCTL node name specifications can override CICSOPT and program specifications.
  • ONBACK
    Specifies the action that should be taken for database sessions opened by a program using this interface module when they participate in a CICS backout operation.
    • ROLLBACK
      Specifies that database sessions should be terminated. This is the default.
    • ROLLBACK-CONTINUE
      Specifies that database sessions should continue but currencies freed.
    • ALWAYS
      Specifies that the ONBACK behavior specified in the CICSOPT parameter overrides whatever was specified in the IDMSCINT module with which the application is linked.
    • DEFAULT
      Specifies that the ONBACK behavior specified in the CICSOPT parameter applies only if the corresponding IDMSCINT parameter specifies DEFAULT. This is the default.
  • ONCOMT
    Specifies the action that should be taken for database sessions opened by a program using this interface module when they participate in a CICS syncpoint operation.
    • COMMIT-ALL
      Specifies that database sessions should continue but currencies freed.
    • COMMIT-CONTINUE
      Specifies that database sessions should continue and currencies retained.
    • FINISH
      Specifies that database sessions should be terminated. This is the default.
    • ALWAYS
      Specifies that the ONCOMT behavior specified in the CICSOPT parameter overrides the specification in the IDMSCINT module with which the application is linked.
    • DEFAULT
      Specifies that the ONCOMT behavior specified in the CICSOPT parameter applies only if the corresponding IDMSCINT parameter specifies DEFAULT. This is the default.
  • OPTIXIT
    Indicates whether CICS transactions can modify the IDMSOPTI structure dynamically so that only the task thread is affected by the changes. YES indicates that the IDMSOPTI structure can be modified dynamically.
    IDMSINTC copies the static IDMSOPTI structure into dynamic storage and passes it to the user routine, which may alter it based on site-specific rules.
    For more information on the OPTIXIT user exit, see OPTIXIT.
  • PLT
    Indicates how IDMSINTC starts up.
    • YES
      Specifies that IDMSINTC can start up as a PLT-invoked program.
    • NO
      Specifies IDMSINTC always starts up as a user task once CICS start up is complete.
  • RSYNTXN
    Specifies the name of the CICS resynchronization transaction defined for this interface.
    • rsyn-transaction-name
      Must be the name of a transaction defined to CICS and associated with a resynchronization program. If not specified, the default transaction name is RSYN.
  • SVC
    Identifies the number of the CA IDMS SVC.
    • svc-number
      For
      svc-number
      , specify a value as follows:
      • If no SVC is being used, or if using SYSCTL, specify NO.
      • If an SVC is being used by the DC/UCF system, specify the SVC number.
      The SVC parameter is required if no SYSCTL file is specified.
  • SYSCTL
    ddname
    Identifies the
    ddname
    of the file containing DC/UCF system control information.
    If the SVC (described previously) is
    not
    specified, the SYSCTL parameter is required. Likewise, if SYSCTL is desired, the SVC parameter must be NO (SVC=NO).
  • TIMEOUT
    Indicates how long to hold a block of storage after termination of a CICS task that utilizes CA IDMS services. This storage block is acquired with a CICS GETMAIN and is initialized when a terminal makes a request for IDMS services.
    The valid values are as follows:
    • 0
      Specifies that once a block of storage is acquired for a particular CICS terminal that storage is not freed until one of the following occurs:
      • The user signs off the terminal.
      • A task aborts that is using that storage block.
    The following situations apply to the TIMEOUT parameter:
    • TIMEOUT=IMMEDIATE is recommended
      unless
      the IDMSINTC interface is used with SQL transactions that utilize SUSPEND/RESUME processing. These type of transactions require a TIMEOUT value other than IMMEDIATE.
    • TIMEOUT=IMMEDIATE must be specified for any IDMSINTC module that runs in a CICS Application Owning Region (AOR) and which is invoked from terminals in a separate Terminal Owning Region (TOR).
    • Since several thousand bytes are held by each terminal, a non-IMMEDIATE value may result in a large amount of storage being held for terminals with no active tasks.
    • A TIMEOUT value of 1 through 10 must
      not
      be coded if any application program using IDMSINTC services also uses READQ TS ... with the SET option.
    • If the INTCID parameter and/or the NTID parameter of the #UCFCICZ macro are not coded correctly or if the UCFCICZ exit is not driven for some other reason, the IDMS storage block may not be freed when a CICS user is logged off a terminal. The next user who signs on that terminal may acquire that storage block. This can result in S019 or other S0nn abends or other application problems. If such problems are encountered, use TIMEOUT=IMMEDIATE.
    • IMMEDIATE
      Specifies that the storage is freed at task termination of the task that acquired the storage. If IMMEDIATE is coded, a new storage block is acquired and initialized for each CICS task that requests CA IDMS services.
      This is the default.
    • number-of-minutes
      Specifies the number of minutes storage is held.
      number-of-minutes
      can range from 1 to 10. If another CA IDMS request is made within that time, the same block of storage is utilized. If the storage is not used within that time, it is freed. The next request for CA IDMS services results in the acquisition and initialization of a new storage block.
  • TPNAME
    system-name
    Specifies the name by which DC/UCF will identify all tasks running under this CICS system. For
    system-name
    , specify a four-character name.
    If TPNAME is omitted or the
    system-name
    is specified as spaces, the
    system-name
    defaults to the four-character local CICS system ID.
    The TPNAME value must be unique across all CICS systems that access any single central version. If more than one IDMSINTC interface is used within a CICS system, they should all specify the same value for TPNAME. Otherwise, a CICS_NAME SYSIDMS parameter must be used to provide a unique identifier for the CICS system.
    This name forms the first part of the local transaction ID for database requests and forms the first four characters of the front-end system ID for external request units. "BULK" is appended to the
    system-name
    to create the front-end system ID. The front-end system ID can be used:
    • To access front-end system table to determine the packet size for communications and the maximum number of simultaneous requests.
    • As an alternate task code for controlling external request unit processing
    Note:
    The front-end system ID is used by some Performance Monitor reports to determine the type of reporting to be done. Front-end systems with an ID which begins with "CI" are assumed to be CICS systems. Therefore, certain CICS statistics may not be reported if the front-end system ID is set to or defaults to a value which does not begin with CI.
  • TRANSID
    Identifies the transaction coded in the program control table (PCT) as invoking IDMSINTC.
    • task-code
      task-code
      must be the name of a task defined in the PCT table.
      Note:
      For more information on the PCT table, see UCF Operations.
  • TRUE
    Specifies a prefix to be used in forming Task Related User Exit (TRUE) entry names.
    • true-prefix
      Must be a one to five character value that is unique across all interface modules in use within a CICS system. If
      true-prefix
      is less than five characters, it is padded on the right with $'s. If not specified, the default prefix is constructed as the last five characters of the IDMSINTC module name, padded on the right with $'s if necessary.
  • TRUEAPI
    Specifies whether to enable the IDMS TRUE exit with the OPENAPI attribute.
    • CICS
      Specifies to enable the exit with the THREADSAFE attribute.
    • OPEN
      Specifies to enable the exit with the THREADSAFE and OPENAPI attributes.
  • TXNSHR
    Specifies whether database sessions opened by a program using this interface module should share the same transaction as other sessions started by the same CICS task.
    • ON
      Specifies that database sessions should share transactions.
    • OFF
      Specifies that database sessions should not share transactions. This is the default.
    • ALWAYS
      Specifies that the TXNSHR behavior specified in the CICSOPT parameter overrides whatever was specified in the IDMSCINT module with which the application is linked.
    • DEFAULT
      Specifies that the TXNSHR behavior specified in the CICSOPT parameter applies only if the corresponding IDMSCINT parameter specifies DEFAULT. This is the default.
    Note:
    For more information on transaction sharing, see the
    Database Administering section
    .
  • UOWID
    Indicates whether the IDMS interface should acquire the CICS transaction unit of work ID for Performance Monitor SMF230 job termination records.
  • USERCNT
    Specifies the maximum number of concurrent CICS tasks using the CA IDMS interface. Any task that attempts to access CA IDMS through the interface while at the maximum will be aborted with a K214 transaction abend.
    • max-concurrent-CICS-tasks
      Valid values are 1 to 100000. The default value is 100.
  • XA
    Designates whether the operating system is capable of processing XA addresses. If you specify YES, IDMSINTC allocates the primary user-oriented storage in the 31-bit storage area. This storage is retained across all successful task terminations for terminal-associated tasks, and this storage is reused on the next DC/UCF request. The storage is freed for any failing or non-terminal task.
    Note:
    The CICSOPT macro allows other parameters which are not documented in the previous section. Some of these parameters are obsolete and are supported solely to maintain upwardly compatible syntax. Others are relevant only to clients who have the Transparency Option for TOTAL, DL/I, or VSAM. Unless otherwise documented, parameters other than those shown do not have to be coded when invoking the CICSOPT parameter.
Parameter Considerations
Note:
The CICSOPT macro allows other parameters which are not documented in the previous section. Some of these parameters are obsolete and are supported solely to maintain upwardly compatible syntax. Others are relevant only to clients who have the Transparency Option for TOTAL, DL/I, or VSAM. Unless otherwise documented, parameters other than those shown do not have to be coded when invoking the CICSOPT parameter.
Create an IDMSINTC Interface Program
To create an IDMSINTC interface program under z/OS:
  1. Create a CICSOPT source module as follows:
GBLC & MODNAME &MODNAME SETC CICSOPT' CICSOPT cicsopt-parameters END
  1. Save the CICSOPT source module in your custom source library.
  2. Assemble and link the module into your custom load library by executing the z/OS Assemble and Link-Edit JCL.
  3. Substitute the name of your CICSOPT source member and insert the following binder statements:
    ORDER DFHEAI INCLUDE CUSTLIB(
    optixit
    ) (Optional) INCLUDE CUSTLIB(
    optiqxit
    ) (Optional) INCLUDE CUSTLIB(
    usridxit
    ) (Optional) INCLUDE CAGJLOAD(IDMSCSTB) ENTRY STARTUP SETOPT PARM(AMODE=31,RMODE=24,REUS=NONE) NAME idmsintc(R)
    • optixit
      Specifies the name of your OPTIXIT exit routine.
    • optiqxit
      Specifies the name of your OPTIQXIT exit routine.
    • usridxit
      Specifies the name of your USRIDXIT exit routine.
    • idmsintc
      Specifies the name of your IDMSINTC interface load module.
To create an IDMSINTC interface program under z/VSE:
  1. Assemble and catalog a CICSOPT options table using the sample JCL in the "z/VSE Assemble JCL" section of the "Sample z/VSE JCL" topic.
    Modify the JCL by substituting the following in place of the
    Assembler input statements
    :
    PUNCH 'CATALOG
    cicsopts
    .OBJ REPLACE=YES' CICSOPTS TITLE 'CA IDMS CICS OPTIONS MODULE' GBLC &MODNAME &MODNAME. SETC 'cicsopts’ CICSOPT cicsopt-parameters END
  2. Link the IDMSINTC interface program using the sample JCL in z/VSE Link JCL.
    Modify the JCL by substituting the following statements in place of the
    Linkage editor control statements
    :
    PHASE
    idmsintc
    ,* INCLUDE DFHEAI INCLUDE
    optiexit
    (Optional) INCLUDE
    optiqxit
    (Optional) INCLUDE
    usridxit
    (Optional) INCLUDE
    usridxit
    (Optional) INCLUDE
    cicsopts
    INCLUDE IDMSLST6 INCLUDE DFHEAI0 MODE AMODE(31),RMODE(24) ENTRY STARTUP
    • cicsopts
      Specifies the name you choose for your IDMSINTC options table.
      You can have more than one options table with different names.
    • idmsintc
      Specifies the name you choose for your IDMSINTC stub program.
      You can have more than one stub program with different names.
    • optixit
      Specifies the name of your OPTIXIT exit routine.
    • optiqxit
      Specifies the name of your OPTIQXIT exit routine.
    • usridxit
      Specifies the name of your USRIDXIT exit routine.
    • idmsintc
      Specifies the name of your IDMSINTC interface load module.
The IDMSCINT Application Stub Program
Each application program that accesses CA IDMS must be linked with an IDMSCINT stub program. The IDMSCINT stub program establishes communications with a particular IDMSINTC interface program. The CWADISP specified in the IDMSCINT stub program must match the CWADISP specified in the CICSOPT macro that is used when creating the IDMSINTC interface program. The following sections describe how to create an IDMSCINT application stub program.
IDMSCINT Syntax
To prepare an IDMSCINT macro, use the following syntax.
►►─┬───────────────┬─ IDMSCINT CWADISP=
cwa-intc-address-displacement
─────────► ├─
module-name
─┤ └─ IDMSCINT ◄───┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ ,AUTOCMT= ─┬─ ON ──────┤ ├─ OFF ─────┤ └─ DEFAULT ─┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ ,AUTONLY= ─┬─ ON ──────┤ ├─ OFF ─────┤ └─ DEFAULT ─┘ ►─┬─────────────────────┬────────────────────────────────────────────────────► └─ ,DML= ─┬─ YES ◄──┬─┘ └─ NO ────┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► └─ ,EP1=
first-entry-point-label
─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ ,EP2=
second-entry-point-label
─┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ ,EXEC= ─┬─ YES ◄──┬─┘ └─ NO ────┘ ►─┬──────────────────────────────────┬───────────────────────────────────────► └─ ,ONBACK= ─┬─ ROLLBACK ◄─────────┤ ├─ ROLLBACK-CONTINUE ─┤ └─ DEFAULT ───────────┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► └─ ,ONCOMT= ─┬─ COMMIT-CONTINUE ─┤ ├─ COMMIT-ALL ──────┤ ├─ FINISH ◄─────────┤ └─ DEFAULT ─────────┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,SQL= ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ ,SSC12= ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬─────────────────────────┬────────────────────────────────────────────────►◄ └─ ,TXNSHR= ─┬─ ON ───────┤ ├─ OFF ◄─────┤ └─ DEFAULT ──┘
IDMSCINT Parameters
This section details the IDMSCINT parameters.
  • module-name
    Identifies the CSECT name of the generated module.
  • CWADISP=
    cwa-intc-address-displacement
    Identifies the displacement within the CICS CWA of a fullword that holds the address of the IDMSINTC module. For
    cwa-intc-address-displacement
    , specify the same value given to the CWADISP operand of the IDMSINTC macro.
  • AUTOCMT
    Specifies whether database sessions opened by a program linked with this IDMSCINT module are eligible for participation in a CICS UOW (Unit of Work).
    • ON
      Specifies that database sessions are eligible to participate in a CICS Unit Of Work (UOW). If the database session is active at the time a CICS syncpoint operation is performed, the session's updates are committed as part of the CICS UOW.
    • OFF
      Specifies that database sessions are not eligible to participate in a CICS Unit Of Work (UOW).
    • DEFAULT
      Specifies that whether database sessions are eligible for participation in a CICS Unit Of Work (UOW) is determined by the AUTOCMT parameter of the interface's CICSOPT macro.
    If TXNSHR=ON is specified, the default for AUTOCMT is ON; otherwise it is OFF. An assembly error results if TXNSHR=ON and AUTOCMT=OFF are specified.
  • AUTONLY
    Specifies whether database sessions opened by a program linked with this IDMSCINT module are forced to participate in a CICS UOW.
    • ON
      Specifies that database sessions are forced to participate in a CICS Unit Of Work (UOW). Even if a database session is terminated prior to the CICS syncpoint operation, the session's updates are committed as part of the CICS UOW. DML commands that would normally cause the session's updates to be committed (such as FINISH or COMMIT WORK) have no impact on the session's transaction, although they do impact the session. Conversely, if the session's transaction is forced to back out (either because of a DML ROLLBACK request or because of events such as a deadlock), a CICS SYNCPOINT BACKOUT is issued forcing the entire CICS UOW to be backed out.
    • OFF
      Specifies that database sessions are not forced to participate in a CICS Unit Of Work (UOW).
    • DEFAULT
      Specifies that whether database sessions are forced to participate in a CICS Unit Of Work (UOW) is determined by the AUTONLY parameter of the interface's CICSOPT macro.
      If TXNSHR=ON is specified, the default for AUTONLY is ON; otherwise it is OFF. An assembly error results if TXNSHR=ON and AUTONLY=OFF are specified.
  • DML=YES|NO
    Determines whether the program linked with IDMSCINT can (YES) or cannot (NO) issue non-SQL DML statements. YES is the default.
  • EP1=
    first-entry-point-label
    Identifies the name of the first entry point in the generated module. For
    first-entry-point-label
    , specify the name of the first entry point. The default value is either the value given to
    module-name
    above or IDMSCINT if
    module-name
    is not specified.
  • EP2=
    second-entry-point-label
    Identifies the name of the second entry point in the generated module. For
    second-entry-point-label
    , specify the name of the second entry point.
    Second Entry Point Considerations
    • A second entry point is present only if the EXEC parameter described below specifies NO. In this case, if EP2 is not specified, the default value is IDMSINC2.
    • If the EXEC parameter is coded as YES, no second entry point is generated, and EP2 should not be specified.
  • EXEC=YES|NO
    Indicates whether the IDMSCINT module being generated is to be used with the CICS command-level interface.
    • YES
      Specify YES to indicate that the command-level interface is in use. YES is the default.
      If EXEC=YES, name the module IDMSCINT to allow it to be autolinked with applications.
    • NO
      Specify NO to indicate that the command-level interface is not in use. EXEC=NO must be specified if installing the CA IDMS DMS interface.
      If EXEC=NO, name the module IDMSINC1 to allow the use of autolink.
  • ONBACK
    Specifies the action that should be taken for database sessions opened by a program linked with this IDMSCINT module when they participate in a CICS backout operation.
    • ROLLBACK
      Specifies that database sessions should be terminated. This is the default.
    • ROLLBACK-CONTINUE
      Specifies that database sessions should continue but currencies freed.
    • DEFAULT
      Specifies that the backout action for sessions is determined by the ONBACK parameter of the interface's CICSOPT macro.
  • ONCOMT
    Specifies the action that should be taken for database sessions opened by a program linked with this IDMSCINT module when they participate in a CICS syncpoint operation.
    • COMMIT-ALL
      Specifies that database sessions should continue but currencies freed.
    • COMMIT-CONTINUE
      Specifies that database sessions should continue and currencies retained.
    • FINISH
      Specifies that database sessions should be terminated. This is the default.
    • DEFAULT
      Specifies that the commit action for sessions be determined by the ONCOMT parameter of the interface's CICSOPT macro.
  • SQL=YES|NO
    Determines whether the program linked with IDMSCINT can (YES) or cannot (NO) issue SQL DML statements. NO is the default.
  • SSC12=YES|NO
    Determines whether the application program contains a PROTOCOL statement that specifies SUBSCHEMA-NAMES LENGTH IS 18. If this is the case, specify YES.
    Specify NO if the application program contains a PROTOCOL statement that specifies SUBSCHEMA-NAMES LENGTH IS 16 or if the PROTOCOL statement does not contain a SUBSCHEMA-NAMES LENGTH clause.
    Default:
    NO
  • TXNSHR
    Specifies whether database sessions opened by a program linked with this IDMSCINT module should share the same transaction as other sessions started by the same CICS task.
    • ON
      Specifies that database sessions should share transactions.
    • OFF
      Specifies that database sessions should not share transactions. This is the default.
    • DEFAULT
      Specifies whether database sessions share transactions is determined by the TXNSHR parameter of the interface's CICSOPT macro.
    For more information on transaction sharing, see the
    CA IDMS Database Administering section
    .
The IDMSCINT macro allows other parameters which are not documented above. These parameters are obsolete and are supported solely to maintain upwardly compatible syntax. Always take the default values.
Assembling and Link Editing IDMSCINT
This section contains the JCL to assemble and link edit the IDMSCINT module for z/OS and z/VSE operating systems.
z/OS IDMSCINT assembly and link edit
To assemble and link end IDMSCINT
  1. Create a source module as follows:
    IDMSCINT idmscint-parameters END
  2. Save the source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-Edit JCL from the "Sample z/OS JCL" topic.
    Substitute the name of your source member and insert the following binder statement:
    NAME
    idmscint
    (R)
  4. Add the following statement to the link of each application program that accesses IDMS using this
    idmscint
    application stub program. The CWADISP specified in the IDMSCINT parameters must match the CWADISP specified in the CICSOPT parameters used in creating an IDMSINTC interface program:
    INCLUDE idmscint
    • idmscint
      Specifies the name of your IDMSCINT interface module.
z/VSE IDMSCINT assembly and link edit
To create an IDMSINTC interface program under z/VSE:
  1. Assemble and catalog an IDMSCINT program using the sample JCL from the "z/VSE Assemble JCL" section of the "Sample z/VSE" topic.
    Modify the JCL by substituting the following in place of the
    Assembler input statements
    :
    PUNCH 'CATALOG
    idmscint
    .OBJ REPLACE=YES' IDMSCINT idmscint-parameters END
  2. Add the following statement to the link of each application program that accesses IDMS using this
    idmscint
    application stub program. The CWADISP specified in the IDMSCINT parameters must match the CWADISP specified in the CICSOPT parameters used in creating an IDMSINTC interface program:
    INCLUDE idmscint
    • idmscint
      Specifies the name you choose for your IDMSCINT application stub program.
      You can have more than one application stub program with different names