LINK

Purpose

Specifies the next dialog executed in a current application.

LINK is also used to request execution of a COBOL, PL/I, or Assembler program.

Syntax

►►── LINK ──┬──────────┬── to ─┬─┬────────────────────┬─ dialog-name ─────────►
            └─ NOSAVE ─┘       │ └─ DIALOG ───┬─ IS ─┬┘
                               │              └─ =  ─┘
                               └┬─ PROGram ─┬─┬──────┬─ program-name ─────────
                                └─ PGM ─────┘ ├─ IS ─┤
                                              └─ =  ─┘

 ►──────┬─────────────────────────────┬────────────────────────────────┬─ . ──►◄
        └─ USING ( control-options ) ─┘                                │
                                                                       │
  ──────┬────────────────────────────────────────────────────────────┬─┘
        └─ USING ( ─┬───────────────────┬──┬───────────────────┬─ ) ─┘
                    │                   │  │ ┌───────────────┐ │
                    └─ control-options ─┘  └─▼─ record-name ─┴─┘

Expansion of Control-Options

►►─┬───────────────┬──┬─────────────────────┬─────────────────────────────────►◄
   ├─ MAP-CONTROL ─┤  ├─ SUBSCHEMA-CONTROL ─┤
   └─ MAP_CONTROL ─┘  └─ SUBSCHEMA_CONTROL ─┘

Parameters

NOSAVE

Specifies that the database currencies for the dialog that issues the LINK command are not saved.

When a dialog that issues a LINK NOSAVE command regains control from a lower level dialog or program, its database currencies are set as follows:

If the LINK command extends a run unit, the dialog's currencies are passed back up to the dialog or program to which the linking dialog passed control.
If the LINK command does not extend a run unit, the dialog's database currencies are reinitialized to whatever they were when the dialog gained control.

DIALOG IS dialog-name

Specifies the name of the dialog to which control passes.

Dialog-name is either the name of a variable data field that contains the dialog name or the dialog name itself, enclosed in single quotation marks.

The load module for the named dialog must be stored in the data dictionary of load library.

IS or = are optional keywords and have no effect on processing.

PROGram IS program-name

Specifies the name of the COBOL, PL/I, or Assembler program to which control is passed.

Program-name is either the name of a variable data field that contains the program name or the program name itself, enclosed in single quotation marks.

The load module for the named program must be defined under DC/UCF as a program. The program can be defined in any of the following ways:

At system generation by means of the PROGRAM statement
In the IDD by means of the DDDL PROGRAM statement
Under DC/UCF by means of the DCMT VARY DYNAMIC PROGRAM master terminal command

PGM can be used in place of PROGRAM.

USING control-options

Identifies the control options to be used.

Expanded syntax for control-options is shown above immediately following the LINK syntax.

Multiple parameters in the USING clause must be separated by blanks or commas. The record and control block names must be specified in the same order in which they are defined in the user program. If used, the USING clause must specify at least one record or control block name.

The SQLSSI parameter is used when passing a global cursor from an CA ADS dialog to a user program. SQLSSI is a record that contains the SQL session identifier which is assigned when the dialog's transaction started. This record is copied into the dialog automatically, so the user does not need to add it to the dialog. The user program must have a record in its "linkage" section defined with the SQLSESS datatype.

record-name

Specifies the data that is passed to the named user program.

MAP-CONTROL

Passes the map request block of the original CA ADS dialog to the lower level dialog.

The lower level dialog must specify the same map as the calling dialog. The version number and date/time stamp for both maps must be identical. If the maps differ, the application abends.

The keyword MAP_CONTROL may be used in place of MAP-CONTROL.

SUBSCHEMA-CONTROL

Extends a calling dialog's run unit to a lower level dialog. The runtime system ignores any differences between the two dialog's subschemas, schemas, and area ready modes. On return to the calling dialog, the run unit is unconditionally extended upward.

The dialog to which control is extended is not allowed to access a record or set not defined in the original dialog's subschema. Such an attempt causes an abend at runtime.

