The TAAEXC program is intended to be used instead of QCMDEXC from a
HLL program to allow for better handling of messages. An externally
described data structure is supplied which must be defined in the HLL
program. Fields within the data structure allow a command to be
passed, options to be set, and information to be returned.
The advantage of TAAEXC is that it provides a simpler interface for:
** 'Remove message' function. The default is *NO to retain any
messages. *YES may be specified to clear any messages caused
by the command that was executed.
** MONMSG function. The default is to have TAAEXC resend any
escape message (caused by the command to be executed) to the
HLL program. You may easily check for a single error
condition by specifying the exception ID in a field in the
data structure. Multiple messages may be checked for in your
program. See the sample code provided.
** Easy access to the completion or escape message sent by the
command that was executed. The data is returned in fields
within the data structure for Message ID, message text,
message data, etc. The information may be used in the program
or with the TAA Tool SNDESC to resend the message as an escape
message.
** Easy access to the diagnostic message preceding the escape.
This provides for more specific error handling when a command
such as CPYF is used which sends a generalized escape message
and specific diagnostic messages. The data is returned in
fields within the data structure for Message ID, message text,
message data, etc.
** Simple building of the command to be executed. Parameters of
the command are automatically concatenated together with
spaces rather than having the user program perform the
concatenation.
A typical set of RPG statements would be:
I* TAAEDS is the data structure used by the TAA Tool TAAEXC
ITAAEDS E DSTAACMECP
.
C* Your statements to build the command such as CHKOBJ
C MOVEL'CHKOBJ' TAACM1 P CHKOBJ
C MOVEL'xxx' TAACM2 P CHKOBJ
C MOVEL'*PGM' TAACM3 P CHKOBJ
C* Call TAAEXC to execute
C CALL 'TAAEXC' TAAEXC
C PARM TAAEDS Cmd DS
A typical set of RPG IV statements would be:
D* TAAEDS is the data structure used by the TAA Tool TAAEXC
D TAAEDS E DS EXTNAME(TAACMECP)
.
C* Your statements to build the command such as CHKOBJ
C MOVEL(P) 'CHKOBJ' TAACM1
C MOVEL(P) 'xxx' TAACM2
C MOVEL(P) '*PGM' TAACM3
C* Call TAAEXC to execute
C CALL 'TAAEXC'
C PARM TAAEDS
If an error occurred, the TAAEXC program would resend any escape
message to the RPG program. See the later discussion on monitoring
for messages.
What commands may be executed
-----------------------------
TAAEXC uses the QCMDEXC function internally and therefore has the
same restrictions as QCMDEXC. Most commands are valid except those
that are limited for use within CL programs (such as RTV commands).
The command definition object must be specified as ALLOW(*ALL) or
ALLOW(*EXEC).
An exception is OVR commands. Because TAAEXC is a program, any
normal OVR commands issued are lost when the program goes out of the
stack. The OVR commands support the OVRSCOPE parameter which will
allow you to retain the override.
Field names in the TAACMECP data structure
------------------------------------------
All the fields used are named TAAxxx. You may review the names with
the DSPFMT TAA Tool.
DSPFMT FILE(TAACMECP)
There are 5 command fields. TAACM1 has a length of 256 bytes. The
TAACM2 - TAACM5 fields each has a length of 50 bytes.
The TAACMx fields are concatenated in sequence to build the command
with spaces in between. For a very simple command such as the CHKOBJ
command shown in the previous example, you just fill the fields and
let TAAEXC concatenate the values together before execution.
The TAAMON field (described later) determines what will be monitored
for. If TAAMON is blank or *NONE, any escape messages received will
be resent to the HLL program.
The TAARMV field (described later) controls whether messages received
by TAAEXC will be removed.
All the other fields in the TAAEDS data structure are return values.
The TAARES field will contain '0' if the command completed
successfully. If you are monitoring for messages, a '1' will be
returned if the command failed.
The remaining fields such as the TAAMID (message ID) will contain
information from messages sent by the command that was executed. The
fields are similar to the return variables provided by the RCVMSG
command. If no information is available, the fields will be blank.
Monitoring for messages
-----------------------
The TAAMON field allows you to monitor for messages.
** The default (blanks) causes any escape message received by
TAAEXC to be resent to the HLL program. *NONE may also be
specified to cause this function.
Prior to sending the escape, any previously received
diagnostic message will be resent as a diagnostic message.
For example, CPYF will send a generalized escape message
CPF2817 preceded by a specific diagnostic message.
To use the default technique, just copy the code shown at the
beginning of the documentation.
** You may monitor for a single error condition by entering the
escape message ID in the TAAMON field in the same manner you
would describe on a CL MONMSG command.
If the specified escape message occurs, TAAEXC completes
normally, but posts a '1' in the TAARES field for 'failure'
instead of '0' for a 'normal completion'. If a message had
been sent prior to the escape message, it will appear in the
TAADxx fields (such as the message ID will be in the TAADID
field). Your program should check the TAARES value if you
have specified a message to monitor for.
If an escape message occurs that you have not specified, the
escape message would be resent to your HLL program. Any
previously received diagnostic message will be sent as a
diagnostic message.
See the later sample for how to code this technique.
** You may specify *ALL to mean that all message IDs should be
monitored for. If an error occurs, TAAEXC will complete
normally with a '1' in the TAARES field. The TAAMxx fields
will contain the message information (such as the message ID
in TAAMID) and any previous diagnostic message information
would be placed in the TAADxx fields.
Your program needs to check the TAARES field for '1' and then
check the TAAMID field. Sample code is shown later.
Note that unlike the CL MONMSG command, you cannot specify a generic
message ID such as CPF9800 nor can you specify the 'any error'
condition of CPF0000. To achieve the 'any error' function, specify
TAAMON = *ALL and code your program to test for the message IDs.
You cannot specify a list of message IDs to monitor for in the TAAMON
field. You can code for a list of messages in your program as
described in later sample code.
Note that any value other than blanks, *NONE, or *ALL is treated as a
message ID that you want to monitor for.
Previous Diagnostic message
---------------------------
The TAADxx fields are for a previous diagnostic message such as when
CPYF fails with the CPF2817 generalized escape which is preceded by a
specific diagnostic message ID that describes the error. The TAADxx
fields would contain the information from the diagnostic message.
If the previous message is other than a diagnostic type, the TAADxx
fields are not filled.
The technique used to retrieve the diagnostic message may not be
accurate in all cases. Since messages in the program message queue
are not associated with a command, the technique used retrieves the
previous message that occurred before an escape message. If it is a
diagnostic type, the technique assumes that it belongs to the escape
message. It is possible that a diagnostic message could have been
issued earlier from a previous function and then a later function
caused an escape message in which case the diagnostic message would
be incorrectly associated with the escape message.
The Call command is treated separately from other commands by the
system so that monitoring for Call exceptions requires some unique
handling.
If you use a command entry display and enter a Call to a non-existent
program, the system sends the CPD0170 diagnostic message followed by
the CPF0001 generalized escape message.
If you execute the invalid Call using QCMDEXC, the system resends the
CPD0170 as a diagnostic, but changes the CPF0001 message into the
generalized escape message CPF0006. Consequently, you must monitor
for CPF0006 and not CPF0001.
Removing messages caused by your command
----------------------------------------
The command you execute may cause messages to be sent to the TAAEXC
program message queue. The default (TAARMV = blanks) retains these
messages so they will exist in the job log. To remove any messages
sent to TAAEXC, set TAARMV to *YES such as:
C MOVE '*YES' TAARMV Remove msgs
Any value other than *YES will retain the messages.
Checking for a single error condition
-------------------------------------
The following error handling code checks for the CPF9801 error
message. Note that the RPG program will fail if a message other than
CPF9801 occurs.
The following is RPG III code:
I* TAAEDS is the data structure used by the TAA Tool TAAEXC
ITAAEDS E DSTAACMECP
.
C* Your statements to build the command such as CHKOBJ
C MOVEL'CHKOBJ' TAACM1 P CHKOBJ
C MOVEL'xxx' TAACM2 P CHKOBJ
C MOVEL'*PGM' TAACM3 P CHKOBJ
C* Set TAAMON to the message ID to be monitored for
C MOVEL'CPF9801' TAAMON P Monitor msg
C* Call TAAEXC to execute
C CALL 'TAAEXC' TAAEXC
C PARM TAAEDS Cmd DS
C* Check result (TAARES is '0' = Successful and '1' = Failure)
C TAARES IFEQ '1' Cmd failed
C* Your code to process the CPF9801 error
C* Any other errors such as CPF9802, will cause an escape
C* message to be sent to the RPG program
C ENDIF Cmd failed
The following is RPG IV code:
D TAAEDS E DS EXTNAME(TAACMECP)
.
C* Your statements to build the command such as CHKOBJ
C MOVEL(P) 'CHKOBJ' TAACM1
C MOVEL(P) 'xxx' TAACM2
C MOVEL(P) '*PGM' TAACM3
C* Set TAAMON to the message ID to be monitored for
C MOVEL(P) 'CPF9801' TAAMON
C* Call TAAEXC to execute
C CALL 'TAAEXC'
C PARM TAAEDS
C* Check result (TAARES is '0' = Successful and '1' = Failure)
C TAARES IFEQ '1'
C* Your code to process the CPF9801 error
C* Any other errors such as CPF9802, will cause an escape
C* message to be sent to the RPG program
C ENDIF
Handling multiple error conditions
----------------------------------
In the following code, the CPF9801 and CPF9802 error conditions are
specifically handled within the program. Any other error from CHKOBJ
would cause the RPG program to resend the error condition to the
calling program. This occurs by use of the TAA SNDESCMSG Tool.
The following is RPG III code:
I* TAAEDS is the data structure used by the TAA Tool TAAEXC
ITAAEDS E DSTAACMECP
I* MSG area used by SNDESCMSG TAA Tool
IMSGDS DS 512
.
C* Your statements to build the command such as CHKOBJ
C MOVEL'CHKOBJ' TAACM1 P CHKOBJ
C MOVEL'xxx' TAACM2 P CHKOBJ
C MOVEL'*PGM' TAACM3 P CHKOBJ
C* Set TAAMON to *ALL
C MOVEL'*ALL ' TAAMON P Monitor msg
C* Call TAAEXC to execute
C CALL 'TAAEXC'
C PARM TAAEDS
C* Check result (TAARES is '0' = Successful and '1' = Failure)
C TAARES IFEQ '1' Cmd failed
C SELEC Select MsgID
C* Select on error ID
C TAAMID WHEQ 'CPF9801' If CPF9801
C* Your handling of CPF9801 Print
C TAAMID WHEQ 'CPF9802' If CPF9802
C* Your handling of CPF9802 Print
C OTHER Any other
C* Any other escape message causes a resend of the escape message
C CALL 'SNDESC2' TAA Tool
C PARM TAAMID Msg ID
C PARM TAAMFL Msg file
C PARM TAAMLB Msg lib
C PARM TAAMSD MSGDS Msg data
C ENDSL Select MsgID
C ENDIF Cmd failed
An alternative would be to just display whatever message received
whether it is an escape or completion. In the following code, MSG80
would be a display field.
.
C MOVEL'*ALL ' TAAMON P Monitor msg
C* Call TAAEXC to execute
C CALL 'TAAEXC'
C PARM TAAEDS
C MOVELTAAMSGMSG80 MSG80
The following is RPG IV code:
D* TAAEDS is the data structure used by the TAA Tool TAAEXC
D TAAEDS E DS EXTNAME(TAACMECP)
D* MSG area used by SNDESCMSG TAA Tool
D MSGDS DS 512
.
C* Your statements to build the command such as CHKOBJ
C MOVEL(P) 'CHKOBJ' TAACM1
C MOVEL(P) 'xxx' TAACM2
C MOVEL(P) '*PGM' TAACM3
C* Set TAAMON to *ALL
C MOVEL(P) '*ALL ' TAAMON
C* Check result (TAARES is '0' = Successful and '1' = Failure)
C TAARES IFEQ '1'
C SELECT
C* Select on error ID
C TAAMID WHENEQ 'CPF9801'
C* Your handling of CPF9801 Print
C TAAMID WHENEQ 'CPF9802'
C* Your handling of CPF9802 Print
C OTHER
C* Any other escape message causes a resend of the escape message
C CALL 'SNDESC2'
C PARM TAAMID
C PARM TAAMFL
C PARM TAAMLB
C PARM TAAMSD MSGDS
C ENDSL
C ENDIF
Other message handling
----------------------
The most typical message handling function would be to handle escape
messages as described previously.
You may also handle completion messages. For example, CRTDTAARA will
send a completion message. The same field names (TAAMID, TAAMSG,
etc) are used to contain the last message sent to the TAAEXC program
(the field data will exist for the last message received). You can
determine the type of message by using the contents of the TAAMTP
field. It will contain the same values as described for the RCVMSG
RTNTYPE parameter. For example, 01 = Completion and 02 = Diagnostic.
You may choose to resend the message using the QMHSNDPM API or a TAA
Tool such as SNDESCMSG or SNDDIAGMSG.
Command parameters *CMD
------------------
No command exists. TAAEXC is just a program.
Restrictions
------------
** Normal override commands will be lost when the TAAEXC program
ends. The OVRSCOPE parameter allows you to control the
duration of the override.
** CL program commands may not be executed.
Prerequisites
-------------
None.
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
TAAEXC *PGM CLP TAACMECC QATTCL
TAACMECP *FILE PF TAACMECP QATTDDS
|
