The Retrieve Job Status command allows you to return a status of
whether a job is on the job queue, is active or is on the output
queue. A fully qualified job name or a less than fully qualified job
name may be entered. A generic job or user name may also be used.
You may request a status (*ALL *JOBQ *ACTIVE *OUTQ).
If a less than fully qualified job name is used, there may be
duplicates. Return values occur for the first or last job and a
count of the number of jobs. Informational messages are sent for
each duplicate. The definition of 'first' or 'last' is determined by
the DUPJOBRQS parameter.
An internal work space is used which will hold a maximum of 546 jobs.
Only the jobs in the internal work space are considered when
determining how the options on DUPJOBRQS will be handled.
** *FIRST causes the job with the lowest job number to be
returned. If the job numbers wrap, it may not be the first.
** *FIRSTDATE causes the job with the earliest date/time value
for when the job entered the system to be returned.
** *LAST causes the job with the highest job number to be
returned.
** *LASTDATE causes the job with the latest date/time value for
when the job entered the system to be returned.
A typical command to determine the status of a qualified job name
would be:
RTVJOBSTS JOB(123456/QPGMR/PAYROLL) RTNSTS(&RTNSTS)
IF (&RTNSTS *EQ '*ACTIVE') DO ...
Another typical use is where you want to know the qualified job name
of the job named PAYROLL. In the following command, &RTNUSER and
&RTNJOBNBR would contain the rest of the fully qualified job name.
RTVJOBSTS JOB(PAYROLL) STATUS(*ACTIVE) RTNUSER(&RTNUSER)
RTNJOBNBR(&RTNJOBNBR)
If a simple job name is used, there may be duplicates. Assume if
there is only one job active of the simple name (e.g. your current
job), you want to do some set of code:
RTVJOBSTS JOB(PAYROLL) STATUS(*ACTIVE) NBROFJOBS(&NBROFJOBS)
IF (&NBROFJOBS *EQ 1) DO ...
Either or both the job and user name may be generic values such as:
RTVJOBSTS JOB(PAY*) USER(SMI*) STATUS(*ACTIVE)
NBROFJOBS(&NBROFJOBS)
IF (&NBROFJOBS *EQ 1) DO ...
If no jobs meet the criteria, CPF9898 is sent as an escape message.
The function is implemented using the QUSLJOB API.
Command parameters *CMD
------------------
JOB The qualified job name of the job to be retrieved.
Any of the following combinations are valid:
JOB
JOB and USER
JOB and USER and JOBNBR
A specific JOB, a generic job, or *ALL may be
specified.
If *ALL is specified, you would normally request a
specific or generic USER name. *ALL is the default.
A specific USER, a generic user name, *CURRENT, or
*ALL may be specified. If *ALL is specified, you
would normally use a specific or generic JOB name.
A specific JOBNBR may be specified or *ALL. *ALL is
the default.
STATUS The status of the job to be accessed. The default
is *ALL. *JOBQ, *ACTIVE or *OUTQ may be specified.
DUPJOBRQS The request for which job to return if duplicate
jobs exist. RTVJOBSTS uses an internal work space
that will hold 546 jobs. If more than 546
duplicates are found, the options may not return the
correct information.
*FIRST is the default for the first job (lowest job
number) with a duplicate name based on the values
entered. This allows a return of the first job
number of a duplicate set of job names.
*LAST may be specified to return the information for
the last job with a duplicate name (highest job
number).
*FIRSTDATE may be specified to return the job with
the lowest date/time that the job entered the
system. This may be helpful if the command is used
when job numbers wrap.
*LASTDATE may be specified to return the job with
the highest date/time that the job entered the
system. This may be helpful if the command is used
when job numbers wrap.
CURUSER The 'current user' to select for if a 'swap' of user
profiles has occurred. For example, you can bypass
jobs with the same job name and user name that do
not have the specified current user profile.
*ALL is the default meaning any current user profile
associated with the specified job.
A specific user profile name may be entered or the
special value *USER meaning the user name of the
current job. This will affect the list of jobs
returned, the RTN* variables, and the NBROFJOBS
count.
RTNSTATUS If you specified STATUS(*ALL), the RTNSTATUS
parameter can be used to determine what status the
job is in. The return variable must be declared as
*CHAR LEN(10) and will contain *JOBQ, *ACTIVE, or
*OUTQ.
RTNJOB If you specified JOB(*ALL), the RTNJOB parameter can
be used to determine the job name. The return
variable must be declared as *CHAR LEN(10). See
also JOBLIST/JOBLIST2.
RTNUSER If you specified a simple job name, the RTNUSER
parameter can be used to determine the user name of
the job. The return variable must be declared as
*CHAR LEN(10).
RTNJOBNBR If you specified a simple job name, the RTNJOBNBR
parameter can be used to determine the job number of
the job. The return variable must be declared as
*CHAR LEN(6). See also JOBLIST/JOBLIST2.
NBROFJOBS If you specified a simple job name, there may be
duplicate jobs that match the same job name and
status specified. The return variable must be
specified as *DEC LEN(5 0). If the value is other
than 1, informational messages are sent for the
duplicate jobs. See also JOBLIST/JOBLIST2.
JOBLIST If a DUPJOBQRS value of *LAST or *LASTDATE is
specified, this return variable will contain the
list of jobs that make up the duplicates. Only the
first 120 are returned. Each entry is 60 bytes made
up of Job, User, Job number, Status, and
entry-date-time.
If the number of jobs is greater than 120, the
information returned for RTNJOB, RTNUSER, and
RTNJOBNBR will not be correct. Use JOBLIST2 to
increase the size that can be returned.
This is an optional return variable that if used
must be specified as *CHAR LEN(7200).
JOBLIST2 If a DUPJOBQRS value of *LAST or *LASTDATE is
specified, this return variable will contain the
list of jobs that make up the duplicates. Only the
first 546 are returned. Each entry is 60 bytes made
up of Job, User, Job number, Status, and
entry-date-time.
If the number of jobs is greater than 546, the
information returned for RTNJOB, RTNUSER, and
RTNJOBNBR will not be correct.
This is an optional return variable that if used
must be specified as *CHAR LEN(32767).
Restrictions
------------
** Because the command provides a return variable, it can only be
used in a CL program.
** The RTN job information may not be correct if more than the
first 120 are returned in the JOBLIST return variable. See
also the restrictions described for the parameter.
** If more than 546 jobs meet the selection criteria, the first
546 are returned in the JOBLIST2 return variable. See also
the restrictions described for the parameter.
** If the 120/546 limits are exceeded, a diagnostic is sent, but
the command will complete normally.
Prerequisites
-------------
The following TAA Tools must be on your system:
CRTUSRSPC Create user space
RTVUSRSPCE Retrieve user space entry
RTVUSRSPCI Retrieve user space initialization
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVJOBSTS *CMD TAAJOBP QATTCMD
TAAJOBPC *PGM CLP TAAJOBPC QATTCL
|
