LINK


LINK is used to call the other programs expecting return in CICS environment. When the LINK is coded in the program, the calling program expected the control back from called program.

LINK passes control from an application program at one logical level to an application program at the next lower logical level. If the requested program is not defined to CICS and AUTOINSTALL is active, CICS supplies a definition for the program.

LINK passes the control between the programs from one logical level to the next lower logical level. The linked program can be two types based on the region’s 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 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 require to be recompile hence LINK will use the dynamic calling of the sub programs. Subprograms called using LINK needs PPT entry in CICS region.

If the command is issued by a program that is running under a task for an application, CICS searches first for the named program in the private program directory for the application. If the named program is not found there, CICS then searches the public program directory.

Syntax -


LINK Syntax

Parameters -


PROGRAM(program-name) -

Program name is mandatory entry in LINK command. Specifies the program name to which the control is passed unconditionally 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 searches in the local libraries to execute the program.

COMMAREA(data-area) -

COMMAREA is optional entry in LINK command. Specifies the communication area that is passing to the called program. Calling program always passes the pointer to the data area to called program. Subprogram or called program needs to receive it by using DFHCOMMAREA declaration in LINKAGE SECTION.

LENGTH(data-value) -

LENGTH is optional entry in LINK command. LENGTH is 16-bit(half-word) binary value that specifies the length of the communication area. If negative value supplied, ZERO length will be assumed. Do not specify 0 (zero) for LENGTH, because the resulting behaviour is unpredictable and the EXEC CICS LINK command might fail.

DATALENGTH(data-value) -

DATALENGTH is optional entry in LINK command. DATALENGTH is 2 bytes(half-word) binary value that specifies the length of the contiguous memory area from the start of the COMMAREA.

The DATALENGTH is specified and checked ony when the LINK request is remote or dynamic. The DATALENGTH is not checked for static local links. DATALENGTH cannot be used at the same time as INPUTMSG.

CHANNEL(channel-name) -

CHANNEL is optional entry in LINK command. Specifies the channel made available to the invoked program or called program or linked program. Channel name is of 16 characters length which contains alphanumeric characters and special characters.

If less than 16 characters given, the remaining characters at the right most characters will be filled with spaces. If the specified channel does not exist, it is created.

INPUTMSG(data-area) -

INPUTMSG is optional entry in LINK command. Specifies the data to be supplied to the called program when it first issues RECEIVE statement. The data 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. If a linked-to chain exists, CICS supplies the INPUTMSG data to the first RECEIVE command run in the chain. INPUTMSG cannot be used at the same time as DATALENGTH.

INPUTMSGLEN(data-value) -

INPUTMSGLEN is optional entry in LINK command and mandatory when INPUTMSG coded with LINK Statement. INPUTMSGLEN is a half word binary value that specifies the length of the INPUTMSG.

SYSID(system-name) -

SYSID is optional entry when linking to the local programs and mandatory entry for the remote programs. SYSID specifies the remote region name to where the program link request is to be routed. SYSID is a four characters field contains alphanumeric characters.

SYNCONRETURN -

SYNCONRETURN is optional entry in LINK command. Specifies the remote region on the SYSID to take the sync point on the successful completion of the linked program.

SYNCONRETURN is only applicable to remote links, it is ignored if the link is local. Changes to recoverable resources made by the calling program are committed or rolled back independently of changes to recoverable resources made by the called program issuing the LINK request.

TRANSID(name) -

TRANSID is optional entry in LINK command. Specifies the remote transaction that attached to the remote region and under which it is to run the called program. If the TRANSID is ignored, the remote regions attach either CSMI or CPMI.

Error Conditions -


Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.

Error ConditionRESP2, Description & SolutionSystem Action
122 CHANNELERR
1 - The channel name contains illegal character or combination of illegal characters
Solution -Change the application program/table and remove invalid characters in the channel name.
Task abnormally terminated
16 INVREQ
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.
Solution -LINK with INPUTMSG option should be issued from a program that is associated with local terminal or APPC logical unit or an IRC session. Modify the program to remove it.

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.
Solution -In this case, the client program is in an incorrect state to support the SYNCONRETURN option. Modify the program to remove it.

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.
Solution -Correct the transaction id in the program if required to be different or contact the system administrator if the behaviour is as expected.

