Data queue support

There are two different types of data queue support for spooled files.

  • Data queue support on output queues

    Support is available to optionally associate a data queue with an output queue using the Create Output Queue (CRTOUTQ) or Change Output Queue (CHGOUTQ) command. Entries are logged in the data queue when spooled files are in ready (RDY) status on the output queue. A user program can determine when a spooled file is available on an output queue using the Receive Data Queue (QRCVDTAQ) API to receive information from a data queue. See the Receive Data Queue (QRCVDTAQ) API in the Programming topic for more information.

    Each time a spooled file on the output queue reaches RDY status an entry is sent to the data queue. A spooled file can have several changes in status (for example, ready (RDY) to held (HLD) to release (RLS) to ready (RDY) again) before it is taken off the output queue. These status changes result in entries in the data queue for a spooled file each time the spooled file goes to RDY status.

    A spooled file can reach RDY status in these instances:

    • When initially spooled on the output queue.
    • When the spooled file is opened and the schedule parameter value is *IMMED.
    • When a job completes and the spooled file schedule parameter value is *JOBEND.
    • When the spooled file is released.
    • When a spooled file is moved to this output queue from another output queue.
    • When a writer is ended immediately while printing a spooled file (the spooled file status is reset from WTR to RDY).
    The data queue must be created with a maximum message length (MAXLEN) parameter value of at least 128 bytes. The sequence (SEQ) parameter value should be *FIFO or *LIFO. The format of the CRTDTAQ command is: 
    CRTDTAQ DTAQ (<library name>/<data queue name>) MAXLEN(128) SEQ(*LIFO)

    The Create Output Queue (CRTOUTQ) and Change Output Queue (CHGOUTQ) commands have a data queue (DTAQ) parameter, which is used to specify the data name. An error occurs when using these commands if the specified data queue does not exist or if the user creating or changing the output queue does not have use authority to the data queue.

    After a data queue is associated with an output queue, any spooled file that is placed on the output queue in a ready status causes an entry to be placed on the data queue. The data queue entry is added regardless of the authority the user generating the spooled file has to the data queue.

    The entry in the data queue has a format of record type 01. See Record type 01 data queue entry format for a description of the information contained in record type 01.

  • Environment variable data queue support

    Using the Add Environment Variable (ADDENVVAR) or Change Environment Variable (CHGENVVAR) command, you can associate a data queue with a job or the system. As spooled files are created, the entries are logged in the data queue. Using the Receive Data Queue (QRCVDTAQ) API to receive information from the data queue, a user program can determine when a spooled file has been created by the job or by the system. Use the environment variable data queue support if you need to determine the identity of a spooled file that was stored under a QPRTJOB and was created by a job such as a remote command system job.

    Using the CL command ADDENVVAR, and specifying a fully qualified data queue name for the environment variable QIBM_NOTIFY_CRTSPLF, you can associate a data queue with a job or the system.

    The command use is as follows: 
    ADDENVVAR ENVVAR(QIBM_NOTIFY_CRTSPLF)
          VALUE('*DTAQ <library name>/<data queue name>')
          LEVEL(*JOB | *SYS)
    The data queue must be created with a record length of at least 144 bytes. The data queue must also have a public authority of *USE, or you need to grant the QSPL user profile *USE private authority to the data queue. You must ensure that the containing library has a public authority of *EXECUTE, or you need to grant the QSPL user profile *EXECUTE private authority to the library. The format of the CRTDTAQ command is: 
    CRTDTAQ DTAQ (<library name>/<data queue name>) MAXLEN(144) AUT(*USE)

    If you want the data queue information to have dates and time in Coordinated Universal Time (UTC), you can use the same environment variable with a different value. Replace the *DTAQ with *DTA2 in the ADDENVVAR command above. This value causes a type 03 data queue entry to be placed in the data queue instead of a type 02 entry. The command format is as follows:

    ADDENVVAR ENVVAR(QIBM_NOTIFY_CRTSPLF)
          VALUE('*DTA2 <library name>/<data queue name>')
          LEVEL(*JOB | *SYS)

    The length of the type 03 data queue entry is 200 bytes. Use the following command format to create a type 03 data queue:

    CRTDTAQ DTAQ (<library name>/<data queue name>) MAXLEN(200) AUT(*USE)

    Once a data queue is associated with a job or the system, any spooled file created by the job or system will automatically have an entry placed in the data queue. For this action to occur, the user or user profile QSPL must have authorization to the data queue.

    Note: An environment variable that is specified at the job level takes precedence over the same environment variable specified at the system level.

Error conditions

An error occurs if the specified data queue does not exist or if the user creating or changing the output queue does not have use authority to the data queue.

After a data queue is associated with an output queue, any spooled file that is placed on the output queue in ready status causes an entry to be placed on the data queue. The data queue entry is added regardless of the authority the user generating the spooled file has to the data queue.

If the system tries to add entries to a data queue that does not exist or that has an invalid length, the system continues with its processing but sends an informational message to the QSYSOPR message queue. This message indicates that there is a problem with the data queue and specifies the data queue name. This message is sent the first time a specific problem occurs with the data queue of an output queue. The message is sent once every 24 hours.

For example, if message X is received at 10:00 a.m., it is logged in the QSYSOPR message queue. If message X is received again at 10:30 a.m., 11:00 a.m., 1:00 p.m., or 1:30 p.m., it will not be logged. As you can see, the message will not be logged until after 10:00 a.m. the next day, even if it continues to be received all day.

If after message X is logged at 10:00 a.m., message Y is received at 2:00 p.m., message Y is logged. If message X is received again at 2:30 p.m., message X will be logged again even though it was logged earlier in the day.

The intent is not to log the same recurring message all day, but to inform the user of each change of error messages associated with the data queue of a particular output queue.

Additional considerations

Changing the data queue of an output queue is allowed regardless of whether there are spooled files on the output queue. For data queue entries of record type 01, only spooled files that reach RDY status after the change will have entries on the data queue. Spooled files already having a status of ready on the output queue will not have entries on the new data queue.

It is the user's responsibility to manage the data queues. These responsibilities include creating, clearing, and deleting data queues.

When clearing all output queues during IPL, any associated data queues are not cleared. If a damaged system output queue is found, it is re-created without any associated data queue name. Damaged data queues are not re-created.