TRANSFER (DC/UCF)

Data Manipulation Language Statements › TRANSFER (DC/UCF)

TRANSFER (DC/UCF)

The TRANSFER statement is used to:

Establish linkage with a specified program and to pass control and an optional parameter list to that program. The program issuing the TRANSFER RETURN request expects return of control at the instruction immediately following the TRANSFER statement when the linked program terminates or issues a DC RETURN request.
Transfer control and an optional parameter list to a specified program. The program issuing the TRANSFER NORETURN request does not expect return of control.

Passing Parameters from a Non-PL/I Program

If parameters are passed to a PL/I program from a non-PL/I program (CA ADS, COBOL, and Assembler), special code must be used in the PL/I program. A partial sample of this code is shown below:

SAMPPROC: PROCEDURE (F1,F2,F3) OPTIONS (MAIN,REENTRANT);
DCL (F1,F2,F3) POINTER;
DCL (SAMPSUBS SUBSCHEMA, SAMPSCHM SCHEMA) MODE (IDMS_DC) DEBUG;
DCL IDMS ENTRY OPTIONS (INTER,ASM);
DCL IDMSP ENTRY;
DCL PASSED_FIELD_1 FIXED BIN (31) BASED(ADDR(F1));
INCLUDE IDMS (SUBSCHEMA_CTRL BASED(ADDR(F2)));
INCLUDE IDMS (RECORD_AA BASED(ADDR(F3)));
 .
 .
 .
rest of code

Here, a non-PL/I program has transferred control to this sample program, passing three parameters. The first is binary fullword. The second is the address of the subschema control block that the program will use. The third is an CA IDMS/DB record. Note that dummy parameters are set up to provide addresses on which to base the structures that are actually passed.

Refer to the PL/I programmer's reference for your site for more information on passing parameters to a PL/I program from an Assembler program.

Note: The section (in the same reference) on invoking PL/I programs from COBOL programs is not relevant. In a DC/UCF environment, you must code the PL/I program as shown in the previous sample.

Syntax

►►── TRANSFER TO (program-name) ─┬──────────────┬─┬───────────────────────┬ ;─►◄
                                 ├─ RETURN ─────┤ │    ┌───── , ─────┐    │
                                 ├─ LINK ───────┤ └ ( ─▼─ parameter ─┴ ) ─┘
                                 ├─ NORETURN ◄ ─┤
                                 └─ XCTL ───────┘

Parameters

TO (program-name)

Specifies the 1- to 8-character name of the program to which control is transferred. Program-name is either the symbolic name of a user-defined field that contains the program name, or the name itself enclosed in quotation marks.

RETURN/NORETURN

Specifies whether control will be returned to the calling program.

RETURN: Establishes linkage with the specified program, expecting return of control. The keywords RETURN and LINK are synonymous.
NORETURN: Transfers control to the specified program, not expecting return of control. The keywords NORETURN and XCTL are synonymous. NORETURN is the default.

parameter

Passes one or more parameters (data items) to the program receiving control. Parameter is the symbolic name of a user-defined field that contains the names of the data items to be passed. Multiple parameter specifications must be separated with a blank.

To use parameter, the DECLARE IDMSP ENTRY statement is required. For details on this PL/I declarative, see Required PL/I Declaratives.

If parameter is specified, the data items being passed are defined in program variable storage for both the calling program and the linked program. The program receiving control must include a corresponding parameter clause in its PROCEDURE statement.

Examples

The following statement transfers control to the program in the PROGRAM_NAME field; the issuing program expects return of control:

TRANSFER TO (PROGRAM_NAME)
  LINK;

The following statement transfers control to PROGRAMD and passes three data items (FIELD_1, FIELD_2, and FIELD_3) to the program; the issuing program does not expect return of control:

TRANSFER TO ('PROGRAMD')
  NORETURN
  (FIELD_1, FIELD_2, FIELD_3);

Status Codes

Upon completion of the TRANSFER function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:

0000: The request has been serviced successfully.
3020: The request cannot be serviced because an I/O, program-not-found, or potential deadlock error has occurred.