16 - The TRANSID specified is all blanks.
Solution -Modify the Application program if the transaction is coded or debug the program if the transaction is passing from somewhere else.

17 - The TRANSID supplied by the dynamic routing program is all blanks.
Solution -Debug the program why the transaction id having all blanks and correct it.

19 - A LINK command with the INPUTMSG option is issued for a program that is the subject of a DPL request.
Solution -LINK with INPUTMSG should not be coded in the program invoked by DPL. Modify the application program to correct it.
Task abnormally terminated
22 LENGERR
11 - The COMMAREA length is less than 0 or greater than the permitted length.
Solution -Debug the application program to verify the COMMAREA length. If the COMMAREA length specified is less than zero, modify it according to the data. If the COMMAREA length is greater than permitted length, use other ways to pass the data from program to program.

12 - The length specified on the DATALENGTH option is a negative value.
Solution -Length specified in DATALENGTH should not be negative. Modify the program to correct the length value.

13 - The length specified on the DATALENGTH option is greater than the length specified on the LENGTH option.
Solution -Length specified in DATALENGTH should not be greater than the length value specified in LENGTH option. The length value should be same in both options.

26 - The COMMAREA address is zero, but the COMMAREA length is nonzero.
Solution -COMMAREA address should be a valid address. Debug the application program to verify how COMMAREA address is not set.

27 - The INPUTMSG length is less than 0 or greater than 32767.
Solution -Debug the application program to verify the INPUTMSG length. If the INPUTMSG length specified is less than zero, modify it according to the data. If the INPUTMSG length is greater than 32767, use other ways to pass the data from program to program.
Task abnormally terminated
70 NOTAUTH
101 - A resource security check has failed on PROGRAM(name).
Solution -Application programmer doesn’t need to do anything. Contact system administrator team to check whether the appropriate access added for the user or group. It will resolve the problem.
Task abnormally terminated
27 PGMIDERR
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.
Solution -Contact system administrator to make the program definition installed.

2 - A program is disabled.
Solution -Contact system administrator to make the program entry enabled.

3 - A program was not loaded because the load not found or load new copy not issued.
Solution -To reset the load status, the load module must be in the DFHRPL concatenation and a SET PROGRAM NEWCOPY is required.

21 - The program autoinstall control program failed. Program autoinstall is disabled and message DFHPG0202 or DFHPG0203 is written to the CSPL.
Solution -Contact system administrator to resolve the error.

22 - The model returned by the program autoinstall control program was not defined to CICS or was not enabled.
Solution -Contact system administrator to resolve the error.

23 - The program autoinstall control program returned invalid data.
Solution -Contact system administrator to resolve the error.

24 - The defined program failed because auto install returned an invalid program name or definition.
Solution -Contact system administrator to resolve the error.

25 - The dynamic routing program rejected the link request.
Solution -Contact system administrator to resolve the error.
Task abnormally terminated
121 RESUNAVAIL
0 - A resource required by the linked-to program is unavailable on the target region.
Solution -Call again the dynamic routing program for route selection failure.
Call again the dynamic routing program for route selection failure.
82 ROLLEDBACK
29 - The SYNCONRETURN option is specified and the server program cannot successfully take a sync point.
Solution -In this case, the client program is in an incorrect state to support the SYNCONRETURN option. Modify the program to remove it.
Task abnormally terminated
53 SYSIDERR
18 - The SYSID specified cannot be found in the intersystem table.
Solution -Check the SYSID and modify the program to correct it.

20 - The remote system specified in SYSID is not supports distributed program link requests.
Solution -Change the remote system id if specified wrongly or contact system administrator if the remote system id is specified correctly.

21 - The remote system specified in LINK with CHANNEL option does not support CHANNEL option.
Solution -Contact System administrator to rectify the error.

28 - The remote system specified by SYSID is not in service and transaction has not been defined on the remote system.
Solution -Change the remote system id if specified wrongly or contact system administrator if the remote system id is specified correctly.

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.
Solution -Contact System administrator to rectify the error.

31 - The request to allocate a session to the remote system has been rejected.
Solution -Contact System administrator to rectify the error.

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.
Solution -Contact System administrator to rectify the error or request them after some time.
Task abnormally terminated
81 TERMERR
17 - An unrecoverable error occurs during the conversation with the Remote region.
Solution -Contact System administrator or support team to rectify the error.
Task abnormally terminated