The Command Data Queue tool is designed to allow asynchronous command
requests. The typical use is for users who are capable of using
commands, but the function is general purpose and can be used in any
application including batch jobs.
Assume you are a programmer entering various commands. Most commands
would be done interactively. Some commands would be submitted to
batch such as CRTxxxPGM. However, there is often a middle ground
category where you would like a command performed asynchronously, but
you do not want the overhead of a separate batch job or have your
command be stuck on a batch job queue.
The major advantage of the CMDDTAQ tool is that you can get more work
done because you can cause some commands to be executed
asynchronously.
To use the command data queue for this situation, you would normally
include the following command as part of your initial program:
STRCMDDTAQ
This submits a batch job which waits for an entry on a data queue.
When an entry is received, the entry is processed as a command. To
simplify STRCMDDTAQ, defaults are used. The data queue name is
assumed to be the same as the user profile and is created in QGPL.
Since the job will operate much like an interactive job, the default
is to submit it to the QINTER job queue. By default, the data queue
is created with PUBLIC(*EXCLUDE) so that no other user can run
commands in the job.
Then you just send requests to the data queue. There are two
commands designed for this purpose. The SNDCMDDTAQ command is the
formal command. You would specify:
SNDCMDDTAQ CMD(xxxx)
Like SBMJOB, you can do the following:
- Enter the command named SBMJOB and press F4
- Enter the command you want to run and press F4
- Enter the command prompts and press Enter
The command is then sent to the data queue. The DTAQ parameter on
the command defaults to *USRPRF in QGPL. You can use SNDCMDDTAQ to
send to any command data queue.
The second command SQ is the informal command that is designed for
interactive use where you want a minimum of keystrokes and always
prompt for the command to be executed. You must use a data queue
with the same name as your user profile.
For example, if you wanted to create a data area asynchronously, you
would do the following:
- Enter 'SQ CRTDTAARA' and press Enter.
- Enter the command prompts and press Enter
The command would be sent to the command data queue of the same name
as your user profile in QGPL (there is no parameter for where the
data queue exists). SQ operates as somewhat of a shorthand for
SNDCMDDTAQ.
When SQ completes, it sends the generated SNDCMDDTAQ command as a
Request message and receives it. It then sends a completion message
stating the command was sent to the command data queue.
If you operate from the Command Entry display, you would see:
> SQ CRTDTAARA
> SNDCMDDTAQ CMD(CRTDTAARA DTAARA(xxx) TYPE(xxx) LEN(nn))
Command sent to data queue YYYYY in QGPL.
The purpose of resending the command as a Request message is to allow
you to use the F9 Retrieve function for commands. You would use F9
and then key over the top of the command for minor modifications or
re-prompt.
The intent of SQ is to add a minimum number of key strokes to what
you would need to do if you wanted the same function executed
interactively.
SQ can only be used in an interactive environment. SNDCMDDTAQ can be
used in any environment.
With either SNDCMDDTAQ or SQ, the command is sent to the batch job
submitted by STRCMDDTAQ. The command is executed using QCMDEXC. You
can submit as many commands as are needed. The commands are
processed in FIFO sequence from the data queue.
When you are ready to end the Command Data Queue function, use:
SNDCMDDTAQ CMD(XCMDDTAQ)
It sends a special entry to the data queue which ends the job.
The STRCMDDTAQ command first attempts to allocate the specified data
queue and then deallocates it. The batch job allocates the data
queue to *EXCLRD. This ensures that multiple STRCMDDTAQ commands
cannot be used for the same data queue.
If users forget to end their Command Data Queue batch jobs, a special
command (ENDCMDDTAQ) is available for the system operator. It will
end all jobs that have a function specified as EXCCMDDTAQ.
CMDDTAQ escape messages you can monitor for
-------------------------------------------
Most of the commands do not provide specific escape messages that can
be monitored for. The following does
SNDCMDDTAQ escape messages you can monitor for
----------------------------------------------
TAA9897 Special 'end' message not valid unless
the data queue is active
Valid commands
--------------
STRCMDDTAQ starts a batch job. Any command that is valid in a batch
job may be run This includes commands such as CALL, SBMJOB, DSPxxx.
Because the system considers the job to be a batch job, the default
OUTPUT(*) parameter on many DSP commands will operate correctly.
Commands such as DCL, RTV cannot be used because they are only valid
in CL programs. Commands such as GO cannot be used because they are
restricted to the interactive environment.
The command cannot exceed approximately 512 bytes.
Feedback
--------
When the batch job handles requests, it sends messages back to the
user profile message queue that used SNDCMDDTAQ or SQ. The messages
are designed to be used with the STSMSG TAA Tool which turns the
messages into status messages. The messages still exist in the
message queue, but STSMSG provides a simple solution for receiving
feedback without being interrupted.
To use the STSMSG tool, you would normally name your User Profile
message queue with the command:
CHGMSGQ MSGQ(xxxx) DLVRY(*BREAK) PGM(TAATOOL/TAAMSGDC)
The STSMSG tool has been enhanced so that it handles:
** TAA9851 as a status message.
** TAA9852 as a 'no action' message. The message remains in the
message queue, but no status message is sent nor does DSPMSG
occur. This allows the CMDDTAQ tool to send additional
information to your message queue without causing an
interruption.
The following approach is used for the handling of messages.
** If the command completes normally without a completion
message, a standard message is sent as TAA9851 which states a
normal completion and shows the first 40 bytes of the command
that was executed.
** If the command completes normally with a completion message,
the completion message text is sent as TAA9851.
** If the command fails with an escape message, the previous
diagnostic message text (if any) is sent as a TAA9852 message.
The escape message text is also sent as a TAA9852 message. A
general message stating the failure and the first 40 bytes of
the command is sent as a TAA9851 message.
In most cases, the messages sent will be sufficient to determine the
problem. In some cases, you will need to review the job log of the
batch Command Data Queue job.
Batch job identification
------------------------
If you use WRKSBMJOB or WRKACTJOB you will see the batch job that was
submitted by STRCMDDTAQ. If the defaults are taken, the name of the
batch job will be the same name as the user profile. The function
description will show 'CMD-EXCCMDDTAQ'. The EXCCMDDTAQ command is an
internal command and is only used to provide a better description for
the 'function' column on WRKACTJOB rather than just calling the
processing program.
If you want to end all jobs with EXCCMDDTAQ as the function, use
ENDCMDDTAQ.
If you want to write a program that finds the Command Data Queue
jobs, you could use the TAA Tool CVTWRKACT to create a data base file
and search for the value EXCCMDDTAQ in the AJFNCN field.
When the batch job is submitted, it is specified with
JOBMSGQFL(*WRAP) to avoid abnormally terminating the batch job if the
job log message queue becomes full.
Other uses of the Command Data Queue
------------------------------------
While the default use of the Command Data Queue makes it easy for any
user to have a separate asynchronous job for commands, there are no
restrictions to prevent other use.
For example, you could have:
** A separate Command Data Queue that is used for system wide
functions:
** A unique Data Queue for a specific application.
** A unique Data Queue for a specific batch job.
Each time STRCMDDTAQ is run, a separate job is established on the
system.
Handling of the Data Queue by STRCMDDTAQ
----------------------------------------
Because the data queue object type can be easily damaged and has poor
performance characteristics if a large number of unprocessed entries
ever exist, the STRCMDDTAQ command batch job will attempt to delete
and re-create the data queue when it first begins processing.
If the data queue does not exist, it is created automatically in the
batch job and processing continues normally.
If the data queue exists, the batch job determines if any entries
exist. If not, the data queue is deleted and re-created. The same
library is used where the data queue was found. If the user is not
authorized to delete the data queue, processing continues normally
with a message in the job log.
If entries exist when the batch job starts, they will be processed
normally and the data queue will not be re-created.
Thus if entries exist in the data queue when STRCMDDTAQ is run, they
will be processed. If one of the entries found is from EXCCMDDTAQ,
the batch job will end.
STRCMDDTAQ Command parameters *CMD
-----------------------------
DTAQ The qualified name of the data queue. The default
is to use the same name as the users profile. The
library defaults to QGPL. *LIBL may also be
specified, but only when the data queue already
exists. See the previous discussion on re-creation
of the data queue.
JOBQ The qualified name of the job queue to submit the
batch job to. The default is QINTER as the job
tends to operate as an interactive job. The library
defaults to *LIBL.
JOBD The qualified name of the job description to be used
for the batch job. The default is *USRPRF meaning
the job description found in the user profile. The
library defaults to *LIBL.
JOB The job name to be used for the batch job. The
default is *DTAQ which means the same name as the
DTAQ parameter value.
AUT The authority for the created data queue. The
default is *EXCLUDE meaning the *PUBLIC is excluded
from using the data queue. The other entries are
the standard values of *LIBCRTAUT, *CHANGE, *ALL, or
*USE.
SNDCMDDTAQ Command parameters *CMD
-----------------------------
CMD The command to be executed by the Command Data Queue
function. The CMD parameter can be prompted for in
the same manner as you prompt for a command on
SBMJOB.
Any command that can be successfully executed by
QCMDEXC in batch may be used. This includes
commands such as CALL, SBMJOB, DSPxxx. Because the
system considers the job to be a batch job, the
default OUTPUT(*) parameter on many DSP commands
will operate correctly.
The command cannot exceed approximately 512 bytes.
Commands such as DCL, RTV cannot be used because
they are only valid in CL programs. Commands such
as GO cannot be used because they are restricted to
the interactive environment.
A special value exists to allow a user to end the
batch job. The command XCMDDTAQ sends a special
request that ends the batch job. The default for
listing the job log is accessed from the JOBD that
the job started with.
The XCMDDTAQ entry is not valid unless the data
queue is active meaning that it is in use by another
job. If not active, TAA9897 will be sent as an
escape message.
For example, if you have not done a STRCMDDTAQ, it
is invalid to send the special message as this would
result in immediately ending the job the next time
STRCMDDTAQ was used.
DTAQ The qualified name of the data queue to send the
command to. The default is to use the same name as
the users profile. The library defaults to *LIBL.
*CURLIB may also be specified.
SQ Command parameters *CMD
---------------------
CMDNAM The command name to be prompted for. When Enter is
pressed, the prompt for the desired command would
appear. When Enter is pressed, the command is sent
to the data queue.
The data queue is searched for using a default of
the user profile name and the library list.
The command XCMDDTAQ may be entered to send a
special message to end the batch job. The XCMDDTAQ
entry is not valid unless the data queue is active
meaning that it is in use by another job. If not
active, TAA9897 will be sent as an escape message.
For example, if you have not done a STRCMDDTAQ, it
is invalid to send the special message as this would
result in immediately ending the job the next time
STRCMDDTAQ was used.
ENDCMDDTAQ Command parameters *CMD
-----------------------------
There are no parameters. You must have the special authority *JOBCTL
to use the command.
EXCCMDDTAQ Command *CMD
------------------
This is an internal command which is not intended to be used
externally. The function of EXCCMDDTAQ is to provide a meaningful
name for the function field displayed by WRKSBMJOB and WRKACTJOB when
the batch job that is submitted by STRCMDDTAQ is displayed.
XCMDDTAQ Command parameters *CMD
---------------------------
XCMDDTAQ is a special command that can only be entered on SNDCMDDTAQ
or SQ to end the batch job.
Restrictions
------------
A few minor restrictions exist throughout the documentation.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKACTOBJ Check active object
CHKJOBCTL Check job control
RTVJOBSTS Retrieve job status
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
While not required, the Command Data Queue is intended to work with
the tool:
STSMSG Sending received messages as status messages
Implementation
--------------
None, the tool is ready to use. To use the STSMSG tool, you must set
your user profile message queue to the break handling program as
described previously.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
STRCMDDTAQ *CMD TAADTQF QATTCMD
SNDCMDDTAQ *CMD TAADTQF2 QATTCMD
ENDCMDDTAQ *CMD TAADTQF3 QATTCMD
SQ *CMD TAADTQF4 QATTCMD
EXCCMDDTAQ *CMD TAADTQF5 QATTCMD
TAADTQFC *PGM CLP TAADTQFC QATTCL
TAADTQFC2 *PGM CLP TAADTQFC2 QATTCL
TAADTQFC3 *PGM CLP TAADTQFC3 QATTCL
TAADTQFC4 *PGM CLP TAADTQFC4 QATTCL
TAADTQFC5 *PGM CLP TAADTQFC5 QATTCL
Structure
---------
STRCMDDTAQ Cmd
TAADTQFC CL pgm
Submits the EXCCMDDTAQ command as a batch job
SNDCMDDTAQ Cmd
TAADTQFC2 CL pgm
SQ Cmd
TAADTQFC4 CL pgm
TAADTQFC2 CL pgm
ENDCMDDTAQ Cmd
TAADTQFC3 CL pgm
EXCCMDDTAQ
TAADTQFC5 CL pgm
|