The keyword SUBSCHEMA_CONTROL may be used in place of SUBSCHEMA-CONTROL.

Usage

Control Passed to a Specified Dialog

When control is passed to a specified dialog by means of a LINK command, the next lower level in the application thread is implicitly established and a nested structure is created.

Considerations

The dialog issuing the LINK command becomes the top of the nested structure and remains operative.
If an application response passes control by means of a LINK command, the function from which the response was selected becomes the top of a nested structure.
A LINK command within a nested structure establishes the top of a lower nested level.
Dialogs within a nested structure can issue any of the control commands.
A RETURN command cannot pass control higher than the top of the lowest nested level that is operative in the application thread.
The dialog issuing a LINK command expects control to return to the command following the LINK instruction.
The issuing dialog's database currencies are saved and are available to the dialog when it regains control, unless the NOSAVE option is used.
When the dialog that issued a LINK NOSAVE command regains control from a lower level dialog or program, the database currencies set depend on whether or not the run unit was extended.

Refer to the LINK command syntax rules that follow this discussion for currency settings of extended and nonextended run units.

Control Passed to a User Program

When a LINK command specifies a user program, control passes outside the CA ADS environment and temporarily suspends CA ADS sessions.

Considerations

The LINK command must explicitly specify any data to be passed to the user program, including the subschema control block, the map request block, and any records used in the program's processing.
A user program has the option of using the calling dialog's run unit.
If the LINK command does not contain subschema-control in its USING list, the user program cannot access its calling dialog's run unit. The user program can access a database by binding a run unit and establishing its own currencies. This run unit will be bound concurrently with the dialog's run unit.

If the LINK command contains subschema-control in its USING list, the dialog's run unit is passed to the user program. Any database records to be shared with the dialog should be passed in the USING RECORD list.
A user program must return control to CA ADS by means of a DC RETURN statement.
When the user program issues the DC RETURN statement, the suspended CA ADS session resumes and control passes to the command following the LINK command.

The format of the DC RETURN statement varies based on whether the program has previously issued a DC RETURN statement that specified a next task code other than ADSR, as follows:
- If the program has previously issued a DC RETURN statement that specified a next task code other than ADSR, the DC RETURN statement that returns control to CA ADS must have the following format:
```
DC RETURN NEXT TASK CODE ADSR.
```
  DC RETURN NEXT TASK CODE will end the task and rollback any open run unit, whether it was bound by the user program or passed from the calling dialog.
  
  ADSR is the default task code that invokes ADSOMAIN with no input. The task code can be changed by means of the DC/UCF system generation TASK statement.
Note: For more information about specifying the task code for the CA ADS runtime system, see the CA IDMS System Generation Guide.
- If the program has not previously issued a DC RETURN statement that specified a next task code other than ADSR, the DC RETURN statement that returns control to CA ADS can have the following format:
```
DC RETURN
```
A dialog with a standard subschema can link to a dialog with an LRF subschema using subschema control. However, if the lower-level dialog makes an LR call, a status of 0063 is returned; in this case, the status is equivalent to a status of 2008.

To use the LINK command effectively in conjunction with user programs, refer to the online programming techniques presented in the CA IDMS DML Reference for the appropriate language.

Example 1: Passing control to a lower level dialog

Dialog UPDATEC, shown in Example 1 of Application Thread, uses the response process listed below to pass control to dialog UPDATEO.

UPDATEO obtains an ORDOR record for the current CUSTOMER, requests modifications, and updates the record in the database. When UPDATEO returns control to dialog UPDATEC, processing resumes with the DISPLAY command that follows the LINK command:

LINK TO DIALOG 'UPDATEO'.
DISPLAY MESSAGE TEXT IS
'CUSTOMER ORDER HAS BEEN CHANGED'.

Example 2: Passing control to a COBOL program

The following statement from the premap process associated with dialog UPDATEC passes control to the COBOL program LOOKUP. LOOKUP uses the subschema control block and CUSTOMER record buffer from UPDATEC to check the status of the current customer:

LINK PROGRAM 'LOOKUP'
USING (SUBSCHEMA-CONTROL,CUSTOMER).

Example 3: Extending the current map session

In this example, ERRCHK is a dialog that contains special error-checking and validating routines. ERRCHK uses the same map as the calling dialog. The LINK command passes current map attributes and data to ERRCHK.

When ERRCHK finds errors, it:

Sets the appropriate fields in error by modifying error attributes for the map.
Returns control to the calling dialog. The error attributes are returned along with current map data.

The sample LINK statement that passes control to ERRCHK is:

LINK TO DIALOG 'ERRCHK'
USING (MAP-CONTROL).

Example 4: Extending the current run unit

In this example:

The calling dialog uses subschema EMPSS01. This subschema contains records EMPLOYEE and DEPARTMENT.
The LINK command unconditionally extends the current run unit to dialog UPDATE, which is a mapless dialog containing update logic for records EMPLOYEE and DEPARTMENT.
The USING statement bypasses the checking of the subschema and ready modes when passing the run unit.
Dialog UPDATE updates the database and then returns control to the calling dialog.

The sample LINK statement that passes control to UPDATE is:

LINK TO DIALOG 'UPDATE'
USING (SUBSCHEMA-CONTROL).

Example 5: COBOL program that was passed the dialog's subschema-control

The following example shows a LINKed-to COBOL program that was passed the dialog's SUBSCHEMA-CONTROL.

ENVIRONMENT DIVISION.
  PROTOCOL. IDMS-RECORDS MANUAL.
WORKING-STORAGE SECTION.
  01 COPY IDMS SUBSCHEMA-NAMES.
  01 COPY IDMS RECORD <the name of each database record that is
                       needed but was not passed in the USING list>
LINKAGE SECTION.
  01 COPY IDMS SUBSCHEMA-CTRL.
  01 COPY IDMS RECORD <the name of each database record that is
                       passed in the LINK command>
PROCEDURE DIVISION.
  BIND <the name of each database record that is needed but was
        not passed in the LINK command>

Example 6: BAl program that was passed the dialog's subschema-control

The following example shows a LINKed-to Basic Assembler Language program that was passed the dialog's SUBSCHEMA-CONTROL and DIALOG record ADSO-APPLICATION-GLOBAL-RECORD.

ADSPGM TITLE 'PROGRAM CALLED FROM AN ADS DIALOG'
*GETBTMAP RENT EP=GBMPEP1 XA
COPY #APGDS
COPY #CSADS
COPY #TCEDS
COPY #SSCDS
#MOPT CSECT=ADSPGM,ENV=USER
@MODE MODE=IDMSDC,WORKREG=RO,QUOTES=YES,DEBUG=YES
*At entry, R9 contains the address of the TCE
USING TCE,R9
*At entry, R10 contains the address of the CSA
USING csa,R10
ENTRY ADSPGEP1
ADSPGEP1 DS OH
*-------------------------------------------------
*Set base register
*-------------------------------------------------
LR,R12,R15 BASE THIS MODULE
USING ADSPGEP1,R12
*Registers at entry need not be saved
*At entry, R1 contains the address of the passed parameter list
*Accept ADSO-APPLICATION-GLOBAL-RECORD as a passed parameter
L R6,0(,R1) A(SSCTRL)
USING APG,R6
* Accept SUBSCHEMA-CONTROL as a passed parameter
L R7,4(,R1) A(SSCTRL)
LA R7,0(,R7) CLEAR HIGH-ORDER FLAG
USING SSCTRL,R7
SPACE
#GETSTG TYPE=(USER,SHORT),PLIST=*,X
LEN=12,X
ADDR=(R2),X
INIT=0
* Necessary DML commands here
EJECT
*-------------------------------------------------
*Return to caller
*-------------------------------------------------
#RETURN
LTORG
END

More information:

CA ADS Runtime System