LINK

LINK

The CICS LINK command is used to call another CICS program from the currently executing program. The control is temporarily transferred to the called program, and once the called program completes, control is returned to the original program.

Features -

  • Transfers control to another program (subprogram) and returns once execution is complete.
  • The calling program remains active while the called program executes.
  • COMMAREA (Communication Area) can be used to pass data between programs.
  • The called program executes at the same logical level as the calling program.
  • The called program must be defined in CICS using a PPT (Processing Program Table) entry.

Syntax -

EXEC CICS LINK
	PROGRAM(program-name)
	[COMMAREA(data-area) LENGTH(data-area-length)]
	[CHANNEL (name)] 
	[INPUTMSG(data-area)]
	[INPUTMSGLEN(data-value)]
	[SYSID(system-name)]
	[TRANSID(name)]
	[RESP(response-field)]
	[RESP2(response-field2)]
END-EXEC.
  • PROGRAM(program-name) - Specifies the name of the CICS program to be called.
  • COMMAREA(data-area) - Specifies a communication area available to the next program that receives control. The valid range for the COMMAREA length is 0 through 32767 bytes. If the length provided is outside range, the LENGERR condition occurs.
  • LENGTH(data-area-length) - Specifies the length of the COMMAREA in bytes. If any negative value provided, ZERO assumed as length.
  • CHANNEL (name) - Specifies the channel name (1–16 characters) to be available to the next program that receives control.
  • INPUTMSG(data-area) - Specifies the data to pass to the transaction in the TRANSID option or call a program in a multi-region environment.
  • INPUTMSGLEN(data-value) - Specifies the length of the INPUTMSG. (Declaration: PIC S9(4) USAGE BINARY).
  • SYSID(system-name) - specifies the remote region name to where the program link request is to be routed and mandatory entry for the remote programs.
  • TRANSID(trans-id) - Specifies the remote transaction that attached to the remote region and under which it is to run the called program. If omitted, control returns to the calling program.
  • RESP(response-variable) - Optional. It captures the response code of the RECEIVE MAP operation and used to check if the command executed successfully or encountered an error.
  • RESP2(response2-variable) - Optional. It captures the response2 code of the RECEIVE MAP operation when the error occured.

Working -

  • The calling program executes a LINK command.
  • Control is transferred to the subprogram.
  • The subprogram processes the request and returns control.
  • The calling program resumes execution after the subprogram completes.

Short Examples -

Scenario - Using LINK in a CICS COBOL Program

Main Program (CALLER-PROG)

IDENTIFICATION DIVISION.
PROGRAM-ID. CALNPROG.

DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COMMAREA  PIC X(100).

PROCEDURE DIVISION.
    ...

	EXEC CICS LINK
	 PROGRAM('SUBPROG')
	 COMMAREA(WS-COMMAREA)
	 LENGTH(50)
	 RESP(WS-RESP-CODE)
	 END-EXEC.

	IF WS-RESP-CODE = 0 THEN
		MOVE "Returned from SUBPROG successfully" TO MSG1O
	ELSE
		STRING "Error in LINK command, Code: "
		        DELIMITED BY SIZE 
				WS-RESP-CODE 
				DELIMITED BY SIZE
				INTO MSG1O
	END-IF.
    ...

Called Subprogram (SUBPROG)

IDENTIFICATION DIVISION.
PROGRAM-ID. SUBPROG.

DATA DIVISION.
LINKAGE SECTION.
01 DFHCOMMAREA  PIC X(100).

PROCEDURE DIVISION.
    MOVE DFHCOMMAREA TO WS-COMMAREA.
    ...

Error Conditions -

Eror Condition RESP RESP2 Reason
INVREQ 16 8 A LINK command with the INPUTMSG option is issued for a program that is not associated with a terminal, or that is associated with an APPC logical unit, or an IRC session.
16 14 The SYNCONRETURN option is specified but the program issuing the link request is already in conversation with a mirror task in the remote region specified on the SYSID option.
16 15 The program issuing the link request is already in conversation with a mirror task and the TRANSID specified is different from the transaction identifier of the active mirror.
16 16 The TRANSID specified is all blanks.
16 17 The TRANSID supplied by the dynamic routing program is all blanks.
16 19 A LINK command with the INPUTMSG option is issued for a program that is the subject of a DPL request.
LENGERR 22 11 The COMMAREA length is less than 0 or greater than the permitted length.
22 12 The length specified on the DATALENGTH option is a negative value.
22 13 The length specified on the DATALENGTH option is greater than the length specified on the LENGTH option.
22 26 The COMMAREA address is zero, but the COMMAREA length is nonzero.
22 27 The INPUTMSG length is less than 0 or greater than 32767.
PGMIDERR 27 1 A program has no installed resource definition and either program auto install was switched off or the program autoinstall control program indicated that the program should not be auto installed.
27 2 A program is disabled.
27 3 A program was not loaded because the load not found or load new copy not issued.
27 21 The program autoinstall control program failed. Program autoinstall is disabled and message DFHPG0202 or DFHPG0203 is written to the CSPL.
27 22 The model returned by the program autoinstall control program was not defined to CICS or was not enabled.
27 23 The program autoinstall control program returned invalid data.
27 24 The defined program failed because auto install returned an invalid program name or definition.
27 25 The dynamic routing program rejected the link request.
SYSIDERR 53 18 The SYSID specified cannot be found in the intersystem table.
53 20 The remote system specified in SYSID is not supports distributed program link requests.
53 21 The remote system specified in LINK with CHANNEL option does not support CHANNEL option.
53 28 The remote system specified by SYSID is not in service and transaction has not been defined on the remote system.
53 29 The remote system specified by SYSID is in service, but there are no sessions available and the dynamic routing program has chosen not to queue the link request.
53 31 The request to allocate a session to the remote system has been rejected.
53 32 The queue of allocate requests for sessions to the remote system has failed because the session allocation queue is full or has been purged.
NOTAUTH 70 101 A resource security check has failed on PROGRAM(name).
TERMERR 81 17 An unrecoverable error occurs during the conversation with the Remote region.
ROLLEDBACK 82 29 The SYNCONRETURN option is specified and the server program cannot successfully take a sync point.
RESUNAVAIL 121 0 A resource required by the linked-to program is unavailable on the target region.
CHANNELERR 122 1 The channel name contains illegal character or combination of illegal characters