IDMSINTL and IDMSCINL CICS Interface Macros

Contents
idms19
The functionality of the CICS IDMSINTL interface has been stabilized at the r16 level except that an optional OPTIXIT exit point was added. For the applications that use this interface, we recommend using the IDMSINTC interface instead. You do not have to change or relink the application programs that were using IDMSINTL to use IDMSINTC. You can create an IDMSINTC interface module by compiling a CICSOPT with the same invocation parameters as the IDMSINTL interface being replaced.
The IDMSINTL/IDMSCINL interface differs from the standard CICS interface (IDMSINTC/IDMSCINT) in the following ways:
  • Supports only native DML run-units using 16-character-format subschema controls. SQL, UCF, and Transparency interfaces remain available only through the standard interface.
  • An OPTIXIT is provided, but it has more limited capabilities than the OPTIXIT provided with for the IDMSINTC interface.
  • Each run-unit utilizes an ERE (External Request Element). The standard interface uses one ERE per CICS transaction regardless of the number of run-units bound by that transaction.
  • Task-level commands (COMMIT TASK, ROLLBACK TASK, FINISH TASK) are not supported.
  • CA IDMS load libraries are not required at runtime.
Because this interface offers a minimal subset of the features available through the standard interface, its resource requirements are therefore substantially reduced. Users with applications that demand no more than what this interface offers can use it in place of the standard interface to reduce resource consumption in the CICS system. Applications that need the full services of the standard interface can coexist freely in the same or different CICS systems.
IDMSINTL/IDMSCINL considerations
The following considerations apply to using IDMSINTL/IDMSCINL:
  • Multiple copies of IDMSINTL and IDMSCINL can coexist within a single CICS region, but each must be associated with a unique CWADISP.
  • Existing applications linked with a pre-12.0 version of IDMSCINT be executed with a Release 12.01 or higher version of IDMSINTC or IDMSINTL without relinking.
  • Programs that share a single Subschema Control (SSC) must be linked with the same IDMSCINT or IDMSCINL stub module, that is, you cannot mix invocations of IDMSINTC with IDMSINTL using the same SSC.
  • Programs linked with a pre-12.0 version of IDMSCINT or any other version of IDMSCINL can be executed using an IDMSINTC or IDMSINTL interface.
IDMSINTL
IDMSINTL is intended for applications that execute navigational DML (nDML) only. Applications that require the additional functionality such as SQL or mixed DML and SQL, must use IDMSINTC.
IDMSINTL contains an embedded TRUE exit that will abort (rollback) any un-FINISHed run-units at the end of the transaction, but does not provide AUTOCMT (CICS SYNCPOINT interception) as does the standard interface.
Functions IDMSINTL performs at CICS startup
The functions performed by IDMSINTL vary based on whether a CA IDMS SVC is specified in IDMSINTL as follows:
  • If a CA IDMS SVC
    is
    specified, IDMSINTL performs the following functions when CICS is started up:
    1. Stores the address of the IDMSINTL entry point address table in the CWA
    2. Returns control to CICS
  • If a CA IDMS SVC
    is not
    specified, IDMSINTL performs the following functions when CICS is started up:
    1. Opens and reads the SYSCTL file to obtain the necessary central version information (for example, the CVNUMBER value of the DC/UCF system and the CA IDMS SVC number)
    2. Stores the address of the IDMSINTL entry point address table in the CWA
    3. Returns control to CICS
Automatically starting IDMSINTL
It is useful to have the IDMSINTL interface module started automatically at CICS startup time. To do this, perform the following steps:
  1. Code the following entry for IDMSINTL in the program list table:
    DFHPLT TYPE=ENTRY PROGRAM=IDMSINTL
  2. Enter the name of the program list table (PLTPI) in the system initialization table.
If you don't have IDMSINTL started as a function of the CICS startup routine, be sure to execute the IDMSINTL interface module before attempting communication with DC/UCF at runtime. To execute the IDMSINTL module, enter a TRANSID that corresponds to the IDMSINTL module in the PCT tables.
To start up IDMSINTL automatically
after
control is given to CICS, perform the following steps.
  1. Code the following IDMSINTL 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 IDMSINTL.
    For more information on the PCT table, see UCF Operations.
IDMSINTL processing at runtime
IDMSINTL must be resident in CICS and must be executed before the execution of any CA IDMS database application for that run of CICS. Control passes from IDMSCINL to the main entry point to notify DC/UCF to perform a service requested by the CICS user program.
IDMSINTL performs the following functions:
  • Allocates dynamic storage required to service the run-unit.
  • Enables the recovery exit entry point for the current CICS task. The exit performs the necessary cleanup when the CICS task terminates.
  • Sends the request through the CA IDMS SVC to the DC/UCF region. IDMSINTL 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.
