RTVGRPA (Retrieve Group Attributes)

RTVGRPA Command syntax diagram

 

Purpose

The Retrieve Group Attributes (RTVGRPA) command is used in a CL program or REXX procedure to retrieve information about the group in which the job that issued the RTVGRPA command belongs. The following attributes can be retrieved:

The prompt for this command lists the minimum length for retrieved variables next to the appropriate parameters. For character variables, a single number is shown. For decimal variables, two numbers are shown. The first number indicates the minimum variable length, and the second number indicates the minimum number of decimal positions.

 

Optional Parameters

GRPJOB
Specifies the name of the CL variable that receives the group job name of the job. The variable must be a character variable with a minimum length of 10 characters. If the group job name has fewer characters than the variable allows, the value is padded on the right with blanks.

Note: This is the only parameter of the RTVGRPA command that is meaningful if the job that issued the RTVGRPA command is not a group job. When this occurs, the variable is set to the special value of *NONE, and other parameters specified in the command are filled with zeros or blanks (numeric variables with zeros, character variables with blanks). If this parameter is not specified and the job issuing this command is not a group job, an error message is sent.

GRPJOBL
Specifies the name of the CL variable that receives the list of jobs in the group. Each entry contains the job's group job name, the job number, and the 50 characters of descriptive text.

The maximum number of entries in the variable is 16. The entries are ordered by most recently active job (the group job that is issuing the RTVGRPA command is always first in the variable).

The variable must be a character variable with a minimum length of 1056 characters. If the group job list has fewer characters than the variable allows, the value is padded on the right with blanks.

The group job list has the following format:

Entry-1

Group-job-name
CHAR(10)
Job-number
CHAR(6)
Group-job-text
CHAR(50)

Entry-2

.
 
.
 
.
 

Entry-16

Group-job-name
CHAR(10)
Job-number
CHAR(6)
Group-job-text
CHAR(50)

This list contains all of the active jobs in the group. Jobs in the group that have not completely ended (jobs that have been canceled) are not listed.

GRPJOBCNT
Specifies the CL variable that receives the count of active jobs in the group. The CL variable must be a three-position decimal variable with no decimal positions.

The CL variable contains the number of nonblank entries in the group job list. The count includes all of the active jobs in the group. Jobs that have not completely ended (jobs that have been canceled) are not counted.

MSGQ
Specifies the name of the CL variable that receives the group message queue name. This must be a character variable with a minimum length of 10 characters. If the message queue name has fewer characters than the variable allows, the value is padded on the right with blanks.

MSGQLIB
Specifies the name of the CL variable that receives the name of the library that contains the group message queue. This variable must be a character variable with a minimum length of 10 characters. If the library name has fewer characters than the variable allows, the value is padded on the right with blanks. If there is no message queue associated with the group, the CL variable is set to blanks.

Refer to the Change Group Attributes (CHGGRPA) command description for more information on the use of the group message queue.

PRVGRPJOB
Specifies the name of the CL variable that receives the group job name and job number of the previously active job in the group. The variable must be a character variable with a minimum length of 16 characters. If the group job name has fewer characters than the variable allows, the value is padded on the right with blanks.

If there is no previously active job in the group (no Transfer to Group Job [TFRGRPJOB] command is issued), the group job name portion of the CL variable is set to the special value of *NONE, and the job number portion of the CL variable is set to blanks. The CL variable is returned in the following format: 

Group-job-name     CHAR(10)
Job-number         CHAR(6)

Even though a group job name and job number are returned, it is not necessarily true that the group job still exists. There are cases in which the previously active job in the group has ended, which caused the currently active job to become active.

CTLCDE
Specifies the name of the CL variable that receives information about why the active job in the group has gained control. The CL variable must be a three-position decimal variable with no decimal positions. The following control codes (and their meanings) are possible:
0
There was no previously active job (no TFRGRPJOB commands have been run for this group).
10
The previously active job selected this job to be transferred to on the TFRGRPJOB command.
20
The previously active job's first group program ended normally, and this job was the most recently active job in the group.
30
The previously active job was ended by the End Group Job (ENDGRPJOB) command, and this job was selected to gain control (the RSMGRPJOB parameter specified this group job).
40
The previously active job was ended by the End Group Job (ENDGRPJOB) command and selected a job other than this job to gain control (which was ended before it could be resumed). Since this job was the most recently active job in the group, control is passed to it.
50
The previously active job was ended by the End Group Job (ENDGRPJOB) command, and this job was the most recently active job in the group (the RSMGRPJOB parameter specified *PRV).
60
The previously active job's first group program ended abnormally, and this job was the most recently active job in the group.
70
The previously active job was ended by the End Job (ENDJOB) command, and this job was the most recently active job in the group.

Examples for RTVGRPA

Assume jobs 0001/QUSER/WORKST01 and 0002/QUSER/WORKST01 are group jobs with group job names GROUPJ1 and GROUPJ2, respectively. Also assume that message queue QGPL/GROUPMSGQ is associated with the group. If group job GROUPJ1 has just issued the TFRGRPJOB command to transfer to group job GROUPJ2, and GROUPJ2 called the following CL program:

PGM Example 

DCL VAR(&GRPJOBN)      TYPE(*CHAR)     LEN(10)
DCL VAR(&GRPJOBL)      TYPE(*CHAR)     LEN(1056)
DCL VAR(&GRPCOUNT)     TYPE(*DEC)      LEN(3 0)
DCL VAR(&MSGQNAME)     TYPE(*CHAR)     LEN(10)
DCL VAR(&MSGQLIB)      TYPE(*CHAR)     LEN(10)
DCL VAR(&PRVJOB)       TYPE(*CHAR)     LEN(16)
DCL VAR(&CTLCODE)      TYPE(*DEC)      LEN(3 0)
 
  RTVGRPA  GRPJOB(&GRPJOBN)  GRPJOBL(&GRPJOBL)
    GRPJOBCNT(&GRPCOUNT)  MSGQ(&MSGQNAME)
    MSGQLIB(&MSGQLIB)  PRVGRPJOB(&PRVJOB)
    CTLCDE(&CTLCODE)

The contents of the CL variables returned are as follows: 

&GRPJOBN: GROUPJ2
&GRPJOBL:
 
GROUPJ2  0002  50 characters of text for
               this group job...
GROUPJ1  0001  50 characters of text for
               this group job...

Fourteen more entries, full of blanks 

&GRPCOUNT:     002
&MSGQNAME:     GROUPMSGQ
&MSGQLIB:      QGPL
&PRVJOB:       GROUPJ1     0001
&CTLCODE:      010

Error messages for RTVGRPA

*ESCAPE Messages

CPF1309
Subsystem cannot complete the &1 command.
CPF1311
Job is not a group job.
CPF1317
No response from subsystem for job &3/&2/&1.
CPF1351
Function check occurred in subsystem for job &3/&2/&1.