.*T: Process Data Queue
.*O: CRTPNLGRP CHRID(*CHRIDCTL)
.*                                                                    +
.* Copyright (c) 2009 Rory Hewitt                                     +
.* All rights reserved.                                               +
.*                                                                    +
.* Redistribution and use in source and binary forms, with or without +
.* modification, are permitted provided that the following conditions +
.* are met:                                                           +
.* 1. Redistributions of source code must retain the above copyright  +
.*    notice, this list of conditions and the following disclaimer.   +
.* 2. Redistributions in binary form must reproduce the above         +
.*    copyright notice, this list of conditions and the following     +
.*    disclaimer in the documentation and/or other materials provided +
.*    with the distribution.                                          +
.*                                                                    +
.* THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ''AS IS'' +
.* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED  +
.* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A    +
.* PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR   +
.* OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,    +
.* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT   +
.* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF   +
.* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED    +
.* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT        +
.* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN  +
.* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE    +
.* POSSIBILITY OF SUCH DAMAGE.                                        +
.*                                                                    +
.* This panel group source member contains help text for the
.* DQ command.
.*H:-------------------------------------------------------------------

:PNLGRP.

.*---------------------------------------------------------------------
.* Text for DQ command (Process Data Queue)
.*---------------------------------------------------------------------

:HELP NAME='DQ'.Process Data Queue
:P.
The Process Data Queue (DQ) command allows you to start a data queue
server, end a data queue server or send data to a data queue server.
:P.
A data queue server is a batch job which monitors a specified data
queue. When an entry appears on the data queue, the data queue
server calls a 'handler' program to process the entry.
:P.
:IMHELP NAME='DQ/ERROR/MESSAGES'.

:EHELP.

.*---------------------------------------------------------------------
.* Action (ACTION)
.*---------------------------------------------------------------------

:HELP NAME='DQ/ACTION'.
Action (ACTION) - &msg(CPX6AB4,QCPFMSG).
:XH3.
Action (ACTION)
:P.
Specifies the action to take regarding the data queue server
:P.
This is a required parameter.
:P.
:PARML.
:PT.:PK.*START:EPK.
:PD.Start a data queue server to process the data queue
specified in the :HP2.Data queue:EHP2. prompt (DTAQ parameter).
:PT.:PK.*END:EPK.
:PD.End a data queue server which is processing the data queue
specified in the :HP2.Data queue:EHP2. prompt (DTAQ parameter).
:PT.:PK.*SEND:EPK.
:PD.Send data to the data queue server which is processing the data
queue specified in the :HP2.Data queue:EHP2. prompt (DTAQ parameter).
:EPARML.

:EHELP.

.*---------------------------------------------------------------------
.* Data queue (DTAQ)
.*---------------------------------------------------------------------

:HELP NAME='DQ/DTAQ'.
Data queue (DTAQ) - &msg(CPX6AB4,QCPFMSG).
:XH3.
Data queue (DTAQ)
:P.
Specifies the qualified name of the data queue being processed. The
data queue must already exist.
:P.
This is a required parameter.
:P.
:HP2.Qualifier 1: Data queue:EHP2.
:PARML.
:PT.:PK.name:EPK.
:PD.Specify the name of the data queue.
:EPARML.
:P.
:HP2.Qualifier 2: Library:EHP2.
:PARML.
:PT.:PK def.*LIBL:EPK.
:PD.All libraries in the library list for the current thread are
searched until the first match is found.
:PT.:PK.*CURLIB:EPK.
:PD.The current library for the thread is searched.  If no library is
specified as the current library for the thread, the QGPL library is
searched.
:PT.:PK.name:EPK.
:PD.Specify the name of the library to be searched.
:EPARML.

:EHELP.

.*---------------------------------------------------------------------
.* Key (KEY)
.*---------------------------------------------------------------------

:HELP NAME='DQ/KEY'.
Key (KEY) - &msg(CPX6AB4,QCPFMSG).
:XH3.
Key (KEY)
:P.
Specifies the key to use for the data queue. The length of this key
must be the same as the key specified when the data queue was created.
:P.
If a value other than KEY(*NONE) is specified, the data queue server
will only process data queue entries with a matching key value.
:P.
This is a required parameter.
:P.
:PARML.
:PT.:PK.*NONE:EPK.
:PD.The data queue is unkeyed.
:PT.:PK.*JOBNBR:EPK.
:PD.The data queue will use a 6-byte key which is the same as the
job number of the data queue server job.
:PT.:PK.*JOBNAME:EPK.
:PD.The data queue will use a 10-byte key which is the same as the
job name of the data queue server job. This name is always 'DQ'.
:PT.:PK.*JOBUSER:EPK.
:PD.The data queue will use a 10-byte key which is the same as the
job user of the data queue server job. This will be the same as the
user who executes the DQ command.
:PT.:PK.user-defined-key:EPK.
:PD.The data queue will use a user-specified key value, which can be
up to 16 bytes in length.
:EPARML.