IDMSINTL Syntax
►►─┬───────────────┬─ IDMSINTL CWADISP=
cwa-intc-address-displacement
─────────► ├─
module-name
─┤ └─ IDMSINTL ────┘ ►─ ,OPSYS=
operating-system
──────────────────────────────────────────────────► ►─┬───────────────────────────┬──────────────────────────────────────────────► └─ ,CVNUM= ─┬─
cv-number
─┬─┘ └─ 0 ◄────────┘ ►─┬──────────────────────────┬───────────────────────────────────────────────► └─ ,SVC= ─┬─
svc-number
─┬─┘ └─ NO ◄────────┘ ►─┬──────────────────┬───────────────────────────────────────────────────────► └─ ,SYSCTL=
ddname
─┘ ►─┬──────────────────────────────┬───────────────────────────────────────────► └─ ,TPNAME=
system-name
────────┘ ►─┬───────────────────────────────────────────┬──────────────────────────────► └─ ,NODENAM=(
nodename
─┬─ ,ALWAYS ────┬─ ) ─┘ └─ ,DEFAULT ◄──┘ ►─┬──────────────────────────────────────────┬───────────────────────────────► └─ ,DBNAME=(
db-name
─┬─ ,ALWAYS ────┬── ) ─┘ └─ ,DEFAULT ◄──┘ ►─┬───────────────────┬──────────────────────────────────────────────────────► └─ ,XA= ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬───────────────────────────────────┬──────────────────────────────────────► └─ ,ERRDCT= ─┬─
destination-name
─┬─┘ └─ CSMT ◄────────────┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,PLT= ─┬─ YES ◄──┬┘ └─ NO ────┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ ,TRANSID=
task-code
─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────►◄ └─ ,MACLVL= ─┬─ YES ◄──┬─┘ └─ NO ────┘ ►─┬───────────────────────┬─────────────────────────────────────────────────►◄ └─ ,UOWID= ─┬─ YES ◄──┬─┘ └─ NO ────┘
IDMSINTL 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 to hold the address of the IDMSINTL module. For
    cwa-intc-address-displacement
    , specify a number of bytes (maximum value is 3584) or the name of a field within the CSA copy book.
    Considerations:
    The specified field must be on a fullword boundary within the CWA and must be the same value given to the CWADISP parameter of the IDMSCINL macro.
  • OPSYS=
    operating-system
    Identifies the operating system under which the DC/UCF system will run.
    Valid values for
    operating-system
    :
    • OS390
    • z/VSE
    • DVS
    • DS
    • DOS
    • DOSVS
  • CVNUM=
    cv-number
    Identifies the number of the DC/UCF system to be accessed from CICS. For
    cv-number
    , specify the number used for the CVNUM parameter in the sysgen.
  • SVC=
    svc-number
    Identifies the number of the CA IDMS SVC. 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 no SVC (described above) is specified, the SYSCTL parameter is required. Likewise, if SYSCTL is desired, the SVC parameter must be NO (SVC=NO).
  • TPNAME=
    system-name
    Specifies the name by which DC/UCF will identify all tasks running under this CICS system. If this parameter is omitted, the four-character local system id of this CICS system will be used, thereby permitting this CICS interface module to be used by multiple CICS systems. You may optionally specify a four-character name.
    This name forms the first part of the local transaction ID for database requests. It also forms the first 4 characters of the front end system ID for external request units. "BULK" is appended to
    system-name
    to form the front-end system ID. The front-end system ID is used in determining the packet size for communications and may also be used as an alternate task code for controlling external request unit processing.
  • NODENAM=
    nodename
    Identifies a system defined to the DC/UCF communications network to be contained in the IDMSINTL module and the conditions under which programs signing on to the DC/UCF system will be directed to the named node for execution.
    For
    nodename
    , specify the 1- to 8-character name of a remote system. If the node name 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.
    Under z/OS and z/VSE, SYSCTL node name specifications can override IDMSINTL and program specifications.
  • DBNAME=
    db-name
    Identifies the database (or data dictionary) name to be contained in the IDMSINTL module. This parameter also identifies the conditions under which programs signing on to the DC/UCF system access the named database.
    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 IDMSINTL and program specifications.
  • XA=NO|YES
    Designates whether the operating system is XA (YES) or not (NO).
  • ERRDCT=
    destination-name
    Identifies the CICS transient data destination to be used as the target for error messages produced by IDMSINTL. The default
    destination-name
    is CSMT. Use another destination if you want to rout CA IDMS error messages to another CICS destination. The DCT entry should be defined with a logical record length of at least 130 characters.
  • PLT=YES|NO
    Indicates how IDMSINTL starts up. YES indicates that IDMSINTL can start up as a PLT-invoked program. NO indicates IDMSINTL always starts up as a user task once CICS start up is complete.
  • TRANSID=
    task-code
    Identifies the transaction coded in the program control table (PCT) as invoking IDMSINTL.
    task-code
    must be the name of a task defined in the PCT table.
    For more information on the PCT table, see UCF Operations.
  • MACLVL=YES|NO
    This parameter is obsolete. Macro level programs are no longer supported in CICS.
  • UOWID
    Indicates whether the IDMS interface should acquire the CICS transaction unit of work ID for Performance Monitor SMF230 job termination records.
