CICS LINKCICS Call Statement CICS Xctl Statement
LINK is used to call the other programs in CICS environment.
When the LINK is coded in the program, the calling program expected the control back when the RETURN or GOBACK executed in called program.
Control will return to the calling program regardless of the programs calling structure. i.e. control will return to the calling program, even though the calls happened at same level of programs.
LINK passes the program from one logical level to another level which is the next lower logical level.
The linked program can be two types based on the regions existence.
- If the program is local to the current region then CICS loads the program and execute it.
- If the program is in remote region then CICS sends the LINK request to remote region and will call it as a Distributed Program Link (DPL).
For to do this, the remote program should be defined in the current CICS region where SYSID should have remove region entry where to execute.
The Exception handlers like HANDLE condition etc are not inherited to the called programs and will be in effect once the control returns back to the calling program.
If the subprogram modified, then the calling program doesn’t required to be recompile hence LINK will use the dynamic calling of the sub programs.
Subprograms called using LINK needs PPT entry in CICS region.
In another words, LINK will links to the another program expecting return.
EXEC CICS LINK PROGRAM(prog-name) COMMAREA(data-area) LENGTH(data-area-length) DATALENGTH(data-value) CHANNEL(data-value) INPUTMSG(input-msgdata-area) INPUTMSGLEN(input-msgdata-value) SYSID(system-name) SYNCONRETURN TRANSID(tran-name) END-EXEC.
Program name is mandatory entry in LINK command.
Specifies the program name to which the control needs to be passed and from where the control expected back.
Program name is of 8 characters length which includes alphanumeric characters.
Program id and program name should be same in each case.
When the LINK is executed, the CICS will check the SYSID in program definition.
If the SYSID has the data, CICS will simply transfers the control to remote region to execute the program. Otherwise, CICS will search for local definition to execute.
COMMAREA is optional entry in LINK command.
Specifies the communication area that is passing to the called program to process.
Calling program always passes the pointer to the data area to called program.
Subprogram or called program needs to receive it by using COMMAREA declaration in LINKAGE SECTION.
LENGTH is optional entry in LINK command.
LENGTH specifies 16-bit binary value which specifies the length of the communication area.
If negative value supplied, ZERO length will be assumed.
DATALENGTH is optional entry in LINK command.
Specifies a 2 bytes binary value is the length of the contiguous memory location.
CHANNEL is optional entry in LINK command.
Specifies the channel made available for invoked program or called program or linked program.
Channel name is of 16 characters length which contains alphanumeric characters and special characters.
If 16 characters are not given, the remaining characters at the left most characters will be filled with spaces.
INPUTMSG is optional entry in LINK command.
Specifies the data to be supplied to execute the called program when the it first RECEIVE statement executes.
The data will remain available until the RECEIVE or RETURN statement executes.
INPUTMSG is required when a particular program requires both commarea and message that required for RECEIVE command.
INPUTMSGLEN is optional entry in LINK command.
INPUTMSGLEN is mandatory when INPUTMSG coded with LINK Statement.
INPUTMSGLEN is a half word binary value.
SYSID is optional entry in LINK command for the local programs.
SYSID is mandatory entry for the remote programs.
SYSID is a four characters field which contains alphanumeric characters.
SYSID specifies the remote region name where the remote programs needs to execute.
SYNCONRETURN is optional entry in LINK command.
Specifies the remote region which is in SYSID to take the syncpoint on the successful completion of the linked program.
If the SYNCONRETURN is not specified the remote sync point will be ignored and default synchronization level will be considered.
TRANSID is optional entry in LINK command.
Specifies the remote transaction that needs to be attached in the remote region to execute the linked program.
If the TRANSID is ignored, the remote regions attaches either CSMI or CPMI.
INVREQ occurs in the following conditions.
1. The TRANSID is specified as blanks.
2. LINK command with INPUTMSG option is issued for the program that needs to be executed in the remote system.
3. The SYNCONRETURN option is specified in a application program which is already in a conversation with mirror task.
LENGERR occurs in the following conditions.
1. The length specified on the DATALENGTH option is greater than the length specified on the LENGTH option.
2. The length specified on the DATALENGTH option is negative length.
PGMIDERR occurs in the following conditions.
1. The program has no program definitions entry
2. Program entry disabled.
3. Program loading fails
NOTAUTH occurs in the following conditions.
1. If SYSID specified by a transaction defined with internal/external resource lock attribute
2. Resource security check is unsuccessful on the program.
SYSIDERR occurs in the following conditions.
1. The SYSID provided is down but a valid communications definition entry.
2. The SYSID provided is not valid communications definition entry.
3. The SYSID provided may be a valid communications definitions entry but not configured properly.
4. The SYSID provided may be a valid communications definitions entry but out of service.
TERMERR occurs in the following conditions.
1. If the connectivity fails or session fails
2. If any unrecoverable error occurred during the conversation.
3. The transaction specified with TRANSID does not exist in the region specified by the SYSID.
If any questions on the above, post your queries on CICS Discussion forum
CICS Call Statement CICS Xctl Statement