The Convert Output Queue Data Queue command converts the entries sent
by the system to a data queue if the DTAQ parameter is specified on
CRT/CHGOUTQ. This allows a determination of spooled files that were
output as opposed to the print accounting function which captures
only those files that were actually printed.
In some instances, duplicates may appear and not all spooled files
may cause an entry to be written. Entries are written to the data
queue each time a spooled file goes into the RDY status.
The file output is always OUTQDTQP with a format name of OUTQDTQR.
The model file is TAADTQZP in TAATOOL. The QRCVDTAQ API is used to
read the data queue entries.
Getting started with CVTOUTQDTQ
-------------------------------
** You must have a data queue with a MAXLEN of at least 128 bytes
and be a non-keyed data queue. The LIBA library will be used
in this example.
CRTDTAQ DTAQ(LIBA/DTQ1) MAXLEN(128)
** To allow the system to generate a data queue entry for each
spooled file reaching the RDY status, use CHGOUTQ for an
output queue such as:
CHGOUTQ OUTQ(xxx) DTAQ(LIBA/DTQ1)
Run a command that will cause a spooled file to be created in
the output queue. As spooled files go into the RDY status in
the output queue, the system will write an entry to the DTQ1
data queue.
** You can review the entries in the data queue with:
DSPDTAQ DTAQ(LIBA/DTQ1)
** To convert the entries to a data base file, a typical
CVTOUTQDTQ command would be:
CVTOUTQDTQ DTAQ(LIBA/DTQ1) WAIT(0) OUTLIB(QTEMP)
One record would be written to the OUTQDTQP file in QTEMP for
each entry in the data queue. The entry is automatically
removed from the data queue after the entry is read. Because
WAIT(0) was specified, the command would end when all entries
in the data queue have been converted.
** You can print the entries with:
PRTDB2 FILE(QTEMP/OUTQDTQP)
Note that a spooled file may not exist when the data queue
entries are read and converted. A spooled file could have
been deleted or printed after the data queue entry was written
by the system.
** A special command ENDOUTQDTQ exists to end the CVT function
normally rather than processing any additional data queue
entries. The intent of ENDOUTQDTQ is that if you are using a
long wait time for CVTOUTQDTQ, you may want to end the job
normally.
Try the following test.
ENDOUTQDTQ OUTQ(xxx)
/* Enter a command to cause a spooled file */
CVTOUTQDTQ DTAQ(LIBA/DTQ1) WAIT(0) OUTLIB(QTEMP)
Assuming you had run CVTOUTQDTQ in the prior step, you should
see that no entries are converted. Note that the TAAOUTQDTQ
spooled file is not converted.
** Using DSPDTAQ, you should see spooled file you created is
still in the data queue.
DSPDTAQ DTAQ(LIBA/DTQ1)
** To end the testing example, do the following:
CHGOUTQ OUTQ(xxx) DTAQ(*NONE)
Using the same Data Queue for multiple Output Queues
----------------------------------------------------
You may use the same data queue for multiple output queues. When the
data queue entry is read by CVTOUTQDTQ, it includes the output queue
name where the spooled file exists and the information is included in
the outfile.
RDY Status
----------
The system support may cause multiple entries for a spooled file in
the data queue and does not ensure that a data queue entry will exist
for every spooled file written.
An entry is written to the data queue each time a spooled file
reaches the RDY status. This occurs in the following typical cases:
** A spooled file is initially written and the SCHEDULE parameter
is *FILEEND or *IMMED.
** SCHEDULE(*JOBEND) is used and the job ends (the status is
changed to RDY by the system).
** A spooled file in the RDY status, is held (causes the status
to be changed to HLD), and then released which causes the
status to revert to RDY. There would be an additional entry
for the spooled file. One data queue entry is written for
each time the spooled file reaches the RDY status.
** A spooled file in the RDY status is moved to an output queue
which has specified the DTAQ parameter.
Conversely, there may be spooled files written to an output queue
that never reach the RDY status. For example, they could be written
using an OVRPRTF command which specifies HOLD(*YES) and then deleted.
Or SCHEDULE(*JOBEND) could be used and one or more spooled files for
the job could be deleted before the job ends.
OUTQDTQP fields
---------------
You can review the field descriptions in the outfile with:
DSPFMT FILE(TAADTQZP)
Most of the fields are obvious, but here are a few comments.
The ODSYSN field (system name) is taken from the data queue entry and
reflects the system that created the spooled file (it may not be the
current system).
The ODCVTD and ODCVTT fields (convert date and time) reflect the date
and time the data base record was written. The date/time may not be
the same for all records written on the same use of CVTOUTQDTQ.
The qualified job field names (ODJOB, ODUSER, and ODJNBR) are from
the job that created the spooled file. The user may not be the
current owner of the spooled file.
The ODOPND and OPOPNT fields (spooled file open date and time) will
be the same if multiple entries exist for the same spooled file.
Additional system support for the DTAQ parameter
------------------------------------------------
The system can provide multiple formats for the QRCVDTAQ API.
The default for just specifying the DTAQ parameter for an output
queue causes a type '01' format to be written to the data queue.
There are other formats available, but only the '01' format is
supported by CVTOUTQDTQ.
To understand the full system support for the DTAQ parameter, use the
IBM supplied Information center. Scan for 'creating data queues
associated with an output queue'. Three different formats are
supported by the system.
CVTOUTQDTQ uses the QRCVDTAQ API to access the entries. It ensures
the entries are type '01' and converts the information from the
format to the outfile.
Job and Print Accounting support
--------------------------------
The system Job Accounting support keeps track of the number of print
or spooled files created, the number of lines, and the number of
pages. It does not track the individual files (only a summary is
provided). If you request job accounting support from the system, a
journal entry will be written when a job completes and if the
CHGACGCDE command is used. The TAA tool JOBACG may be helpful in
setting up and working with job accounting information.
The system Print Accounting support keeps track of the number of
files actually printed regardless of whether they were first spooled
or printed directly. It tracks the individual files including the
number of pages/lines and the device used. If you request print
accounting support from the system, a journal entry is written when a
file is printed. The TAA tool PRTACG may be helpful in setting up
and working with print accounting information.
CVTOUTQDTQ escape messages you can monitor for
----------------------------------------------
TAA9891 No entries exist to be converted.
Escape messages from based on functions will be re-sent.
CVTOUTQDTQ Command parameters *CMD
-----------------------------
DTAQ The qualified name of the data queue to be
converted. It must be at least 128 bytes in length
and be non-keyed.
The library qualifier defaults to *LIBL. A specific
library or *CURLIB may also be used.
WAIT The wait time to be used when receiving an entry.
The entry is removed after it is received.
0 is the default meaning when no more entries exist
to be converted, the command ends normally if at
least one entry existed.
A number up to 99999 (about 28 hours) may be
specified. If the number has not been reached, the
command goes to sleep and wakes up when a new entry
arrives.
*NOMAX may be entered which is the same as 99999.
OUTLIB The library in which the OUTQDTQP file will be
placed. The default is *LIBL. If the file does not
already exist, a library must be specified.
OUTMBR The member of the OUTQDTQP file to be used. If the
member does not exist, it is added. The default is
OUTQDTQP.
REPLACE A *YES/*NO value for whether the member should be
cleared before writing records into it. The default
is *YES.
*NO may be specified to add records to an existing
file.
ENDOUTQDTQ Command parameters *CMD
-----------------------------
OUTQ The qualified name of the output queue to end the
use of CVTOUTQDTQ. A special entry is sent to the
data queue assigned to the output queue to end the
CVTOUTQDTQ function.
The library qualifier defaults to *LIBL. A specific
library or *CURLIB may also be used.
Restrictions
------------
** The data queue must be at least 128 bytes and be non-keyed.
** Only the type '01' format used by the QRCVDTAQ API is
supported.
** In some instances, duplicates may appear and not all spooled
files may cause an entry to be written. (see the prior
comments about the system support).
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKOBJ3 Check object 3
DUPTAADBF Duplicate TAA data base file
EDTVAR Edit variable
RSNLSTMSG Resend last message
RTVDTAQD Retrieve data queue description
RTVOUTQA Retrieve output queue attributes
RTVDAT Retrieve date
SNDCOMPMSG Send completion message
SNDESCINF Send escape information
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CVTOUTQDTQ *CMD TAADTQZ QATTCMD
ENDOUTQDTQ *CMD TAADTQZ2 QATTCMD
TAADTQZC *PGM CLP TAADTQZC QATTCL
TAADTQZC2 *PGM CLP TAADTQZC2 QATTCL
TAADTQZR *PGM RPG TAADTQZR QATTRPG
TAADTQZP *FILE PF TAADTQZP QATTDDS
Structure
---------
CVTOUTQDTQ Cmd
TAADTQZC CL pgm
TAADTQZR RPG pgm
ENDOUTQDTQ
TAADTQZC2 CL pgm
|
