Transferring control from IDMS ADS dialogs to CICS programs
Article ID: 60311
Updated On:
Products
Issue/Introduction
Is it possible to transfer control at runtime from IDMS DC running an ADS dialog to programs running on CICS?
Environment
Release: All releases
Component: IDMS/DB
Resolution
This can be done using UCF distributed applications and program RHDCUXFT, the UCF program that handles transfers to the front-end such as CICS. This procedure involves getting storage with storage ID PDAT which cannot be done by ADS however ADS may call a COBOL or an Assembler program to perform this task. The ADS task on the backend has to have been invoked by a transaction running on the front-end CICS.
For details on how this works refer to article 20732 - Initiate a CICS session from an IDMS program / dialog and the CA IDMS documentation section UCF Programs
How UCF Transfers Control and Data
The transferring program specifies the next task or transaction to be executed on the back-end. This task or transaction must be defined to invoke program RHDCUXFT.
Program RHDCUXFT must be defined at system generation time with the following attributes:
PROGRAM RHDCUXFT LANGUAGE ASSEMBLER REENTRANT NOPROTECT.
A DC program transferring control to a program on the front-end system does the following:
Passes data in storage that is USER KEEP LONG with a STGID of PDAT.
Transfers control to the program on the front-end system by returning to DC and specifying the next task to be executed for the terminal. The specified task, which must be defined as NOINPUT, indirectly causes the next program to execute.
A CICS command-level program transferring control to a program on the DC/UCF system queues the next transaction to be executed for the terminal and specifies the location and length of the data to be passed. In the following example, the next transaction to be executed is TSKB, and the data to be passed is located at PARTNUM:
EXEC CICS START TRANSID('TSKB') TERMID(EIBTRMID)
FROM(PARTNUM) LENGTH(10)
When transferring control to a program on the DC/UCF system, a CICS command-level program returns to CICS:
EXEC CICS RETURN
A CICS command-level program receiving control from a program on the DC/UCF system retrieves passed data:
EXEC CICS RETRIEVE INTO(data-area)
LENGTH(data-length-area)
CICS program and transaction definitions:
DEFINE TRANSACTION(TSKA) PROGRAM(A) ...
DEFINE TRANSACTION(TSKB) PROGRAM(UCFCICS) ...
DEFINE PROGRAM(A) ...
DEFINE PROGRAM(UCFCICS) LANGUAGE ASSEMBLER CEDF(NO)
EXECKEY(CICS)RESIDENT
To get the storage with storage ID PDAT which cannot be done by ADS, a COBOL or an Assembler program needs to be called to perform this task. See documentation section Calling a DC Program from a CA ADS Dialog
To return back to the ADS dialog from the CICS frontend program it must invoke task ADSR or an assembler or COBOL program that specifies a next task code of ADSR.
Sample COBOL programs to transfer data between ADS to CICS and back again were provided in old informational APAR 91031055:
The information from that informational APAR is reproduced here:
ADSO DIALOG 'A' IS EXECUTING ON THE DC SIDE. IT NEED TO EXECUTE A CICS
PROGRAM AND RETURN TO THE NEXT EXECUTABLE STATEMENT IN THE ADSO DIALOG 'A'.
IT WILL ALSO BE NECESSARY TO PASS DATA BACK AND FORTH BETWEEN REGIONS.
'ADSR' IS THE TASK CODE THAT WILL FACILITATE THE ABILITY TO TRANSFER BACK
INTO AN ADSO SESSION THAT WAS ESTABLISHED PRIOR TO A TRANSFER FROM ADSO
TO CICS .
THE FOLLOWING IS AN EXAMPLE OF THE SETUP AND SAMPLE SHELL PROGRAMS
NEEDED TO ACCOMPLISH DATA TRANSFER FROM ADS TO CICS AND BACK AGAIN.
SYSGEN CHANGES:
ADD PROGRAM RHDCUXFT LANGUAGE ASSEMBLER REENTRANT NOPROTECT.
ADD PROGRAM CALLCICS LANGUAGE COBOL. (THIS KICKS OFF TASK "ATSK" STARTING)
(RHDCUXFT)
ADD PROGRAM CICSRTN LANGUAGE COBOL. (THIS RETURNS TO ADSO WITH "ADSR" FREEING
(THE OUTSTANDING LINK)
ADD PROGRAM MOVSTG LANGUAGE COBOL. (MOVES STORAGE AND THEN RETURNS TO ADS)
ADD TASK ATSK INVOKES PROGRAM RHDCUXFT NOINPUT.
ADD TASK BTSK INVOKES PROGRAM CICSRTN NOINPUT.
*NOTE 'ADSR' SHOULD ALREADY BE DEFINED IN THE SYSGEN WHEN YOU CODED
"INCLUDE ADSO" STATEMENT.
CICS CHANGES NEEDED:
PPT ENTRY (PROGRAM PROPERTY TABLE ENTRY)
DFHPPT TYPE=ENTRY,PROGRAM=CICSPGM
PCT ENTRY
DFHPCT TYPE=ENTRY,TRANSID=ATSK,PROGRAM=CICSPGM
DFHPCT TYPE=ENTRY,TRANSID=BTSK,PROGRAM=UCFCICS,TWASIZE=408
EXAMPLES OF SHELL PROGRAMS NEEDED TO ACCOMPLISH THE DATA TRANSFER FROM
ADS TO CICS AND BACK AGAIN.
IDD
ADD RECORD ADS-WORK-RECORD.
02 CICS-DATA PIC X(120). (NOTE - ANY LENGTH)
ADSO DIALOG
1. WORK RECORD SCREEN: DEFINE ADS-WORK-RECORD.
2. CODE:
MOVE MESSAGE-SENT TO CICS-DATA.
LINK TO PROGRAM 'CALLCICS' USING ADS-WORK-RECORD.
LINK TO PROGRAM 'MOVSTG' USING ADS-WORK-RECORD.
MOVE CICS-DATA TO MESSAGE-RECEIVED.
CALLCICS (PROG. ID) - NATIVE DC COBOL PROGRAM THAT WILL SET UP STORAGE AND TRIGGER OFF THE 'CICSPGM'
WORKING-STORAGE SECTION.
COPY IDMS SUBSCHEMA-CTRL.
LINKAGE SECTIONL
01 ADS-WORK-RECORD.
02 CICS-DATA PIC X(120).
01 CICS-STG.
02 C-LENGTH PIC 99 USAGE COMP.
02 C-ZERO PIC 99 USGAE COMP.
02 C-DATA PIC X(120). *NOTE ANY LENGTH
02 C-STG-END PIC X.
PROCEDURE DIVISION USING ADS-WORK-RECORD.
GET STORAGE FOR CICS-STG TO C-STG-END KEEP LONG USER
STGID 'PDAT' ON DC-NEW-STORAGE NEXT SENTENCE.
MOVE 124 TO C-LENGTH.
MOVE ZERO TO C-ZERO.
MOVE ADS-WORK-RECORD TO C-DATA.
...
...
DC RETURN NEXT TASK CODE 'ATSK' *NOTE PROG RHDCUXFT ON DC SIDE
COPY IDMS IDMS-STATUS.
IDMS-ABORT SECTION.
IDMS-ABORT-EXIT.
EXIT.
CICSRTN - NATIVE DC COBOL PROGRAM THAT RETURNS TO ADS ONLINE.
WORKING-STORAGE SECTION.
COPY IDMS SUBSCHMEA-CTRL.
LINKAGE SECTION.
01 ADS-WORK-RECORD.
02 CICS-DATA PIC X(120).
01 CICS-STG.
02 C-LENGTH PIC 99 COMP.
02 C-ZERO PIC 99 COMP.
02 C-DATA PIC X(120).
02 C-STG-END PIC X.
PROCEDURE DIVISION.
....
.....
DC RETURN NEXT TASK CODE 'ADSR'. (BACK TO ADS)
COPY IDMS IDMS-STATUS.
....
......
MOVSTG - A NATIVE DC COBOL PROGRAM THAT MOVES THE STORAGE TO THE ADS-WORK-RECORD AND RETURNS TO ADSO-ONLINE
WORKING-STORAGE SECTION.
COPY IDMS SUBSCHEMA-CTRL.
LINKAGE SECTION.
01 ADS-WORK-RECORD.
02 CICS-DATA PIC X(120).
01 CICS-STG.
02 C-LENGTH PIC 99 USGAE COMP.
02 C-ZERO PIC 99 USAGE COMP.
02 C-DATA PIC X(120).
02 C-STG-END PIC X.
PROCEDURE DIVISION.
GET STORAGE FOR CICS-STG TO C-STG-END
KEEP
LONG
USER
STGID 'PDAT'
ON DC-NEW-STORAGE NEXT SENTENCE.
MOVE C-DATA TO CICS-DATA.
DC RETURN NEXT TASK CODE 'ADSR'.
COPY IDMS IDMS-STATUS.
IDMS-ABORT SECTION.
IDMS-ABORT-EXIT.
EXIT.
CICS
CICSPGM - A USER CICS PROGRAM
RETRIEVE 'PDAT' STORAGE
START TASK BTSK - TO INVOKE 'UCFCICS' AND START 'CICSRTN' ON DC SIDE
Feedback
