The CMDVAL macro checks whether a value matches an SDF data type description. The macro passes on the result of the check and, if requested, an SDF error message to the PROT buffer. The error messages are not output to SYSOUT. This macro can also be used to check whether an input string matches a predefined wildcard search pattern.
Operation | Operands |
CMDVAL | INPUT = addr [, DATATYP = NOCHECK / INTEGER / INT64 / XSTRING / CSTRING / NAME / ALPHANAME / STRUCNAME / FILENAME / PARTFILE / TIME / DATE / COMPNAME / TEXT / CATID / KEYWORD / KEYNUMBER / VSN / XTEST / FIXED / DEVICE / PRODVERS / PPOSIXPATH / POSIXFILE ] [ ,SHORTST = *ANY / integer ] [ ,LONGEST = *ANY / integer ] [ ,WCLOGL = *NONE / integer ] [ ,LOWDEC = 0 / integer ] [ ,HIGDEC = 0 / integer ] [ ,CONST = *NO / addr / (addr, ...) ] [ ,PATTERN = *NO / addr ] ,[ ATTRIB = { *NONE / ([NOCATID] [,NOUSERID] [,NOGENERATION] | [,NOVERSION] [,WILDCARD] [,KEYSTAR][,NOSEPERATORS] [,UNDERSCORE] [,NOODD] [,NOALIAS] [,VOLUMEONLY] [,NOUSERINT] | [,NOCORSTATE] [,ANYCORSTATE] [,WILDCONST] [,LOWERCASE] [,TEMPFILE] [,QUOTESMAND] [,ANYUSERINT] [,STDDISK]) ] [ ,DEVCLAS = list-poss(2): DISK / TAPE ] [ ,EXCDISK = *NONE / addr / (text8,...) ] [ ,EXCTAPE = *NONE / addr / (text8,...) ] [ ,PROT = *NO / addr ] |
CMDVAL | [ ,PREFIX = C / p ] [ ,MACID = MDV / mac ] [ ,MF = D / C / L / E ] [ ,PARAM = addr ] |
INPUT = addr
String representing a value in variable record format (first halfword: length of the record; second halfword: fill characters used to pad the record to the specified length).
No blanks are allowed as part of the input (exception: blanks within a value of the type <cstring> or <text>).
addr must be aligned on a word boundary.
DATATYP =
Specifies the data type for which the value is to be checked (see statement ADD-VALUE TYPE=...).
NOCHECK
No data type check. Instead, the value is checked to verify whether it matches a wildcard search pattern. The PATTERN parameter is mandatory in conjunction with NOCHECK.
The following table shows the possible data type checks:
DATATYPE= | Data type whose value is checked |
INTEGER | <integer> |
| INT64 | <long-integer> |
XSTRING | <x-string> |
CSTRING | <c-string> |
NAME | <name> |
ALPHANAME | <alphanum-name> |
STRUCNAME | <structured-name> |
FILENAME | <filename> |
PARTFILE | <partial-filename> |
TIME | <time> |
DATE | <date> |
COMPONAME | <composed-name> |
CATID | <cat-id> |
TEXT | The value is checked for the data type <text> if it is a positional operand in an operation. The value is invalid if it contains incorrectly placed separators. |
KEYWORD | <keyword> |
KEYNUMBER | <keyword-number> |
VSN | <vsn> |
XTEXT | <x-text> |
FIXED | <fixed> |
DEVICE | <device> |
PRODVERS | <product-version> |
POSIXPATH | <posix-pathname> |
POSIXFILE | <posix-filename> |
SHORTST =
Specifies a minimum length (if any) for the string (see ADD-VALUE TYPE=...(SHORTEST-LENGTH=...)). For the data types DATE, TIME, CATID, KEYWORD and KEYNUMBER, this parameter is irrelevant. If the data type is XSTRING, SHORTST is the number of bytes in the value specified as INPUT. If the data type is INTEGER or INT64, SHORTST is the lower limit of the value range; if the data type is FIXED, SHORTST is combined with the LOWDEC parameter. An integer complete with sign can be specified for both these data types.
*ANY
The limits specified by SDF apply to the data type.
integer
Explicitly specifies the minimum length.
LONGEST =
Specifies a maximum length (if any) for the string (see ADD-VALUE TYPE=... (LONGEST-LENGTH=...)). For the data types DATE, TIME, CATID, KEYWORD and KEYNUMBER, this parameter is irrelevant. If the data type is XSTRING, LONGEST is the number of bytes in the value specified as INPUT. If the data type is INTEGER, LONGEST is the upper limit of the value range; if the data type is FIXED, LONGEST is combined with the HIGDEC parameter. An integer complete with sign can be specified for both these data types.
*ANY
The limits specified by SDF apply to the data type.
integer
Explicitly specifies the maximum length.
WCLOGL =
Relevant only with ATTRIB=WILDCARD. The value specified as INPUT may include wildcards. WCLOGL specifies the maximum length of the value matching the wildcard search pattern, whereas LONGEST specifies the actual length of the input value.
This parameter has no significance for the data types POSIXPATH and POSIXFILE.
*NONE
The limits specified by SDF apply.
integer
Explicitly specifies the maximum length.
LOWDEC = 0 / integer
Specifies the number of decimal places for SHORTST. Relevant only if the data type is FIXED.
HIGDEC = 0 / integer
Specifies the number of decimal places for LONGEST. Relevant only if the data type is FIXED.
CONST = *NO / addr / (addr,...)
The INPUT value is compared with the constants specified here. CONST is relevant only with DATATYP=NOCHECK. The constants must be stored in records of variable length. If the data type of the INPUT value is KEYWORD or KEYNUMBER, the value can be an abbreviation of one of the constants. Note, however, that lists are not supported. The number of constants is limited to 2000. The minimum and maximum lengths of the constants depend on the defaults for SDF data types.
addr
The record addresses are grouped in a field beginning with the address addr. This field must be aligned on a word boundary and its format must be as follows:
Byte | Meaning |
0 | Number of elements in the field (N, 2 bytes long) |
2 | Filler |
4 | Address of 1st record (aligned on word boundary) |
8 | Address of 2nd record (aligned on word boundary) |
... | |
N*4 | Address of nth record (aligned on word boundary) |
(addr,...)
The record addresses are listed.
PATTERN = *NO / addr
The INPUT value is compared with a wildcard search pattern.
If checking for a data type is requested, the syntax is subject to the conventions for wildcards for the data type in question (including the maximum length of the wildcard expression).
With DATATYP=NOCHECK, the INPUT value is checked to verify only whether it matches the specified wildcard search pattern (no data type check). The length of the wildcard expression is not restricted in this case. Wildcards are not valid for all data types (see statement ADD-VALUE TYPE=...). PATTERN cannot be used together with ATTRIB=(...,WILD-CARD,...).
With DATATYPE=POSIXPATH or POSIXFILE, a special POSIX wildcard syntax applies instead of the BS2000 wildcard syntax. PATTERN cannot be specified for either of these data types.
PATTERN = addr
Specifies the address of a record of variable length in which the wildcard search pattern is stored. addr must be aligned on a word boundary. The value in the record length field of the V record is equal to the sum of the exact length of the search pattern and the length of the record field (e.g. the record length field for “ABC*” will have the value 4+4=8). Trailing blanks are not allowed in the pattern.
ATTRIB = (...)
Specifies a list of attributes valid for the data type. Invalid combinations are rejected and an error message issued. The attributes must be enclosed by parentheses. This applies even if the list contains only one attribute. See the ADD-VALUE statement for more detailed information.
Attributes | Meaning and possible data type |
*NONE | The SDF defaults apply for the attributes. |
NOCATID | Specification of a catalog ID is not permissible |
NOUSERID | Specification of a user ID is not permissible |
NOGENERATION | Specification of a generation number is not permissible |
NOVERSION | Specification of a generation number is not permissible |
WILDCARD | Wildcards may be used. The WILDCARD attribute must not be used together |
KEYSTAR | The input string must be preceded by an asterisk |
NOSEPERATORS | Separators are not allowed (data type <text>). |
UNDERSCORE | The underscore character (_) is allowed (<name>, <composed-name>) |
NOODD | The string must not consist of an odd number of characters (data type |
NOALIAS | Aliases are not allowed |
VOLUMEONLY | Volume type is accepted (data type <device>). |
| NOUSERINT | Specification of the user interface is not allowed (data type <product-version>) |
NOCORSTATE | Specification of the correction state is not allowed (data type <productversion>). If NOUSERINT was specified in the list, NOCORSTATE automatically |
ANYCORSTATE | Specification of the correction state is permitted for <product-version>. |
WILDCONST | The value can be a wildcard constructor (see ADD-VALUE TYPE= |
LOWERCASE | Lowercase characters are retained (data type <name>). |
NOTEMPFILE | Temporary file names are not permitted (data type <filename>). |
QUOTESMAND | POSIX path names and file names must be enclosed in single quotes |
ANYUSERINT | The release status of the user interface can be specified (data type |
STDDISK | Only standard disk devices may be used (data type <device>) |
DEVCLAS = DISK / TAPE
Specifies the device class (data type <device>, see statement ADD-VALUE TYPE=*DEVICE(...)).
EXCDISK = *NONE / addr / (text8,...)
Specifies the excluded disk devices (data type <device>). The list may contain a maximum of 50 device names.
addr
Specifies the address of a field aligned on a word boundary and containing the device names. The first halfword in the field contains the number of elements in the field, the second halfword contains the filler. The device names following the filler are each 8 bytes long; separators are not permitted in the names. If the real device names are shorter than 8 bytes, they must be entered left-justified and padded with blanks to the full length.
EXCDISK = (text8,...)
Specifies a list of device names, each name being 8 bytes long. The rules of syntax for data types <text-without-sep> apply to the device names.
EXCTAPE = *NONE / addr / (text8,...)
Specifies the excluded tape devices. This parameter is used only in conjunction with DEVICE=TAPE (see ADD-VALUE TYPE=*DEVICE(...)). The list may contain a maximum of 50 device names.
addr
Specifies the address of a field aligned on a word boundary and containing the device names. The first halfword in the field contains the number of elements in the field, the second halfword contains the filler. The device names following the filler are each 8 bytes long; separators are not permitted in the names. If the real device names are shorter than 8 bytes, they must be entered left-justified and padded with blanks to the full length.
EXCTAPE = ((text8,...)
Specifies a list of device names, each name being 8 bytes long. The rules of syntax for data types <text-without-sep> apply to the device names.
PROT = *NO / addr
Record of variable length in which SDF stores the error message for the checked value. addr must be aligned on a word boundary. For details of the record, see the description of the BUFFER parameter in the CMDRST macro.
For descriptions of the parameters PREFIX, MACID, MF and PARAM, see section “Macrotypes”ff.
Possible calls
[label] CMDVAL MF=D [,PREFIX=p][,MACID=mac] [label] CMDVAL MF=C [,PREFIX=p][,MACID=mac] [label] CMDVAL MF=L,... [label] CMDVAL MF=E,PARAM=addr
The CMDVAL macro is implemented with a standard header, which means that the form MF=S is not available.
Register usage
Register 1: Address of the parameter list.
Register 15: Return code that is additionally passed in the standard header as well.
Return information and error flags
The return code is passed in the standard header of the parameter area.
| Standard header |
| cc: Subcode 2 (SC2) bb: Subcode 1 (SC1) aaaa: Maincode |
| (SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
| 00 | 00 | 0000 | Checked value matches data type and/or wildcard search pattern. |
| 01 | 01 | 0008 | The INPUT parameter is invalid. |
| 02 | 01 | 0008 | Invalid address (not allocated, not aligned on word boundary, ...) |
| 03 | 01 | 0008 | Invalid specification for – the combination DATATYP/ATTRIB/PATTERN or – the combination DEVCLAS/EXCDISK/EXCTAPE |
| 04 | 01 | 0008 | Invalid specifications for value ranges: – upper limit < lower limit, – SDF-A limits violated, – values incorrect, – number of decimal places not specified, – limits invalid |
| 05 | 01 | 0008 | The PATTERN parameter is invalid (length=0, syntax error) |
| 06 | 01 | 0008 | The CONST parameter is invalid |
| xx | 40 | 001C | The checked value does not match data type and/ or wildcard search pattern. An SDF error message has been written into the PROT buffer. The input value was: |
| 01 | 40 | 001C | not of the specified data type or was without the specified attributes |
| 02 | 40 | 001C | not one of the specified devices |
| 03 | 40 | 001C | out of the range specified by the user or SDF |
| 04 | 40 | 001C | not one of the specified constants (value or keyword) |
| 05 | 40 | 001C | not a match for the wildcard search pattern. |
Notes
If the PROT buffer is too small, the SDF error messages are truncated. It is up to the caller to recognize this situation and react accordingly.
The table below should be used for comparing file names (with file generation numbers) with a wildcard search pattern. The table contains the valid combinations for which a match is currently possible. For details on file generation groups (fggs) see the “Introductory Guide to DMS” [7 (Related publications)].
INPUT string
PATTERN string
Match possible ?
without fgg
without fgg
with fggyes
nowith absolute fgg
(abs_fgg (*nnnn))without fgg
with abs_fgg (*nnnn)
with rel_fgg (+/-nn)yes
yes if (*nnnn) matches
nowith relative fgg
(rel_fgg (+/-nn)without fgg
with abs_fgg (*nnnn)
with rel_fgg (+/-nn)yes
no
yes if (+/-nn) matchesTable 5:
abs_fgg :
absolute generation number (*nnnn), 0001
<=nnnn<=9999rel_fgg :
relative generation number (+/-nn), 0
<=nn<=99Future system extensions may render this table invalid. Consequently, it should not be considered as a guaranteed interface.
Search patterns for a file name may be of the data type <filename> or <partial-filename>.
Similarly, a partially qualified file name can be used as a wildcard search pattern.
Examples
Check a value for its data type:
... CMDVAL MF=E,PARAM=MYPL * returncode must be X'0140001C' LA 1,MYPL USING MYPLD,1 LH 2,DMDVMRET LTR 2,2 BNE ERRPROC ... MYPL CMDVAL MF=L,INPUT=BUFF@,DATATYP=FILENAME,ATTRIB=(NOCATID,WILDCARD) ... BUFF@ DS 0F BUFFL DC Y(BUFFEND-BUFF@) BUFFFIL DS XL2 BUFFCT DC C':OY:$TSOS.SDF-A' BUFFEND EQU * ... MYPLD CMDVAL MF=D,PREFIX=D ...Check whether an input value matches a wildcard search pattern:
... CMDVAL MF=E,PARAM=MYPL2 LA 1,MYPL2 USING MYPLD,1 LH 2,DMDVMRET LTR 2,2 BNE ERRPROC ... MYPL2 CMDVAL MF=L,INPUT=BUFF@,PATTERN=PATT@ ... BUFF@ DS 0F BUFFL DC Y(BUFFEND-BUFF@) BUFFFIL DS XL2 BUFFCT DC C':OY:$TSOS.SDF-A' BUFFEND EQU * ... PATT@ DS 0F PATTL DC Y(PATTEND-PATT@) PATTFIL DS XL2 PATTCT DC C':OY:$TSOS.SD/-*' PATTEND EQU * ... MYPLD CMDVAL MF=D,PREFIX=D ...