An introduction to the IDMS CICS interface
Article ID: 234331
Updated On:
Products
Issue/Introduction
This article is a summary of the main points needed to understand about how to implement the standard interface between IDMS and CICS.
Environment
Release : All supported releases
Component : IDMS UCF
Resolution
The xxxxINTC load module
The main load module that represents the link between one CICS region and one IDMS CV is typically called an "INTC" module.
A CICS region will need one of these for each IDMS CV to which it can connect. Therefore, it may need more than one, so there may be multiple INTC modules.
They will subsequently be referred to in this article collectively as "xxxxINTC" modules.
An xxxxINTC module is created using the #CICSOPT macro.
Steps ASM#INTC and LINKINTC from configuration job JOB03 contain JCL that can be used to create one xxxxINTC module.
The module must be link-edited into a load library that is available to the CICS DFHRPL concatenation.
The #CICSOPT macro takes several parameters.
The most important ones to be aware of are as follows:
CWADISP - an offset in the CICS CWA which must be unique across all xxxxINTC modules in the same CICS region.
SYSCTL - a ddname which must be specified in the CICS startup JCL and must point to the SYSCTL dataset of the IDMS CV to which this xxxxINTC module will connect.
SVC and CVNUM - the SVC number and CV number of the IDMS CV to which this xxxxINTC module will connect.
The usage of SYSCTL or SVC and CVNUM are mutually exclusive. The goal of these parameters is to tell the xxxxINTC module where it must get the IDMS CV's SVC and CV numbers from.
If SYSCTL is used, it will read them from the IDMS CV's SYSCTL file.
If SVC and CVNUM are used, it will know them from being specified directly in the assembly.
SYSCTL is highly recommended because it is easier to change and makes the connection between the CICS and IDMS systems more visible by virtue of the JCL.
The interface must be initiated once and once only ideally when the CICS system starts.
This can be done by placing the xxxxINTC module in the CICS PLT, or interactively by an online user invoking the CICS transaction id that was specified in the #CICSOPT TRANSID parameter.
When the interface has been initiated, a message like this will appear on the CICS log indicating that it was successful:
+CA IDMS 19.0 : IDMSINTC : CTS V05.05.00 interface to IDMS V 01 is now active
(Note, the 01 in the above message is the CV's CV number, not necessarily the SVC or SYSTEM number.)
The xxxxCINT load module
A CICS application program which accesses a database in the IDMS CV communicates with the xxxxINTC interface by including an xxxxCINT module in its link-edit.
There will be one xxxxCINT module for each xxxxINTC module.
The xxxxCINT module is created using the IDMSCINT macro.
Steps ASM#CINT and LINKCINT from configuration job JOB03 contain JCL that can be used to create one xxxxCINT module.
The most important IDMSCINT parameter is also CWADISP, which must have the same value as the CWADISP in the corresponding xxxxINTC module.
If the CWADISP values in the xxxxCINT and xxxxINTC modules do not match, or even if the interface was not started, an attempt to connect to IDMS from CICS will result in an 0068 abend.
The interface is provided in this manner so that maintenance to it will rarely require that application programs be re-linked.
An xxxxCINT module is just a small stub module with little functionality. All of the code which establishes the connection to IDMS is in xxxxINTC.
UCFCICS
UCFCICS is an IDMS-created module that resides in CICS and allows a user logged on to CICS to execute IDMS tasks directly from a CICS terminal.
Once again, if a CICS region must communicate with more than one IDMS CV, it will require a UCFCICS module for each one.
These modules will be referred to in this article generically as UCFxxxx modules.
A UCFxxxx module is created using various #UCFxxxx macros.
Steps ASM#UCFC and LINKUCFC from configuration job JOB03 contain JCL that can be used to create one UCFxxxx module.
The most important parameter is the #UCFUFT parameter NTID, which specifies the dedicated CICS transaction id that will be used to invoke the UCFxxxx module.
The link-edit of the UCFxxxx module must include the xxxxCINT module of the relevant IDMS CV.
CICSCSD
A CICS system which uses an xxxxINTC interface to communicate with an IDMS CV must have some definitions added to it.
These are provided in the IDMS configuration library member *.CAGJSRC(CICSCSD).
Occasionally, a PTF may update this member so it is vital that the most recent one be used.
As of February 10, 2022, the most recent one is provided by PTF SO09362.
Some of the definitions in CICSCSD are based on the assumption that a normal configuration was run and only one xxxxINTC was created and only with all the default names.
These are as follows:
DEFINE TRANSACTION(DBDC) PROGRAM(UCFCICS)
GROUP(IDMSGRP) PROFILE(IDMSPRF)
TASKDATAKEY(CICS)
DEFINE TRANSACTION(IDMS) PROGRAM(IDMSINTC)
GROUP(IDMSGRP) PROFILE(IDMSPRF)
TASKDATAKEY(CICS) TASKDATALOC(BELOW)
DEFINE TRANSACTION(INTC) PROGRAM(IDMSINTC)
GROUP(IDMSGRP) PROFILE(IDMSPRF)
TASKDATAKEY(CICS) TASKDATALOC(BELOW)
DEFINE PROGRAM(IDMSINTC)
GROUP(IDMSGRP) LANGUAGE(ASSEMBLER) CEDF(NO)
RES(YES) EXECKEY(CICS) DATALOCATION(BELOW)
DEFINE PROGRAM(UCFCICS)
GROUP(IDMSGRP) LANGUAGE(ASSEMBLER) CEDF(NO)
EXECKEY(CICS)
If a CICS system is configured to communicate with multiple IDMS CVs, then more than one version of xxxxINTC and UCFxxxx modules and related transactions will be required.
In this case, or even if more xxxxINTC and UCFxxxx modules have been created for any reason, then they will also require to be defined to CICS as PROGRAMs and TRANSACTIONs with the same attributes as the samples above.
Additional Information
Feedback
