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 place the values into the specified variable. The attributes are retrieved for the job 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:

1. This command is valid only within a CL program or a REXX procedure.
2. This command is conditionally threadsafe. Refer to Considerations for Attribute Scope and Thread Safety for additional information.

Considerations for Attribute 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 shows whether the attribute is scoped to the Job or to the Thread.

The Threadsafe column indicates if the attributes are considered to be threadsafe.

Yes: - Attributes marked with this value can be retrieved safely from either the initial thread or from a secondary thread.

No: - Attributes marked with this value are not threadsafe, and should not be retrieved in a multi-threaded job.

Attribute Scope and Thread Safety Table:

Attribute                                            Scope    Threadsafe
----------------------------                         ------   ----------
ASP group name (ASPGRP)                              Thread       Yes
Break message handling (BRKMSG)                      Job          Yes
Character identifier control (CHRIDCTL)              Job          Yes
Coded character set ID (CCSID)                       Job          Yes
Country or region 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
Day of week (DAYOFWEEK)                              Job          Yes
DDM conversation 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 local date and time (DATETIME)                   Job          Yes
Job log output (LOGOUTPUT)                           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
Resource affinity group (RSCAFNGRP)                  Job          Yes
Run priority (RUNPTY)                                Job          Yes
Sort sequence (SRTSEQ)                               Job          Yes
Sort sequence library (SRTSEQLIB)                    Job          Yes
Spooled file action (SPLFACN)                        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
Thread resource affinity (THDRSCAFN)                 Thread       Yes
Time separator (TIMSEP)                              Job          Yes
Time slice (TIMESLICE)                               Job          Yes
Time-slice end pool (TSEPOOL)                        Job          Yes
Time zone abbreviated name (TIMZONABBR)              Job          Yes
Time zone description (TIMZON)                       Job          Yes
Time zone full name (TIMZONFULL)                     Job          Yes
Time zone offset (TIMOFFSET)                         Job          Yes
User library list (USRLIBL)                          Thread       Yes
User name (USER)                                     Job          Yes
Year offset (YEAROFS)                                Job          Yes

Parameters

CL var for JOB (10) (JOB)

Specifies 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.

CL var for USER (10) (USER)

Specifies 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.

CL var for NBR (6) (NBR)

Specifies the name of the CL variable that receives the 6-character number assigned to the job by the system. The job number is the first part of the qualified job name (job-number/user-name/job-name).

CL var for CURUSER (10) (CURUSER)

Specifies the name of the CL variable that receives the name of the current user profile. The variable must be a character variable with a minimum length of 10 characters.

CL var for TYPE (1) (TYPE)

Specifies, the name of the CL variable that receives the 1-character value representing the environment of the job. A character value of 0 indicates that 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.

CL var for SUBTYPE (1) (SUBTYPE)

Specifies the name of the CL variable that receives the subtype value for the environment of the job. The variable must be a character variable with a minimum length of 1 character. The following values can be returned:

Value

Environment

*

The job has no subtype

E

The job is running as an evoked job

T

The job is running as a Multiple Requester Terminal (MRT) job

J

The job is running as a prestart job

P

The job is running as a print driver

CL var for SYSLIBL (165) (SYSLIBL)

Specifies the name of the CL variable that receives the system portion of the thread's library list. Each library name returned is left-justified in an 11-character field and padded on the right with blanks. The variable must be a character variable with a minimum of 165 characters.

CL var for CURLIB (10) (CURLIB)

Specifies the name of a CL variable that receives the name of the current library for the thread. The variable must be a character variable with a minimum length of ten characters.

Note: If the thread does not have a current library, a value of *NONE is returned in this variable.

CL var for USRLIBL (2750) (USRLIBL)

Specifies the name of the CL variable that receives the user portion of the thread's library list. Each library name returned is left-justified in an 11-character field and padded on the right with blanks. If the CL variable is too small for the library list, an exception is signaled and no library names are returned. The variable must be a character variable with a minimum length of 275 characters. A character variable with a minimum length of 2750 characters is needed when the user portion of the library list contains 250 library names.

CL var for ASPGRP (10) (ASPGRP)

Specifies the name of a CL variable that receives the auxiliary storage pool (ASP) group name. The variable must be a character variable with a minimum length of 10 characters. The special value *NONE is returned if there is no ASP group for the thread.

