The Compare Wild Card command provides a comparison of a system name
against a compare value that contains fixed and/or floating wild
cards. The companion command is CHKWLDCRD which is intended to be
used before performing a function such as a DSPxxx OUTFILE or when
using a list type API. Additional commands CMPWLDCRD2 and CHKWLDCRD2
may be used on any string (up to 500 bytes) such as customer names or
addresses.
CMPWLDCRD allows a comparison value of 'A%C*' where '%' is a fixed
wild card (the comparison character is ignored) and '*' is the
floating wild card (in this case a generic type of request). This
would compare correctly to the names 'ABC', and 'ABCD'
A fixed wild card means a single character is ignored. The default
is %. Multiple fixed wild cards may exist such as a value of
'AB%%D%F'.
A floating wild card means that one or more characters are ignored.
The default is *. If the floating wild card appears at the end of
the value such as A%B*, it is treated as a generic request meaning
any characters after the B will be considered a match. The floating
wild card may appear in the middle of the comparison value to mean
any characters are ignored until the next comparison character is
found. For example 'A*D' would compare to 'AD', 'ABD', or 'ABCD'.
Both fixed and floating wildcards may be specified such as 'A%*D*' or
'AB%%*D%*'
A value of Y or N will be returned to describe the result.
Because the wildcard characters may cause an error in a command
string or prompter, you need to quote the value and enter in upper
case.
Typical CMPWLDCRD code would be:
DCL &RESULT *CHAR LEN(1)
.
CMPWLDCRD NAME(xxxx) CMPVAL('A%C*') RESULT(&RESULT)
IF (&RESULT *EQ 'Y') DO /* Good comparison */
.
ENDDO /* Good comparison */
Examples
--------
Compare
Value Good comparisons Failed comparisons
------- --------------- ------------------
A%C ABC, AXC AC, ABCD, ACD
A%C* ABC, AXC, ABCD AC, ACD
A%%D ABBD AD, ABD, ABCDE
A%%D* ABBD, ABBDE AD, ABD, ABCF
AB% ABC AB, ABCD
AB%* ABC, ABCD AB
A*D AD, ABD, ABCD AC, ABDE, ABE
A*D* AD, ABD, ABCD, ABCDE AC, ABE
A%*D% AXDF, AXBDF, AXBBDF AXE, AXEE
*A* A, ABC, BA, BAC BBB
% A, B AB, ABC
* Any value None
ABC Message TAA9891
A** Message TAA9892
A*% Message TAA9892
CHKWLDCRD Command
-----------------
The CHKWLDCRD command is intended to be used before creating a list
to assist in determining whether the CMPVAL contains wildcard
characters and returns a value that is ready to be used in the scan
(such as in the object name of DSPOBJD).
A typical set of commands would be:
DCL &CMPVAL *CHAR LEN(10)
DCL &WLDCRD *CHAR LEN(1)
DCL &RTNNAM *CHAR LEN(10)
DCL &RESULT *CHAR LEN(1)
.
CHKWLDCRD CMPVAL(&CMPVAL) WLDCRD(&WLDCRD) +
RTNNAM(&RTNNAM)
.
DSPOBJD OBJ(xxx/&RTNNAM) OUTFILE(yyy)
READ: RCVF
MONMSG MSGID(CPF0864) EXEC(GOTO EOF)
CMPWLDCRD NAME(xxxx) CMPVAL(&CMPVAL) RESULT(&RESULT)
IF (&RESULT *EQ 'N') DO /* Failed comparison */
GOTO READ
ENDDO /* Failed comparison */
/* Process */
If &CMPVAL contains a simple name (eg ABC), a generic name (eg ABC*),
or *ALL, &RTNNAM would contain the same value and WLDCRD would
contain 'N'.
The WLDCRD return value is Y if CMPVAL contains wildcard characters
of either a fixed or an embedded floating type.
If wildcard characters exist, the RTNNAM return value will contain a
generic value to be used for the object name of the scan function
ending with the first wildcard character. For example, if AB*D or
AB%D is entered, the RTNNAM value will be AB*. This allows the scan
function to perform a generic search which will minimize the number
of entries that must be considered by CMPWLDCRD.
Whether wildcards exist or not, the the RTNNAM value is ready to be
used as the the scan name such as the object name for DSPOBJD (or a
list API).
The CMPWLDCRD command should only be used if the CMPVAL contains a
wildcard character.
If the first character is a wildcard (eg *A* or %A*), the RTNNAM will
be *ALL.
CHKWLDCRD rules
---------------
The following rules apply to the CMPVAL value:
** The first character must be A-Z, $, #, @ or a wildcard
character. If the first character is a wild card character,
the return name will be '*ALL'.
** The remaining characters must be a wildcard character or A-Z,
0-9, $, #, @, _, or '.'.
** Embedded blanks are invalid.
Example of CHKWLDCRD and CMPWLDCRD being used together
------------------------------------------------------
The supplied program TAACLRWC11 is a sample of how to use CHKWLDCRD
and CMPWLDCRD. The functions work together to provide a list of
commands from QSYS.
The sample code may be displayed with:
DSPTAA TAACLRWC11
In the sample, commands from the QSYS library are listed as messages
if they match a passed in CMPVAL such as:
** *ALL
** A simple name such as 'STRDBG'
** A generic name such as 'STRC*'
** A name containing wild card characters such as 'ST%O*' or
'S%*RJ*'
Note that you must pass the compare value in quotes and in upper
case.
The program would be called with a passed in parameter.
CALL PGM(xxx) PARM('TAAS*RC*')
CMPWLDCRD2/CHKWLDCRD2
---------------------
These commands are intended to be used when the field to be scanned
is not a system name. Any string may be scanned for a compare value
that contains wildcards. A typical use would be for name or address
fields.
The commands are identical to CMPWLDCRD and CHKWLDCRD with the
following exceptions:
** Some parameter names on CMPWLDCRD2 and CHKWLDCRD2 are changed
to reflect that a string is being scanned and not a name.
** The STRING to be scanned on on CMPWLDCRD2 may be up to 500
bytes.
** The CMPVAL value may be up to 20 bytes on both CMPWLDCRD2 and
CHKWLDCRD2.
** The RTNVAL parameter on CHKWLDCRD2 may be up to 20 bytes in
length. This may be used as a SETLL value or as a value to
compare to against individual records. It will not contain a
trailing * as with CHKWLDCRD. This can be used to improve
performance by minimizing the number of times the CMPWLDCRD2
function must be used.
** CMPWLDCRD2 supports an additional parameter of STRINGLEN to
allow you to describe the maximum length of the STRING value
to be scanned.
** CHKWLDCRD2 allows any values to exist in the CMPVAL including
wildcards. Characters can include digits, special characters,
and blanks.
When comparing for names and addresses, you probably need to consider
the case of the data. A simple solution is to translate all field
data to be compared to upper case using a translate table or the RPG
XLATE function and then ensure that the compare value is also in
upper case.
The CMPWLDCRD2 CPP (TAACLRWC3) may be called directly from a HLL
program. See the later discussion.
CMPWLDCRD escape messages you can monitor for
---------------------------------------------
TAA9891 A wildcard character must exist
TAA9892 A wildcard may not follow a floating wildcard
Escape messages from based on functions will be re-sent.
CMPWLDCRD2 escape messages you can monitor for
----------------------------------------------
TAA9891 A wildcard character must exist
TAA9892 A wildcard may not follow a floating wildcard
Escape messages from based on functions will be re-sent.
CHKWLDCRD escape messages you can monitor for
---------------------------------------------
TAA9893 An invalid CMPVAL exists
Escape messages from based on functions will be re-sent.
CHKWLDCRD2 escape messages you can monitor for
----------------------------------------------
TAA9893 An invalid CMPVAL exists
Escape messages from based on functions will be re-sent.
CMPWLDCRD command parameters *CMD
----------------------------
NAME The name to be scanned. Up to 10 bytes may be
specified. In a typical example, the name would be
an object, member, job, or spooled file name.
CMPVAL The comparison value to check against NAME. CMPVAL
must contain at least one fixed or floating wildcard
such as 'A%B', 'A%B*', or 'A%*B*'. A wildcard may
not follow a floating wildcard character. Up to 10
bytes may be specified.
RESULT The returned result after the comparison is made.
This must be specified as *CHAR LEN(1) and will
contain either Y or N.
FIXWLDCRD The character that is the fixed wildcard. The
default is '%'.
FLTWLDCRD The character that is the floating wildcard. The
default is '*'.
CHKWLDCRD parameters *CMD
--------------------
CMPVAL The comparison value to checked. It may contain
*ALL, a simple name ('ABC'), a generic name
('ABC*'), or a name with wildcard characters
('A%C*', r 'A%*C', 'A%*C*', or *A*'). Up to 10
bytes may be specified.
The non-wildcard characters must follow the rules of
a valid system name. A wildcard may not follow a
floating wildcard character.
WLDCRD A Y/N return value for whether the CMPVAL contains
wildcard characters. A 'Y' will be returned if
wildcard characters exist. A generic value such as
ABC* considered to be a generic value and does not
contain wildcard characters. A CMPVAL such as
'A%B', 'A%B*', 'A*B', or 'A*B*' would cause a 'Y' to
be returned.
This is an optional return variable that if used
must be specified as *CHAR LEN(1).
RTNNAM The returned value that is intended to be used as
the object name on a function such as DSPOBJD.
If *ALL, a simple name ('ABC'), or a generic name
('ABC*') exist for the CMPVAL, the same value will
be returned.
If the CMPVAL contains a wildcard character, the
value returned will be a generic name ending with
the first wildcard found. For example, if 'AB%C*'
is the CMPVAL, 'AB*' will be returned. This allows
the system function to perform a generic search
which will minimize the number of times that
CMPWLDCRD must be used. For each entry processed,
the CMPWLDCRD command would be used to determine if
a match exists.
The DSPOBJD command and corresponding API also
support an 'object type' for selection criteria
which can be used to further reduce the number of
entries that must be checked with CMPWLDCRD.
See the sample program on how CHKWLDCRD and
CMPWLDCRD can be used together.
This is an optional return variable that if used
must be specified as *CHAR LEN(10).
FIXWLDCRD The character that is the fixed wildcard. The
default is '%'.
FLTWLDCRD The character that is the floating wildcard. The
default is '*'.
CMPWLDCRD2 command parameters *CMD
-----------------------------
STRING The string of data to be scanned. Up to 500 bytes
may be specified. In a typical example, the string
would be a field in a data base file such as
customer name or address.
CMPVAL The comparison value to check against the STRING
value. CMPVAL must contain at least one fixed or
floating wildcard such as 'A%B', 'A%B*', or 'A%*B*'.
A wildcard may not follow a floating wildcard
character. Up to 20 bytes may be specified.
RESULT The returned result after the comparison is made.
This must be specified as *CHAR LEN(1) and will
contain either Y or N.
STRINGLEN The length of the value in the STRING parameter.
The default is 50. The length may be between 1 and
500 bytes.
It is not an error to specify a larger length than
the actual data. For example, if the field to be
scanned is 25 bytes, specifying 25 would be typical
rather than determining the actual length of the
data.
If you have a large field that needs to be scanned,
specifying an actual length of the data improves
performance as the possible entire value may not
have to be scanned.
FIXWLDCRD The character that is the fixed wildcard. The
default is '%'.
FLTWLDCRD The character that is the floating wildcard. The
default is '*'.
CHKWLDCRD2 parameters *CMD
---------------------
CMPVAL The comparison value to checked. It may contain
*ALL, or a simple name such as 'ABC' or 'AB3'. It
may contain wildcard characters such as 'A%*C'
'A%*1*', or *A*'). Up to 20 bytes may be specified.
Any non-wildcard characters are valid including
blank. A wildcard may not follow a floating
wildcard character.
WLDCRD A Y/N return value for whether the CMPVAL contains
wildcard characters. A 'Y' will be returned if
wildcard characters exist. A generic value such as
ABC* considered to be a generic value and does not
contain wildcard characters. A CMPVAL such as
'A%B', 'A%B*', 'A*B', or 'A*B*' would cause a 'Y' to
be returned.
This is an optional return variable that if used
must be specified as *CHAR LEN(1).
RTNVAL The returned value that is intended to be used as a
SETLL value or to compare to data base records.
If CMPVAL(*ALL) is used, '*ALL' is returned.
If a simple name like CMPVAL(ABC) is used, 'ABC' is
returned.
If a generic like value CMPVAL(ABC*) is used, 'ABC'
is returned.
If CMPVAL(AB%D*) is used, 'AB' is returned.
This allows an application to use a SETLL limit
function or to compare to the first N bytes of a
value to determine whether the CMPWLDCRD2 function
should be used. For each entry processed, the
CMPWLDCRD2 command (or CPP) would be used to
determine if a match exists.
This is an optional return variable that if used
must be specified as *CHAR LEN(20).
FIXWLDCRD The character that is the fixed wildcard. The
default is '%'.
FLTWLDCRD The character that is the floating wildcard. The
default is '*'.
Calling the CMPWLDCRD CPP directly
----------------------------------
A HLL program may call the CPP for CMPWLDCRD directly such as the
following RPG code:
C CALL 'TAACLRWC' CMPWLDCRD
C PARM xxx NAME 10 Name
C PARM 'A%C*' CMPVAL 10 Comp value
C PARM RESULT 1 Result
C PARM '%' FIXWLD 1 Fixed wldcrd
C PARM '*' FLTWLD 1 Float wldcrd
The RESULT field will contain 'Y' or 'N'.
Calling the CMPWLDCRD2 CPP directly
----------------------- -----------
A HLL program may call the CPP for CMPWLDCRD2 directly using RPG
code. In this example, the CUSNAM field (fixed length) from the data
base is scanned for a comparison value containing wild cards. Assume
that a CL program has used CHKWLDCRD2 and has passed the CMPVAL
parameter to RPG.
I* CMPWLDCRD TAA Tool - CPP for CMPWLDCRD2
I 'TAATOOL/TAACLRWC3' C WLDCRD
ISTRNDS DS 500
.
C READ xxxx
.
C* Move CUSNAM to parameter field and get the length
C MOVELCUSNAM STRNDS Move to DS
C ' ' CHEKRCUSNAM STRNLN String len
C* Call CPP of CMPWLDCRD2
C CMPWLD TAG Compare
C CALL WLDCRD CMPWLDCRD
C PARM STRNDS String
C PARM CMPVAL 20 Comp value
C PARM RESULT 1 Result
C PARM STRNLN 30 String len
C PARM '%' FIXWLD 1 Fixed wldcrd
C PARM '*' FLTWLD 1 Float wldcrd
C* If RESULT is 'Y', the name matches
To avoid calling the CMPWLDCRD3 program for every record, it would be
possible to pass in the RTNVAL parameter from CHKWLDCRD2 and use it
(and its length) to compare to the first few bytes of the CUSNAM
field. An example of this type of coding exists in the SCNDTA
program TAADBIGR.
Restrictions
------------
Because the commands return variables, they may only be used in a CL
program. The CMPWLDCRD and CMPWLDCRD2 CPPs may be called directly as
described previously.
Prerequisites
-------------
The following TAA Tools must be on your system:
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
------ ---- --------- ---------- ----------
CMPWLDCRD *CMD TAACLRW QATTCMD
CHKWLDCRD *CMD TAACLRW2 QATTCMD
CMPWLDCRD2 *CMD TAACLRW3 QATTCMD
CHKWLDCRD2 *CMD TAACLRW4 QATTCMD
TAACLRWC *PGM CLP TAACLRWC QATTCL
TAACLRWC2 *PGM CLP TAACLRWC2 QATTCL
TAACLRWC3 *PGM CLP TAACLRW3 QATTCL
TAACLRWC4 *PGM CLP TAACLRWC4 QATTCL
TAACLRWC11 *PGM CLP TAACLRWC11 QATTCL
TAACLRWC11 is the sample program.
Structure
---------
CMPWLDCRD Cmd
TAACLRWC CL Pgm
CHKWLDCRD Cmd
TAACLRWC2 CL Pgm
CMPWLDCRD2 Cmd
TAACLRWC3 CL Pgm
CHKWLDCRD2 Cmd
TAACLRWC4 CL Pgm
|
