Micro Focus Enterprise Developer 3.0 for Eclipse > Programming > Mainframe Programming > AppMaster Builder > Reference > Data Communication Calls > LINK

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:

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.
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"
```
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

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:

Including a TERM call in the invoked program returns control to the program issuing the LINK.
Code userparms in the same order as those in the LINKAGE SECTION and the NTRY statement in the linked to program.
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'
```
LINK generates a COBOL CALL or ISPEXEC SELECT, depending on the PROGRAM CONTROL TRANSFER option.
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.
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.
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.
The PROGRAM CONTROL TRANSFER option lets you invoke the LIBDEF service to define application-level libraries via the SELECT value.
The called program must issue a TERM to stop executing, terminate the screen, and return to the calling program.
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