The Compare Command List command is intended for the case where a
command supports both a 'select' and an 'omit' list of system names
or generic system names. CMPCMDLST ensures that both lists are
unique from each other and generic names do not overlap specific
names (or generic names) in the other list. TAA9896 is sent as an
escape message for non-unique situations. An option exists to allow
generic overlap.
Consider use of the CHKSELOMT tool to determine if a name you want to
process is in the list.
Assume you have a command that allows you to specify both a select
and an omit list such as:
TESTCMD ... SELECT(ABC DEF GHI) OMIT(JKL MNO ABC)
Since ABC is in both lists, the sequence and logic of the command
processing program will determine whether ABC is selected or omitted.
However, the user of the command has probably made an error in
describing the same name in both lists. By using CMPCMDLST in the
command processing program, an escape message will occur.
A similar situation can occur with a generic request such as:
TESTCMD ... SELECT(ABC DEF GHI) OMIT(JKL MNO AB*)
The omit value AB* will cover the selected value ABC. Checking the
lists with CMPCMDLST would cause an escape message.
In some cases you may want to select names such as AB* and yet omit
ABC. An option exists on CMPCMDLST to allow this generic overlap.
CMPCMDLST expects the lists to be passed from command definition
including the leading 2 bytes describing the number of elements. The
number of elements may differ. Only 10 byte system names or generic
names are valid within each list.
A typical CMPCMDLST command for the previous TESTCMD would be:
CMPCMDLST LIST1(&SELECT) LIST2(&OMIT) CMD(TESTCMD) +
PARM1(SELECT) PARM2(OMIT)
The purpose of the CMD, PARM1, and PARM2 parameters is to allow
a specific error message to be produced that would describe
the error such as:
CMPCMDLST found the same name of ABC in parameter
SELECT and parameter list OMIT of the TESTCMD command.
Defaults
--------
The defaults are SELECT(*ALL) and OMIT(*NONE). If both defaults are
used, an escape message is sent.
If only one of the defaults is used, the command completes normally
without checking anything.
See the CHKDUPLST command for checking for duplicates within the same
list.
Values not described
--------------------
Assume you specified:
TESTCMD ... SELECT(ABC DEF) OMIT(JKL MNO)
CMPCMDLST will determine that both lists are unique, but your program
logic must determine what to do with a value such as GHI which does
not appear in either list.
Examples
--------
Assume you have written the CMD1 command which is defined as:
CMD PROMPT('...')
PARM KWD(SELECT) TYPE(*GENERIC) MAX(40) +
PROMPT('Select list')
PARM KWD(OMIT) TYPE(*GENERIC) MAX(40) +
PROMPT('Omit list')
You intend to process a list of all objects in a library, but want to
allow the user to select specific objects by describing them in the
select list and omit those in the omit list.
The command processing program with CMPCMDLST would appear as:
PGM PARM(&SELECT &OMIT)
DCL &SELECT *CHAR LEN(402)
DCL &OMIT *CHAR LEN(402)
CMPCMDLST LIST1(&SELECT) LIST2(&OMIT) CMD(CMD1) +
PARM1(SELECT) PARM2(OMIT)
If the same value appeared in both lists, the TAA9896 escape message
would be issued.
In most cases the user would probably either select or omit specific
names. However, the user may want to select any name beginning with
ABC (specify ABC*) except for ABCD and ABCE. The GENOVERLAP
parameter defaults to *NO to prevent this. By specifying *YES, you
would allow this condition.
The command would appear as:
CMPCMDLST LIST1(&SELECT) LIST2(&OMIT) +
GENOVERLAP(*YES) +
CMD(CMD1) PARM1(SELECT) PARM2(OMIT)
CMPCMDLST escape messages you can monitor for
---------------------------------------------
TAA9894 Both defaults were used
TAA9896 The lists have equal values or generic overlap
Escape messages from based on functions will be re-sent.
CMPCMDLST Command parameters *CMD
----------------------------
LIST1 The first list of names or generic names to be
compared. *ALL is the default. Only system names
(objects, jobs, spooled file names, etc) may be in
the list. Each name (or generic name) must be 10
bytes in a length and may have a maximum of 300
names.
LIST2 The second list of names or generic names to be
compared. *NONE is the default. Only system names
(objects, jobs, spooled file names, etc) may be in
the list. Each name (or generic name) must be 10
bytes in a length and may have a maximum of 300
names.
GENOVERLAP Whether to consider generic overlap or not.
*NO is the default to cause an escape message if the
lists have either equal values or one list has a
value such as AB* and the other list has a value
such as ABC. This prevents an illogical definition.
Specifying *YES allows the situation where you want
to select ABC*, but omit a specific value such as
ABCD. Or you may want to select ABC* and omit the
name ABCD.
CMD The name of your command that has the two lists.
The name is used in the escape message to assist in
identifying the error.
PARM1 The name of your first list parameter. The name is
used in the escape message to assist in identifying
the error.
PARM2 The name of your second list parameter. The name is
used in the escape message to assist in identifying
the error.
Restrictions
------------
The command requires that each list be passed from a command (or
appear as such) with the leading 2 bytes describing the number of
elements in 2 bytes.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKGENERC Check generic
EXTLST Extract list
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CMPCMDLST *CMD TAACLTA QATTCMD
TAACLTAC *PGM CLP TAACLTAC QATTCL
|