:EHELP.

.*---------------------------------------------------------------------
.* Handler (HANDLER)
.*---------------------------------------------------------------------

:HELP NAME='DQ/HANDLER'.
Handler (HANDLER) - &msg(CPX6AB4,QCPFMSG).
:XH3.
Handler (HANDLER)
:P.
Specifies the program which will be called by the data queue server to
handle entries which it receives.
:P.
The program must already exist and must have the following parameters:
:OL.
:LI.Data (Character, 5000 bytes). This is the data string which is
placed on the data queue by this command when ACTION(*SEND) is
specified.
:LI.Qualified job (Character, 26 bytes). This is the qualified name of
the job which placed the data string on the data queue. It is made up
of the job name (10 bytes), job user (10 bytes) and job number (6
bytes).
:LI.Return code (Character, 7 bytes). This is the return code that will
be returned to the data queue server from the handler. It will be
returned with one of the following 3 values:
:UL.
:LI.blank - The handler successfully processed the data string.
:LI.*WARN - The handler encountered errors processing the data string.
The data queue server will place a diagnostic message in the job log
(which may be in addition to any messages placed there by the handler).
:LI.*ERROR - The handler encountered unrecoverable errors. The data
queue server will end abnormally and no more data queue entries will
be processed.
:EUL.
:EOL.
:P.
This parameter is ignored unless ACTION(*START) is specified.
:P.
:HP2.Single values:EHP2.
:PARML.
:PT.:PK.*DFTHDLR:EPK.
:PD.Use the default handler program DQHDLR
:EPARML.
:P.
:HP2.Qualifier 1: Program:EHP2.
:PARML.
:PT.:PK.name:EPK.
:PD.Specify the name of the program.
:EPARML.
:P.
:HP2.Qualifier 2: Library:EHP2.
:PARML.
:PT.:PK def.*LIBL:EPK.
:PD.All libraries in the library list for the current thread are
searched until the first match is found.
:PT.:PK.*CURLIB:EPK.
:PD.The current library for the thread is searched.  If no library is
specified as the current library for the thread, the QGPL library is
searched.
:PT.:PK.name:EPK.
:PD.Specify the name of the library to be searched.
:EPARML.

:EHELP.

.*---------------------------------------------------------------------
.* Data (DATA)
.*---------------------------------------------------------------------

:HELP NAME='DQ/DATA'.
Data (DATA) - &msg(CPX6AB4,QCPFMSG).
:XH3.
Data (DATA)
:P.
Specifies the data that will be sent to the data queue server. The data
can be a CL command to be run or a string of characters.
:P.
The data will be passed to the handler program exactly as specified in
this parameter, including any leading or embedded blanks, quotes and
special characters.
:P.
This parameter is ignored unless ACTION(*SEND) is specified.

:EHELP.

.*---------------------------------------------------------------------
.* Examples for DQ
.*---------------------------------------------------------------------

:HELP NAME='DQ/COMMAND/EXAMPLES'.Examples for DQ
:XH3.Examples for DQ
:P.
:HP1.Example 1::EHP1.
:XMP.
DQ ACTION(*START)
   DTAQ(*LIBL/DQ)
   KEY(*NONE)
   HANDLER(*LIBL/DQHDLR)
:EXMP.
:P.
This example will start a data queue server which will process the
unkeyed data queue DQ. Any subsequent uses of the DQ command which
specifiy ACTION(*SEND) will cause the string specified in the DATA
parameter to be passed by the data queue server to the DQHDLR handler
program.
:P.
:HP1.Example 2::EHP1.
:XMP.
DQ ACTION(*SEND)
   DTAQ(*LIBL/DQ)
   KEY(*NONE)
   DATA('A string to send to the data queue handler')
:EXMP.
:P.
This example will put an entry onto the unkeyed data queue DQ with a
value of 'A string to send to the data queue handler'. The data queue
server will receive this entry and pass the value to the data queue
handler program specified when the data queue server was started.

:EHELP.

.*---------------------------------------------------------------------
.* Error messages for DQ
.*---------------------------------------------------------------------

:HELP NAME='DQ/ERROR/MESSAGES'.&msg(CPX0005,QCPFMSG). DQ
:XH3.&msg(CPX0005,QCPFMSG). DQ
:P.
:HP3.*ESCAPE &msg(CPX0006,QCPFMSG).:EHP3.
:DL COMPACT.
:DT.CPF9898:DD.General escape message.
:DT.CPF*   :DD.Other CPF* messages.
:EDL.

:EHELP.

:EPNLGRP.