CL var for LOGLVL (1) (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 being used to determine the type of message information logged in the job log. The variable must be a character variable with a minimum length of 1 character.

CL var for LOGSEV (2 0) (LOGSEV)

Specifies the name of the CL variable that receives the 2-digit value, ranging from 00 through 99, which is the severity level that is used in conjunction with the logging level to determine which error messages are logged in the job log. The variable must be a 2-digit decimal variable specified with no decimal positions.

CL var for LOGTYPE (10) (LOGTYPE)

Specifies the name of the CL variable that receives the special value that indicates the level of text that appears for any message that is written to the job log. The variable must be a character variable with a minimum length of 10 characters.

CL var for LOGCLPGM (10) (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. The variable must be a character variable with a minimum length of 10 characters.

CL var for LOGOUTPUT (10) (LOGOUTPUT)

Specifies the name of the CL variable that receives the special value that indicates how the job's job log is to be produced when the job completes. The variable must be a character variable with a minimum length of 10 characters. The special value *JOBEND, *JOBLOGSVR, or *PND is returned.

CL var for JOBMSGQMX (2 0) (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 positions.

CL var for JOBMSGQFL (10) (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.

CL var for INQMSGRPY (10) (INQMSGRPY)

Specifies the name of the CL variable that receives the special value that indicates how inquiry messages are being handled by the job. The variable must be a character variable with a minimum length of 10 characters.

CL var for STSMSG (7) (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.

CL var for BRKMSG (7) (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 seven characters.

CL var for DEVRCYACN (13) (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.

CL var for RTNCDE (5 0) (RTNCDE)

Specifies the name of the CL variable that receives the 5-digit decimal return code of an RPG, COBOL, DFU, or sort utility program. The return code is set by these programs before they return to the programs that call 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-digit decimal variable with no decimal positions.

CL var for ENDSTS (1) (ENDSTS)

Specifies the name of the CL variable that receives the cancellation status. The single-character value indicates whether a controlled cancellation that affects the job is currently being performed. A value of 1 indicates that either the system, the subsystem in which the job is running, or the job itself is being canceled; a 0 indicates no controlled cancellation is being performed. The CL variable must be a character variable with a minimum length of 1 character.

CL var for PRTDEV (10) (PRTDEV)

Specifies the name of a CL variable that receives the name of the printer device. The variable must be a character variable with a minimum length of 10 characters.

CL var for OUTQ (10) (OUTQ)

Specifies the name of the CL variable that receives the name of the output queue that is used by the job for spooled output. The variable must be a character variable with a minimum length of 10 characters.

CL var for OUTQLIB (10) (OUTQLIB)

Specifies the name of the CL variable that receives the name of the library containing the output queue that is used by the job for spooled output. The variable must be a character variable with a minimum length of 10 characters.

CL var for SPLFACN (10) (SPLFACN)

Specifies the name of a CL variable that receives the special value indicating whether spooled files are kept with the job or detached when the job ends. The variable must be a character variable with a minimum length of 10 characters. The special value *KEEP or *DETACH is returned.

CL var for PRTTXT (30) (PRTTXT)

Specifies the name of the CL variable that receives the print text for the job. The variable must be a character variable with a minimum length of 30 characters.

CL var for PRTKEYFMT (10) (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 10 characters. The special value *NONE, *PRTBDR, *PRTHDR, or *PRTALL is returned.

CL var for SRTSEQ (10) (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.

CL var for SRTSEQLIB (10) (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.

CL var for LANGID (3) (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.

CL var for CNTRYID (2) (CNTRYID)

Specifies the name of the CL variable that receives the value indicating the country or region identifier to be used for the job. The variable must be a character variable with a minimum length of 2 characters.

CL var for CCSID (5 0) (CCSID)

Specifies the name of a CL variable that receives the coded character set identifier value being used. The variable must be a 5-digit decimal variable specified with no decimal positions.

CL var for DFTCCSID (5 0) (DFTCCSID)

Specifies the name of a CL variable that receives the default coded character set identifier value being used for the job. The variable must be a 5-digit decimal variable with no decimal positions.

CL var for CHRIDCTL (10) (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.

CL var for DECFMT (1) (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.

CL var for DATFMT (4) (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 four characters.

CL var for DATSEP (1) (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 one character.

CL var for TIMSEP (1) (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.

CL var for DATE (6) (DATE)

Specifies the name of the CL variable that receives the date assigned to the job by the system when the job is started. The variable must be a character variable with a minimum length of 6 characters. The job date is returned in the job-date format.

CL var for CYMDDATE (7) (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.

CL var for DATETIME (20) (DATETIME)

Specifies the name of a CL variable that receives the current local date and time of the job. The variable must be a character variable with a minimum length of 20 characters. The local job date and time is returned in the format YYYYMMDDHHNNSSXXXXXX where YYYY is the year, MM is the month, DD is the day, HH is the hours, NN is the minutes, SS is the seconds, and XXXXXX is the microseconds.

CL var for DAYOFWEEK (4) (DAYOFWEEK)

Specifies the name of a CL variable that receives the current local day of the week for the job. The variable must be a character variable with a minimum length of 4 characters. The special value *SUN, *MON, *TUE, *WED, *THU, *FRI, or *SAT is returned.

CL var for TIMZON (10) (TIMZON)

Specifies the name of a CL variable that receives the name of the current time zone description used to calculate local job time. The variable must be a character variable with a minimum length of 10 characters.

CL var for TIMZONABBR (10) (TIMZONABBR)

Specifies the name of a CL variable that receives the current abbreviated, or short, name for the time zone used to calculate local job time. This value will contain either the Standard Time or Daylight Saving Time abbreviated name depending on whether or not Daylight Saving Time is in effect. The variable must be a character variable with a minimum length of 10 characters.

CL var for TIMZONFULL (50) (TIMZONFULL)

Specifies the name of a CL variable that receives the current full, or long, name for the time zone used to calculate local job time. This value will contain either the Standard Time or Daylight Saving Time full name depending on whether or not Daylight Saving Time is in effect. The variable must be a character variable with a minimum length of 50 characters.

CL var for TIMOFFSET (3 0) (TIMOFFSET)

Specifies the name of a CL variable that receives the current offset in minutes used to calculate local job time. This value has been adjusted for Daylight Saving Time if necessary. The variable must be a 3-digit decimal variable with no decimal positions.

CL var for YEAROFS (3 0) (YEAROFS)

Specifies the name of a CL variable that receives the year offset for the job. This value specifies the number of years between the current Gregorian year and the current year in the calendar system used by the job. The range is -140 to 140. The variable must be a 3-digit decimal variable with no decimal positions.

CL var for ACGCDE (15) (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.

CL var for SWS (8) (SWS)

Specifies the name of the CL variable that receives the 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 or 0 as the value of the associated switch. The CL variable must be a character variable with a minimum length of 8 characters.

CL var for RUNPTY (2 0) (RUNPTY)

Specifies the name of the CL variable that receives the 2-digit value, ranging from 1 through 99, that is the 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. The variable must be a 2-digit decimal variable specified with no decimal positions.

CL var for TIMESLICE (7 0) (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. The variable must be a 7-digit decimal variable specified with no decimal positions.

CL var for PURGE (10) (PURGE)

Specifies the name of the CL variable that receives the special value which indicates whether this job is eligible to be moved out of main storage and placed into auxiliary storage at the end of a time slice or when entering a long wait. 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.

CL var for DFTWAIT (7 0) (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), that is the default for the maximum number of seconds that the system waits for a machine instruction to acquire a resource. The variable must be a 7-digit decimal variable specified with no decimal positions.

CL var for SBMMSGQ (10) (SBMMSGQ)

Specifies the name of the CL variable that receives the name of a message queue. The variable must be a character variable with a minimum length of 10 characters.

CL var for SBMMSGQLIB (10) (SBMMSGQLIB)

Specifies the name of the CL variable that receives the name of the library containing the message queue described previously. The variable must be a character variable with a minimum length of 10 characters.

CL var for DDMCNV (5) (DDMCNV)

Specifies the name of a CL variable that receives the special value that indicates the action taken for distributed data management (DDM) conversations on the job. The variable must be a character variable with a minimum length of 5 characters.

CL var for TSEPOOL (10) (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.

CL var for THDRSCAFN (20) (THDRSCAFN)

Specifies the name of a CL variable that receives the special value indicating whether or not secondary threads have affinity to the same group of system resources as the initial thread. The special value *NOGROUP or *GROUP is returned in the first 10 characters. The second 10 characters contain the special value indicating the level of affinity. The special value *NORMAL or *HIGH is returned. The variable must be a character variable with a minimum length of 20 characters.

CL var for RSCAFNGRP (10) (RSCAFNGRP)

Specifies the name of a CL variable that receives the special value indicating that the job has affinity to the same group of processors and memory as other jobs using the same routing entry or prestart job entry. The variable must be a character variable with a minimum length of 10 characters. The special value *NO or *YES is returned.

Examples

RTVJOBA   NBR(&JOBNBR)  DATE(&JOBDATE)  DFTCCSID(&DFTCSID)

This command retrieves the job number, job date, and default coded character set identifier for the job in which this command is run. 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 2750
DCL   &CHGLIBL *CHAR 2760
/*  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 2760)

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.

Error messages

*ESCAPE Messages

CPF098A

USRLIBL parameter size is too small.

CPF9899

Error occurred during processing of command.