TFRGRPJOB (Transfer to Group Job)

TFRGRPJOB Command syntax diagram

 

Purpose

The Transfer to Group Job (TFRGRPJOB) command suspends the job that issued the TFRGRPJOB command and the group job specified by the GRPJOB parameter is resumed (if it already exists) or is created (if it does not exist). In both cases, control is transferred to the job specified by the GRPJOB parameter.

The job issuing the TFRGRPJOB command remains suspended until control is passed back to it and the job is resumed. A suspended job cannot do any processing until it is resumed. Suspended group jobs can regain control if another group job issues the TFRGRPJOB command to transfer to the suspended job, or if the active job in the group ends (and the suspended job was specified as the job to gain control).

If the work station message queue is in break or notify mode in the job that issued the TFRGRPJOB command, the message queue is set to the same mode in the group job that is transferred to. For example, if group job A has the work station message queue in break mode and transfers to group job B, the queue is in break mode in group job B. If group job B changes the queue to notify mode and transfers back to group job A, the queue is in notify mode in group job A.

If a user message queue is associated with the group (Change Group Attributes (CHGGRPA) command), it is handled like the work station message queue when one group job transfers to another group job.

Note:

No message is sent for normal completion of the TFRGRPJOB command. Instead, the user may obtain a control code describing the circumstances under which the job regained control (along with the group job name and the job number of the previously active job) by using the RTVGRPA command. For more information about these control codes, see the Retrieve Group Attributes (RTVGRPA) command.

 

Optional Parameters

GRPJOB

Specifies the name of the group job to which control is transferred.

*PRV: Control is transferred to the previously active job in the group. If the previously active job no longer exists, then the most recently active job in the group is resumed. This special value is valid only if there is another group job in the group.

*SELECT: The group job selection display is shown. The user can choose which group job to transfer to or create a new group job and transfer to it.

group-job-name: Specify the group job name of the job to which control is transferred.

When a group job name is specified and that group job already exists, the group job is resumed. Whenever an already existing group job is resumed, the INLGRPPGM, SPCENV, and TEXT parameters are ignored. However, when a group job name is specified and that group job does not already exist, the INLGRPPGM parameter is required and must specify an existing program. When this is the case, a group job is started and control is passed to the new group job.

INLGRPPGM

Specifies the qualified name of the job's first group program. The INLGRPPGM parameter is valid only when a group job is created. If the group job being transferred to already exists, this parameter is ignored.

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.

initial-group-program-name: Specify the name of the first group program.

SPCENV

Specifies the environment in which the group job starts. This parameter is valid only when this command creates a group job. If control is transferring to an existing group job, this parameter is ignored.

*DFT: The new group job starts in the environment specified in the user profile (the environment in which this command is running). The group job starts in the System/36 environment if one of the following is true:

• The System/36 environment is active in the job in which this command is running.
• The user profile specifies that the user runs in the System/36 environment, and the first program called in the group job is QCMD.

*INLGRPPGM: The new group job starts in the environment determined by the first program called in the group job. If the first group program is QCMD, the special environment value in the user profile is used to determine the environment.

*S36: The new group job starts in the System/36 environment.

*NONE: The new group job starts in the iSeries 400 environment.

RSTDSP

Specifies whether data being shown at a display device by this display file is saved at the time the file is suspended (made temporarily inactive) so that a different display file can be used to show different data on the same device.

*NO: The data being shown by this file is not saved when the file is suspended.

*YES: The data being shown when the file is suspended is saved so it can be restored to the display of the device when the file is used again.

TEXT

Specifies the text that briefly describes the group job. More information on this parameter is in Commonly used parameters.

This text appears on the Group Job Selection display.

Note:

This parameter only has meaning when a group job is created. If the group job being transferred to already exists, this parameter is ignored.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Example for TFRGRPJOB

TFRGRPJOB  GRPJOB(GROUPJ1)  INLGRPPGM(QGPL/PROGRAM1)

  SPCENV(*S36)

This command suspends running of the current job. If group job GROUPJ1 already exists, it is resumed at the point where it was suspended (the next high-level language command following the TFRGRPJOB request).

If group job GROUPJ1 does not exist, group job GROUPJ1 is created and runs the program QGPL/PROGRAM1 in the System/36 environment.

Error messages for TFRGRPJOB

*ESCAPE Messages

CPF1E15

Problem occurred while calling Operational Assistant.

CPF1310

Request to transfer to group job failed with reason code &1.

CPF1313

Value &1 for parameter &2 not allowed name.

CPF1314

Value &1 for parameter &2 not allowed.

CPF9871

Error occurred while processing.