TAA Tools
CVTOUTQDTQ      CONVERT OUTPUT QUEUE DATA QUEUE        TAADTQZ

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
					

Added to TAA Productivity tools July 15, 2013


Home Page Up to Top