TFRCTL (Transfer Control)

TFRCTL Command syntax diagram

 

Purpose

The Transfer Control (TFRCTL) command calls the program specified on the command, passes control to it, and removes the transferring program from the return stack. Because the transferring program is removed from the call stack, control does not return to it when the called program returns control. Instead, control is returned to the command following the last call to the transferring program.

The following diagram shows the operation of both the CALL and TFRCTL commands. First, Program A calls Program B. Program B then calls Program C, which in turn transfers control (using the TFRCTL command) to Program D. In transferring control to Program D, Program C is removed from the call stack; therefore, Program D returns to Program B (to the command following the most recent call to the transferring program, Program C). Finally, Program B returns to Program A.

diagram shows the operation of both the <a href=CALL and TFRCTL commands">

If the transferring program was created with USRPRF(*OWNER), the authority does not transfer. However, if a program created with USRPRF(*OWNER) calls a program that transfers control, the authority does transfer because the program that called the transferring program remains in the call stack.

Optionally, the transferring program passes parameters to the program being called. The storage space used by the CL variables in the transferring program is freed and is available for use by the program receiving control.

The parameter values must be passed in CL variables. Values cannot be passed as constants, as null parameters (that is, parameters whose values are null, specified by *N), as lists of values, or as CL variables that were not specified as parameters on the PGM command that identified the start of the transferring program.

The transferring program can only pass CL variables that were previously passed to it. No CL variable can be passed that exists within the transferring program itself. Up to 40 parameters can be passed to the called program. The parameters passed must agree in type, length, number, and order with those expected by the receiving program, as specified in the PARM parameter of the PGM command.

Shared files remain open if control is transferred to a program from a high-level language program or from the CL program that opened the files.

 

Restrictions

  1. This command is valid only within CL programs.

  2. The user must have use authority or one of the data authorities for the program to which control is being transferred.

 

Required Parameters

PGM
Specifies the qualified name of the program that receives control from the program transferring control.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the program that receives control.

 

Optional Parameters

PARM
Specifies the names of one or more CL variables that are passed to the program that is receiving control. The variables passed can only be parameters that were passed to the program currently transferring control. Up to 40 variables can be specified. Specify a CL variable name for each of the values being passed by the program transferring control. The parameter values are received in the receiving program in the order in which they were specified on the TFRCTL command that calls the program.

The value *N cannot be specified as a value being passed because a null value cannot be passed to another program.

Example for TFRCTL 

TFRCTL   PGM(PROGA)  PARM(&PARM1)

This command transfers control to the program PROGA and passes the parameter &PARM1 to it. The parameter &PARM1 must previously have been passed to the program issuing this command.

Error messages for TFRCTL

*ESCAPE Messages

CPF0805
Error found when program &1 in &2 started.
CPF0809
Transfer control (TFRCTL) to C program not allowed.