LINK

Transfer control and optionally send Commarea data from a CICS program at one logical level to a CICS AMB or non-AMB application subprogram; or, transfer control to an IMS or DLG subprogram.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

CICS

Syntax: for Format 1

Link to a AMB program

[TP-]LINK programname [errorpara]
... [DLIUIB pcbname [pcbname] ...]
... [userparm [userparm]...]
... [COMMAREA(dataarea) LENGTH(value)]|[NOCA]

Syntax: for Format 2

Linking to a non-AMB program

[TP-]LINK programname(NONAPS)[errorpara]
... [COMMAREA(dataarea)
... LENGTH(value)]|[NOCA]

General Rules:

  1. When linking to a AMB program, TP-COMMAREA passes by default. Alternately, you may pass another data area, or pass neither. Ensure that the Commarea in the "linked-to" program is the same length as the TP-COMMAREA or alternate data area you pass.
  2. When linking to a non-AMB program, TP-USERAREA passes by default. Alternately, you pass another data area, or pass neither. Ensure that the Commarea in the non-AMB program is the same length as the TP-USERAREA or alternate data area you pass. (TP-USERAREA gets its value from &TP-USER-LEN.)

    Additionally, code the following before your NTRY statement.

    % &TP-PROGRAM-INVOCATION = "NONAPS"
    
  3. Coding TERM in the subprogram returns control to the program that issued the link call.

Parameters:

program-name

Program name; can be a literal, variable, or combination, where the literal is moved to the variable (indicated by a slash (/) as the first character) by rule logic.

errorpara

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

DLIUIB pcbname

DLI User Interface Block and the Program Control Block for the next program.

userparm

Pass linkage data area(s). Code with TP-LINKAGE, which names the 01-level user-defined area in the Linkage Section.

COMMAREA (dataarea)

Pass data area to a program instead of TP-COMMAREA.

LENGTH (value)

Maximum length of data; can be a literal or COBOL data name; define as S9(04)COMP.

(NONAPS)

Program is not a AMB program.

NOCA

Do not pass COMMAREA.

Examples:

Link to PGM001. No PSB is active and no arguments pass.
LINK PGM001
Link to the program stored in WS-PROGNAME. No PSB is active and no arguments pass.
LINK /WS-PROGNAME
Move the value PGM003 to WS-PROGNAME and link to that program.
LINK PGM003/WS-PROGNAME
Link to PGM004; execute an error routine for an abnormal condition. There is no active PSB and no arguments pass.
LINK PGM004 ERROR-PARA
Link to PGM005. Schedule a PSB and use a PCB named ABC-PCB for the linked-to program. Omit the positional parameter errorpara .
LINK PGM005 * DLIUIB ABC-PCB
Link to PGM006 and pass a Linkage data area SCR6-RECORD so that PGM006 can move data directly to screen fields.
LINK PGM006 * SCR6-RECORD
Link to PROG001, a non-AMB program, passing TP-USERAREA only.
LINK PROG001(NONAPS)
Link to PROG002, a non-AMB program, passing the data area WS-COMMAREA.
LINK PROG002(NONAPS) * COMMAREA(WS-COMMAREA)
... LENGTH(100)
Link to PROG003, a non-AMB program, without passing a COMMAREA.
LINK PROG003(NONAPS) * NOCA

IMS DC

Syntax:

[TP-]LINK subprogram

... [errorpara]
... [argument1 ... argument36]

Parameters:

subprogram

AMB-painted subprogram that links the calling program.

errorpara

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

argument

Pass record area(s), such as a PCB. TP-COMMAREA, TP-USERAREA, or *NOSPA, may be an argument for conversational programs.

Example:

The following examples show the CALL statements generated in the program after linking to subprograms.

Coding. . . Yields. . .
LINK SUBPGM * ARG1 ARG2 ARG3
CALL 'SUBPGM' USING TP-COMMAREA 
ARG1 ARG2 ARG3
LINK SUBPGM * *NOSPA ARG1 ARG2 
ARG3
CALL 'SUBPGM' USING ARG1 ARG2 
ARG3
LINK SUBPGM * ARG1 ARG2 
TP-COMMAREA ARG3
CALL 'SUBPGM' USING ARG1 ARG2 
TP-COMMAREA ARG3

DLG

Syntax: for Format 1

CALL format

[TP-]LINK programname [errorpara]
... [userparm [userparm]...]
... [COMMAREA]

Syntax: for Format 2

SELECT format

[TP-]LINK programname

... [errorpara]
... [options]

General Rules:

  1. Including a TERM call in the invoked program returns control to the program issuing the LINK.
  2. Code userparms in the same order as those in the LINKAGE SECTION and the NTRY statement in the linked to program.
  3. To receive TP-COMMAREA as a passed data area from a called program, code the following before the NTRY keyword.
            % &DLG-COMMAREA-IN-LINKAGE = 'YES'
    
  4. LINK generates a COBOL CALL or ISPEXEC SELECT, depending on the PROGRAM CONTROL TRANSFER option.
  5. The &APSPRE..CNTL member APDLGIN assigns the default value for the PROGRAM CONTROL TRANSFER option. The variable &DLG-PROGRAM-TRANSFER-OPTION can have the values CALL (default) or SELECT.
  6. The PROGRAM CONTROL TRANSFER option affects the availability of function pool variables between programs. Using CALL makes the current function variable pool available to the linked-to program; using SELECT does not.
  7. To override the PROGRAM CONTROL TRANSFER option
    • At the installation level, change the value in &APSPRE..CNTL(APDLGIN).
    • At the project group level, code the assignment statement in &DSNPRE..CNTL(APSPROJ).
    • At the application level, code the assignment statement in a &DSNPRE..USERMACS member and include it for all application programs.
    • At the program level, code the assignment statement at the top of the program.
  8. The PROGRAM CONTROL TRANSFER option lets you invoke the LIBDEF service to define application-level libraries via the SELECT value.
  9. The called program must issue a TERM to stop executing, terminate the screen, and return to the calling program.
  10. The program that is called via TP-LINK should not issue a XCTL to another program.

Parameters:

program-name

Program name; can be a literal, variable, or combination, where the literal is moved to the variable (indicated by a slash (/) as the first character) by rule logic.

errorpara

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

userparm

Pass linkage data area(s). Code with TP-LINKAGE, which names the 01-level user-defined area in the Linkage Section.

COMMAREA

Pass the TP-COMMAREA, if the invoking program is the main program. Pass DLG-LINKAGE-COMMAREA, if the invoking program is a called program, that is, one where &DLG-COMMAREA-IN-LINKAGE = 'YES'.

options

DLG Management services SELECT PGM options.

Examples:

Invoke PGM001 as a new program function. The SELECT service option NEWPOOL creates a new shared variable pool. The SELECT option is in effect.
LINK PGM001 * NEWPOOL
Invoke PGM001 as a new program function. The SELECT service option PARM passes data to PGM001 via LINKAGE SECTION. To pass variable data, VDEFINE a dialog variable. The SELECT option is in effect.
DLG-VDEFINE 01  WS-EMPL-NBR  PIC X(05) AS EMPNBR
MOVE EMPL-NBR TO WS-EMPL-NBR
LINK PGM001 * PARM('&EMPNBR')
DLG-VDELETE EMPNBR
Link to the program in WS-PROGNAME. The CALL option is in effect.
MOVE 'PGM001' TO WS-PROGRAM
LINK /WS-PROGNAME
Link to PGM006 and pass Linkage data area SCR6-RECORD so that PGM006 can move data directly to screen fields. The CALL option is in effect.
LINK PGM006 * SCR6-RECORD