RTVJOBA (Retrieve Job Attributes) Command Description
RTVJOBA Command syntax diagram
Purpose
The Retrieve Job Attributes (RTVJOBA) command is used in a CL program or REXX procedure to retrieve the values of one or more job attributes and to place those values into the specified CL variable. The attributes are retrieved for the job in which this command is used. If a job attribute does not exist because the attribute is now supported at the thread level only (e.g. CURUSER), then the thread attribute is retrieved for the thread in which this command is used.
The CL 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.
Restrictions:
- This command is conditionally threadsafe. Refer to “Usage Notes” for additional information.
Optional Parameters
- JOB
- Specifies, if the job name is returned, the name of the CL variable that receives the name of the job. The variable must be a character variable with a minimum length of 10 characters. If the job name has fewer characters than the variable allows, the value is padded on the right with blanks.
- USER
- Specifies, if the user name is returned, the name of the CL variable that receives the name of the user profile associated with the job when the job was started. The user name is the second part of the qualified job name. The variable must be a character variable with a minimum length of 10 characters. If the user name has fewer characters than the variable allows, the value is padded on the right with blanks.
- NBR
- Specifies, if the job number is being returned, the name of the CL variable that receives the unique 6-character number assigned to the job by the system. The job number is the first part of the qualified job name.
- LOGLVL
- Specifies the name of the CL variable that receives the 1-character value, ranging from 0 through 4, that is the message logging level used to determine the type of messages logged in the job log. The variable must be a character variable with a minimum length of 1 character.
- LOGSEV
- Specifies the name of the CL variable that receives the 2-digit value, ranging from 00 through 99, which is the minimum severity level a message must have before it is logged in the job log. The variable must be a 2-digit decimal variable specified with no decimal positions.
- LOGTYPE
- Specifies the name of the CL variable that receives the special value that indicates the level of text that appears for any message written to the job log. The variable must be a character variable with a minimum length of 10 characters. If the special value has fewer characters than the variable allows, the value is padded on the right with blanks.
- LOGCLPGM
- Specifies the name of the CL variable that receives the special value that indicates whether processed commands in a CL program are being logged in the job log. Note that this logging flag only has meaning for commands processed in CL programs which were created with LOG(*JOB) specified on the Create CL Program (CRTCLPGM) command. Additional information on the job’s CL program logging flag is in the LOGCLPGM parameter description in the Change Job (CHGJOB) command. The variable must be a character variable with a minimum length of 10 characters. If the special value has fewer characters than the variable allows, the value is padded on the right with blanks.
- INQMSGRPY
- Specifies the name of the CL variable that receives the special value that indicates how inquiry messages are being handled by the job. Additional information on the value returned in the variable is in the INQMSGRPY parameter description in the Change Job (CHGJOB) command. The variable must be a character variable with a minimum length of 10 characters. If the special value has fewer characters than the variable allows, the value is padded on the right with blanks.
- OUTQ
- Specifies the name of the CL variable that receives the name of the output queue being used by the job for spooled output. The variable must be a character variable with a minimum length of 10 characters. If the output queue name has fewer characters than the variable allows, the value is padded on the right with blanks.The special value *DEV can be retrieved. This value indicates that the output queue with the same name as the printer device, which is specified on either the printer file or the job description, will be used for the spooled output of this job.
- OUTQLIB
- Specifies the name of the CL variable that receives the name of the library that contains the output queue being used by the job for spooled output. The library name is the second part of the qualified output queue name (output-queue/library-name). The variable must be a character variable with a minimum length of 10 characters. If the output queue library name has fewer characters than the variable allows, the value is padded on the right with blanks.
- ACGCDE
- Specifies the name of the CL variable that receives the accounting code for the job. The variable must be a character variable with a minimum length of 15 characters. If the accounting code has fewer characters than the variable allows, the value is padded on the right with blanks.
- DATE
- Specifies, if the job date is to be returned, the name of the CL variable that receives the date assigned to the job by the system when the job was started. The variable must be a character variable with a minimum
length of 6 characters. The job date is returned in the date format for the job.
- SWS
- Specifies, if the job switch settings are being returned, the name of the CL variable that receives the status (on or off) value of the eight job switches used by the job. The job switches are retrieved as a single 8-character value with each of the characters specifying a 1 (on) or 0 (off) as the value of the associated switch. The CL variable must be a character variable with a minimum length of 8 characters.
- TYPE
- Specifies, if the type of job environment is being returned, the name of the CL variable that receives the 1-character value representing the environment of the job. A character value of 0 indicates the job is running as a batch job, and a 1 indicates an interactive job. The variable must be a character variable with a minimum length of 1 character.
- RTNCDE
- Specifies (if the completion status of an RPG, COBOL, DFU, or sort utility program is being returned) the name of the CL variable that receives the 5-digit decimal return code. The return code is set by these programs before they return to the programs that called them. The return code indicates the completion status of the last program (of these types) that has completed processing within the job, as follows:
- 0
- Normal return (RPG, COBOL, DFU, or sort Utility)
- 1
- LR (last record) indicator on (RPG)
- 2
- Error-no halt indicator set (RPG, COBOL, DFU, or sort Utility)
- 3
- Halt indicator set on (one of the RPG indicators H1 through H9)
The CL variable must be a five-position decimal variable with no decimal positions.
- ENDSTS
- Specifies, if checking for a controlled end operation, the name of the CL variable that receives the end status. The single-character value indicates whether a controlled end that affects the job is currently being performed. A value of 1 indicates that the system, the subsystem in which the job is running, or the job itself is being ended; a value of 0 indicates no controlled end is being performed. The CL variable must be a character variable with a minimum length of 1 character.
- RUNPTY
- Specifies the name of the CL variable that receives the 2-digit value, ranging from 1 through 99, that is the run (or processing) priority for the job in which this command is used. This value is the highest run priority allowed for any thread within the job. Individual threads within the job may have a lower run priority. To retrieve the run priority for the thread in which one is running, use the Retrieve Current Attributes (QWTRTVCA) API. For additional information on run priority, refer to this parameter description in the Change Job (CHGJOB) command. The variable must be a 2-digit decimal variable specified with no decimal positions.
- TIMESLICE
- Specifies the name of the CL variable that receives the 7-digit value, ranging from 8 through 9999999, that is the maximum number of milliseconds that a thread within this job can run when it is given processing time. For additional information on time slice, refer to this parameter description under the Change Job (CHGJOB) command. The variable must be a 7-digit decimal variable specified with no decimal positions.
- PURGE
- Specifies the name of the CL variable that receives the special value that indicates whether the job is marked as eligible to move from main storage at the end of a time slice or a long wait state. For additional information on job purging, refer to this parameter description under the Change Job (CHGJOB) command. The variable must be a character variable with a minimum length of 10 characters. If the special value has fewer characters than the variable allows, the value is padded on the right with blanks.
- DFTWAIT
- Specifies the name of the CL variable that receives the 7-digit value, ranging from 1 through 9999999 (or -1 if the value is set to *NOMAX), which is the default for the maximum number of seconds that the system waits for a machine instruction to acquire a resource. For additional information on wait-time, refer to the DFTWAIT parameter description under the Change Job (CHGJOB) command. The variable must be a 7-digit decimal variable specified with no decimal positions.
- USRLIBL
- Specifies the name of the CL variable that receives the user portion of the thread’s library list. The variable must be a character variable with up to 275 variables. Each library name returned is left-justified in an 11-character field and padded on the right with blanks.
- SBMMSGQ
- Specifies the name of the CL variable that receives the name of a message queue. If this parameter is coded for a RTVJOBA command in a CL program which is part of a batch job, the value returned is associated with the MSGQ parameter on the JOB or SBMJOB command which caused the batch job to start running. If *NONE was specified for the MSGQ parameter of the JOB or SBMJOB commands, or the CL program that contains the RTVJOBA command is not part of a batch job, *NONE is returned to the CL variable coded for this parameter. The variable 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.
- SBMMSGQLIB
- Specifies the name of the CL variable that receives the name of the library that contains the message queue described above. (See the SBMMSGQ parameter description above.) The library name is the second part of the qualified message queue name. If *NONE is returned for the SBMMSGQ parameter, it is also returned for this parameter. The variable must be a character variable with a minimum length of 10 characters. If the message queue library name has fewer characters than the variable allows, the value is padded on the right with blanks.
- PRTTXT
- Specifies the name of the CL variable that receives the print text for the job. This must be a character variable with a minimum length of 30 characters. More information on this parameter is in PRTTXT parameter.
- DDMCNV
- Specifies the name of a CL variable that receives the special value that indicates the action taken for DDM conversations on the job. The variable must be a character variable with a minimum length of 5 characters. If the special value has fewer characters than the variable allows, the value is padded on the right with blanks.
- BRKMSG
- Specifies the name of a CL variable that receives the special value that indicates the mode for break message handling that is in effect for the job. The variable must be a character variable with a minimum length of 7 characters. If the special value has fewer characters than the variable allows, the value is padded on the right with blanks.
- DATFMT
- Specifies the name of a CL variable that receives the special value being used as the date format for the job. The variable must be a character variable with a minimum length of 4 characters. If the special value has fewer than 4 characters, the value is padded on the right with blanks.
- DATSEP
- Specifies the name of a CL variable that receives the character being used as the date separator character for the job. The variable must be a character variable with a minimum length of 1 character.
- CURLIB
- Specifies the name of a CL variable that is used to retrieve the name of the current library for the thread. The variable must be a character variable with a minimum length of 10 characters. If the current library name has fewer characters than the variable allows, the value is padded on the right with blanks.
Note: If the thread does not have a current library, a value of *NONE is returned in this variable. - PRTDEV
- Specifies the name of the CL variable that receives the name of the printer device. The variable must be a character variable with a minimum length of 10 characters. If the printer device name has fewer characters than the variable allows, the value is padded on the right with blanks.
- SYSLIBL
- Specifies the name of the CL variable that receives the system portion of the thread’s library list. The variable must be a character variable with up to 165 characters. Each library name returned is left-justified in an 11-character field and padded on the right with blanks.
- CURUSER
- Specifies, if the user name is returned, the 10-character CL variable that receives the name of the current user profile. If the current user name has fewer characters than the variable allows, the value is padded on the right with blanks.
- SUBTYPE
- Specifies, if the SUBTYPE of job environment is being returned, the 1-character CL variable that receives the name of the job environment. The valid character values are:
- Character
- Value
- *
- Job has no subtype
- E
- Job is running as an evoked job
- T
- Job is running as a Multiple Requester Terminal (MRT) job
- J
- Job is running as a prestart job
- P
- Job is running as a print driver
- PRTKEYFMT
- Specifies the name of the CL variable that receives the print key format for the job. The variable must have a minimum length of 7 characters. The special value *NONE, *PRTBDR, *PRTHDR, or *PRTALL is returned.
- TIMSEP
- Specifies the name of a CL variable that receives the character being used as the time separator character for the job. The variable must be a character variable with a minimum length of one character.
- TSEPOOL
- Specifies the name of the CL variable that receives the special value indicating whether interactive jobs are moved to another main storage pool when they reach the time slice end. The variable must be a character variable with a minimum length of 10 characters.
- DEVRCYACN
- Specifies the name of the CL variable that receives the special value indicating the recovery action to take for the job when an I/O error is encountered on the *REQUESTER device for interactive jobs. The variable must be a character variable with a minimum length of 13 characters.
- STSMSG
- Specifies the name of the CL variable that receives the special value indicating how status messages are handled for the job. The variable must be a character variable with a minimum length of 7 characters.
- SRTSEQ
- Specifies the name of the CL variable that receives the name of the sort sequence table used for the job. The special value *LANGIDUNQ, *LANGIDSHR, or *HEX can be returned to the variable. The variable must be a character variable with a minimum length of 10 characters.
- SRTSEQLIB
- Specifies the name of the CL variable that receives the name of the library containing the sort sequence table to be used for the job. The variable must be a character variable with a minimum length of 10 characters. If SRTSEQ is *LANGIDUNQ, *LANGIDSHR, or *HEX, blanks are returned in the variable.
- LANGID
- Specifies the name of the CL variable that receives the value indicating the language identifier to be used for the job. The variable must be a character variable with a minimum length of 3 characters.
- CNTRYID
- Specifies the name of the CL variable that receives the value indicating the country identifier to be used for the job. The variable must be a character variable with a minimum length of 2 characters.
- CCSID
- Specifies the name of a CL variable that receives the CCSID value being used for the job. The variable must be a 5-digit decimal variable with no decimal positions.
- JOBMSGQMX
- Specifies the name of a CL variable that receives the maximum size of the job message queue. The variable must be a 2-digit decimal variable with no decimal position.
- JOBMSGQFL
- Specifies the action that should be taken when the job message queue is full. The variable must have a minimum length of 10 characters. The special value *NOWRAP, *WRAP, or *PRTWRAP is returned.
- DFTCCSID
- Specifies the name of a CL variable that receives the DFTCCSID value being used for the job. The variable must be a 5-digit decimal variable with no decimal positions.
- CYMDDATE
- Specifies the name of the CL variable that receives the date assigned to the job by the system when the job was started. The variable must be a character variable with a minimum length of 7 characters. The job date is returned in the format CYYMMDD, where C is the century, YY is the year, MM is the month and DD is the day.
- DECFMT
- Specifies the name of a CL variable that receives the character being used as the decimal format for the job. The variable must be a character variable with a minimum length of 1 character.
- CHRIDCTL
- Specifies the name of a CL variable that receives the value being used as the character identifier control for the job. The variable must be a character variable with a minimum length of 10 characters.
Example for RTVJOBA
RTVJOBA NBR(&JOBNBR) DATE(&JOBDATE) DFTCCSID(&DFTCSID)
This command retrieves the job number and job date attributes from the job in which this command is located. The 6-digit job number is copied into the CL variable &JOBNBR. The job date is copied into the CL variable &JOBDATE; the values for both &JOBNBR and &JOBDATE must be 6 characters in length. The 5-digit DFTCCSID value is copied into the CL variable &DFTCCSID; this value must be 5 characters in length. The format of the date is determined by the contents of the system value QDATFMT, which controls the system date format.
/* Declare Variables */ DCL &LIBL *CHAR 275 DCL &CHGLIBL *CHAR 285 /* save library list */ RTVJOBA USRLIBL(&LIBL) * * * /* temporarily change library list */ CHGLIBL LIBL(MYLIB QGPL) * * * /* build command string */ CHGVAR &CHGLIBL ('CHGLIBL (' *CAT &LIBL *TCAT ')') /* restore library list */ CALL QCMDEXC (&CHGLIBL 285)
The above command retrieves the user portion of the library list so that it later can be restored from its temporary state, where only MYLIB and QGPL were in the user portion of the library list, to its original state.
If there are no libraries on the user portion of the library list, blanks are returned in the variable. If a library on the library list has been deleted, the value ‘*DELETED’ is put in the variable position for that name.
Usage Notes
Considerations for Attributes Scope and Thread Safety
This command is intended to be used to retrieve job attributes for the job in which the command is used. However, if a job attribute does not exist because the attribute is now supported at the thread level only, then the thread attribute is retrieved for the thread in which this command is used.
The Scope column of Table 1 shows whether the attribute is scoped to the Job to the Thread.
The Threadsafe column of Table 1 indicates if the attributes are considered to be threadsafe.
- Yes
- Attributes marked with a Yes can be retrieved safely from either the initial thread or from a secondary thread.
- No
- An attribute marked with this value is not threadsafe, and should not be retrieved in a multi-threaded job.
Table 1. Attribute, Scope, and Thread Safety
| Attribute | Scope | Threadsafe |
|---|---|---|
| Break message handling (BRKMSG) | Job | Yes |
| Character identifier control (CHRIDCTL) | Job | Yes |
| Coded character set ID (CCSID) | Job | Yes |
| Country ID (CNTRYID) | Job | Yes |
| Current library (CURLIB) | Thread | Yes |
| Current user profile (CURUSER) | Thread | Yes |
| Date format (DATFMT) | Job | Yes |
| Date separator (DATSEP) | Job | Yes |
| DDM conversion handling (DDMCNV) | Job | Yes |
| Decimal format (DECFMT) | Job | Yes |
| Default coded character set identifier (DFTCCSID) | Job | Yes |
| Default wait (DFTWAIT) | Job | Yes |
| Device recovery action (DEVRCYACN) | Job | Yes |
| End status (ENDSTS) | Job | Yes |
| Inquiry message reply (INQMSGRPY) | Job | Yes |
| Job accounting code (ACGCDE) | Job | Yes |
| Job date with century (CYMDDATE) | Job | Yes |
| Job date without century (DATE) | Job | Yes |
| Job message queue full action (JOBMSGQFL) | Job | Yes |
| Job message queue maximum size (JOBMSGQMX) | Job | Yes |
| Job name (JOB) | Job | Yes |
| Job number (NBR) | Job | Yes |
| Job subtype (SUBTYPE) | Job | Yes |
| Job switches (SWS) | Job | Yes |
| Job type (TYPE) | Job | Yes |
| Language ID (LANGID) | Job | Yes |
| Logging Level (LOGLVL) | Job | Yes |
| Logging of CL programs (LOGCLPGM) | Job | Yes |
| Logging Severity (LOGSEV) | Job | Yes |
| Logging Text (LOGTYPE) | Job | Yes |
| Output queue library name (OUTQLIB) | Job | Yes |
| Output queue name (OUTQ) | Job | Yes |
| Print key format (PRTKEYFMT) | Job | Yes |
| Print text (PRTTXT) | Job | Yes |
| Printer device name (PRTDEV) | Job | Yes |
| Program return code (RTNCDE) | Job | No |
| Purge (PURGE) | Job | Yes |
| Run priority (RUNPTY) | Job | Yes |
| Sort sequence (SRTSEQ) | Job | Yes |
| Sort sequence library (SRTSEQLIB) | Job | Yes |
| Status message handling (STSMSG) | Job | Yes |
| Submitter’s message queue library name (SBMMSGQLIB) | Job | Yes |
| Submitter’s message queue name (SBMMSGQ) | Job | Yes |
| System library list (SYSLIBL) | Thread | Yes |
| Time separator (TIMSEP) | Job | Yes |
| Time slice (TIMESLICE) | Job | Yes |
| Time-slice end pool (TSEPOOL) | Job | Yes |
| User library list (USRLIBL) | Thread | Yes |
| User name (USER) | Job | Yes |
Error messages for RTVJOBA
None