RTVOUTDTAQ RETRIEVE OUTPUT QUEUE DATA QUEUE TAASPOD |
The Retrieve Output Queue Data Queue command retrieves the
information about a spooled file that has just entered the RDY status
in an output queue. A data queue must be created to receive the data
queue entries. This allows a CL program to be written to perform a
typical task such as moving spooled files in a RDY status to a
different output queue.
RTVOUTDTAQ would normally be used in a batch job that is waiting for
a spooled file to become RDY. The batch job would continue to loop
on the RTVOUTDTAQ command for each spooled file. See the later
coding for a typical use.
You must have *JOBCTL special authority to use RTVOUTDTAQ.
System support
--------------
The system supports the capability to send an entry to a data queue
when a spooled file enters the RDY status in an output queue (DTAQ
parameter on CRT/CHGOUTQ). The entry is sent only when a spooled
file is in the RDY status. Typical reasons for entering the RDY
status:
** The spooled file is specified as SCHEDULE(*FILEEND) and the
file is complete.
** The spooled file is specified as SCHEDULE(*JOBEND) and the job
is complete.
** The spooled file is held and then released.
** The spooled file was specified as SAVE(*YES). After printing
the status is SAV. If the file is released, it goes to the
RDY status.
Note that no entry if sent is the spooled file is deleted, changed,
held etc. Only a change (such as a new spooled file) that places a
spooled file in the RDY status will cause a data queue entry to be
sent.
If the output queue already contains spooled files when the function
is requested, the existing spooled files do not cause a data queue
entry to be sent.
Multiple output queues may specify the same data queue.
Typical use of RTVOUTDTAQ
-------------------------
A typical use of RTVOUTDTAQ is to take some action when a spooled
file goes into the RDY status. The example used assumes that you
want to move such spooled files to a different output queue.
Assume the output queue to move from is OUTQFROM and the output queue
to move to is OUTQTO.
You must first create a data queue (assume DTAQ1) with a length of at
least 128 bytes.
CRTDTAQ DTAQ(DTAQ1) MAXLEN(128)
It is not necessary to use the CHGOUTQ DTAQ parameter to identify the
data queue to be used. RTVOUTDTAQ internal processing will do
CHGOUTQ for you. If the DTAQ parameter has already been specified,
it must be the same data queue as named on RTVOUTDTAQ.
When the program with RTVOUTDTAQ ends, the data queue parameter will
be retained as specified.
You would need a CL program submitted to batch that begins by moving
any existing spooled files to another output queue and clears the
data queue of any existing entries. The program would then loop on
the RTVOUTDTAQ command and move each spooled file.
The following sample code is in a format to be copied into a CL
program.
PGM
DCL &JOB *CHAR LEN(10)
DCL &USER *CHAR LEN(10)
DCL &JOBNBR *CHAR LEN(6)
DCL &SPLF *CHAR LEN(10)
DCL &SPLNBR *CHAR LEN(6)
DCL &RTNOUTQ *CHAR LEN(10)
DCL &RTNOUTQL *CHAR LEN(10)
DCL &SYSNAM *CHAR LEN(8)
DCL &CRTDAT *CHAR LEN(7)
DCL &CRTTIM *CHAR LEN(6)
DCL &RCDTYP *CHAR LEN(2)
/********************************************/
/* */
/* Move any existing spooled files */
/* to the second output queue */
/* */
/********************************************/
CHGALLSPLF OUTQ(OUTQFROM) TOOUTQ(OUTQTO) CURSTS(*RDY)
/********************************************/
/* */
/* Clear the data queue */
/* */
/********************************************/
CLRDTAQ DTAQ(DTAQ1)
/********************************************/
/* */
RTV: /* Retrieve spooled file in RDY */
/* status */
/* */
/********************************************/
RTVOUTDTAQ OUTQ(OUTQFROM) DTAQ(DTAQ1) +
JOB(&JOB) USER(&USER) JOBNBR(&JOBNBR) +
SPLF(&SPLF) SPLNBR(&SPLNBR) +
RTNOUTQ(&RTNOUTQ) RTNOUTQLIB(&RTNOUTQL) +
SYSNAM(&SYSNAM) CRTDAT(&CRTDAT) +
CRTTIM(&CRTTIM) RCDTYP(&RCDTYP)
CHGSPLFA FILE(&SPLF) JOB(&JOB *TCAT '/' *CAT +
&USER *TCAT '/' *CAT &JOBNBR) +
SPLNBR(&SPLNBR) OUTQ(OUTQTO)
GOTO RTV
ENDPGM
The program would continue to loop waiting for a new entry to occur.
The default is WAIT(*NOMAX) to wait forever.
You would end the batch job when the function is no longer needed.
RTVOUTDTAQ escape messages you can monitor for
----------------------------------------------
TAA9891 The WAIT time has expired.
Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
OUTQ The qualified name of the output queue to be used to
send entries for when a spooled file goes into the
RDY status.
The library value defaults to *LIBL. *CURLIB or a
specific output queue may be named.
DTAQ The data queue to be sent an entry when a spooled
file in the specified output queue becomes in the
RDY status.
Note that no entry is sent if spooled files in the
RDY status already exist in the output queue when
the RTVOUTDTAQ begins. Note that no entry is sent
if the spooled file is placed in a HLD status, is
deleted, etc. An entry will be sent if the spooled
file is in a HLD status and is changed to RDY.
An entry is sent if a spooled file is in the SAV
status and is released to the RDY status.
The library value defaults to *LIBL. *CURLIB or a
specific output queue may be named.
WAIT The number of seconds to wait before a timeout
occurs. *NOMAX is the default meaning the program
will never be returned to unless a data queue entry
appears.
If a specific wait time is entered and expires,
TAA9891 is sent as an escape message.
JOB The job name of the spooled file that is retrieved.
This is an optional return variable that if used
must be specified as *CHAR LEN(10).
USER The user who created the spooled file that is
retrieved. This is an optional return variable that
if used must be specified as *CHAR LEN(10).
JOBNBR The job number of the spooled file that is
retrieved. This is an optional return variable that
if used must be specified as *CHAR LEN(6).
SPLF The spooled file name that is retrieved. This is an
optional return variable that if used must be
specified as *CHAR LEN(10).
SPLNBR The spooled file number of the spooled file that is
retrieved. This is an optional return variable that
if used must be specified as *CHAR LEN(6).
RTNOUTQ The output queue of the spooled file that is
retrieved. This is an optional return variable that
if used must be specified as *CHAR LEN(10).
Note that it is possible to have multiple output
queues use the same data queue.
RTNOUTQLIB The output queue library of the spooled file that is
retrieved. This is an optional return variable that
if used must be specified as *CHAR LEN(10).
SYSTEM The system name where the spooled file was created
that is retrieved. This is an optional return
variable that if used must be specified as *CHAR
LEN(8).
CRTDAT The create date of the spooled file that is
retrieved in CYMD format. This is an optional
return variable that if used must be specified as
*CHAR LEN(7).
CRTTIM The create time of the spooled file that is
retrieved in in HHMMSS format. This is an optional
return variable that if used must be specified as
*CHAR LEN(6).
RCDTYP The record type of the data queue entry that is
retrieved. The system supports only a single type
'01' which will be retrieved. This is an optional
return variable that if used must be specified as
*CHAR LEN(2).
Restrictions
------------
Because the command returns variables, RTVOUTDTAQ may only be used in
a CL program.
You must have *JOBCTL special authority to use RTVOUTDTAQ.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKJOBCTL Check *JOBCTL special authority
EDTVAR Edit variable
SNDDTAQ Send data queue
RTVDTAQD Retrieve data queue description
RTVOUTQA Retrieve output queue attributes
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use. You must create a data queue of with
a MAXLEN of at least 128 bytes.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVOUTDTAQ *CMD TAASPOD QATTCMD
TAASPODC *PGM CLP TAASPODC QATTCL
|
Added to TAA Productivity tools September 15, 2006
