TAA Tools
RTVJOBSTS       RETRIEVE JOB STATUS                    TAAJOBP

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.

   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
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top