Create an IDMSINTL Interface Program
This section contains the JCL to assemble and link edit the IDMSINTL module for z/OS and z/VSE operating systems.
z/OS IDMSINTL assembly and link edit
To assemble and link edit IDMSINTL
  1. Create an IDMSINTL source module as follows:
    IDMSINTL idmsintl-parameters END
  2. Save the IDMSINTL 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 in the "Sample z/OS JCL" topic.
    Substitute the name of your IDMSINTL source member and insert the following binder statements:
    ORDER DFHEAI INCLUDE CUSTLIB(
    optixit
    ) (Optional) INCLUDE CAGJLOAD(IDMSLSTB) ENTRY STARTUP SETOPT PARM(REUS=NONE,AMODE=31,RMODE=24) NAME idmsintl(R)
    • optixit
      Specifies the name of your OPTIXIT exit routine.
    • idmsintl
      Specifies the name of your IDMSINTL interface load module.
z/VSE IDMSINTL assembly and link edit
To create an IDMSINTL interface program under z/VSE:
  1. Assemble and catalog an IDMSINTLoptions 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 idmsintl.OBJ REPLACE=YES' IDMSINTL idmsintl-parameters END
  2. Link the IDMSINTL interface program using the sample JCL in z/VSE Link JCL.
  3. Modify the JCL by substituting the following statements in place of the
    Linkage editor control statements
    :
    PHASE idmsintl,* INCLUDE DFHEAI INCLUDE
    optiexit
    (Optional) INCLUDE IDMSLST6 INCLUDE DFHEAI0 MODE AMODE(31),RMODE(24) ENTRY STARTUP
    • idmsintl
      Specifies the name you choose for your IDMSINTL options table.
      You can have more than one options table with different names
    • optixit
      Specifies the name of your OPTIXIT exit routine.
IDMSCINL
IDMSCINL is essentially a copy of the Release 10.2 IDMSCINT with the exception that the CICS CWA is located using ADDRESS CWA. This makes IDMSCINL compatible with all releases of CICS.
You generate IDMSCINL at DC/UCF installation time. IDMSCINL must be link edited with each CICS user program that accesses DC/UCF (including Assembler modules). IDMSCINL retrieves the entry point address of IDMSINTL from the CWA and passes control to IDMSINTL. The module generated by the IDMSCINL macro is fully reentrant.
For more information on runtime events, see What Happens when a CA IDMS Instruction is Executed.
To prepare an IDMSCINL macro, use the following syntax.
IDMSCINL Syntax
►►─┬───────────────┬─ IDMSCINL CWADISP=
cwa-intc-address-displacement
────────► └─ IDMSCINT ◄───┘ ►─┬────────────────────────────────┬────────────────────────────────────────► └─ ,EP1=
first-entry-point-label
─┘ ►─┬─────────────────────────────────┬───────────────────────────────────────► └─ ,EP2=
second-entry-point-label
─┘ ►─┬─────────────────────┬───────────────────────────────────────────────────►◄ └─ ,EXEC= ─┬─ YES ◄─┬─┘ └─ NO ───┘
IDMSCINL Parameters
  • IDMSCINT
    Identifies the CSECT name of the generated module. This tag is optional.
  • CWADISP=
    cwa-intc-address-displacement
    Identifies the displacement within the CICS CWA of a fullword that holds the address of the IDMSINTL module. For
    cwa-intc-address-displacement
    , specify the same value given to the CWADISP operand of the IDMSINTL macro.
  • 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
    • This parameter is obsolete and should no longer be used.
  • 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.
    • NO
      Specify NO to indicate that the command-level interface is not in use.
    This option should not be specified because macro level programs are no longer supported in CICS.
Example Assembling and link editing IDMSCINL
This section contains the JCL to assemble and link edit the IDMSCINL module for z/OS and z/VSE operating systems.
z/OS IDMSCINL assembly and link edit
To assemble and link edit IDMSCINL
  1. Create a source module as follows:
    IDMSCINL idmscinl-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.
    Substitute the name of your source member and insert the following binder statement:
    NAME
    idmscinl
    (R)
  4. Add the following statement to the link of each application program that accesses IDMS using this
    idmscinl
    application stub program. The CWADISP specified in the IDMSCINL parameters must match the CWADISP specified in the IDMSINTL parameters used in creating an IDMSINTL interface program:
    INCLUDE idmscinl
    • idmscinl
      Specifies the name of your IDMSCINL interface module.
z/VSE IDMSCINL assembly and link edit
  1. Assemble and catalog an IDMSCINL program 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
    idmscinl
    .OBJ REPLACE=YES' IDMSCINL idmscint-parameters END
  2. Add the following statement to the link of each application program that accesses IDMS using this
    idmscinl
    application stub program. The CWADISP specified in the IDMSCINL parameters must match the CWADISP specified in the IDMSINTL parameters used in creating an IDMSINTL interface program:
    INCLUDE idmscinl
    • idmscinl
      Specifies the name you choose for your IDMSCINL application stub program.
      You can have more than one application stub program with different names.