Transposition Routines for Command Limiting › Transposition Routines

Transposition Routines

ALLSPFIL

ALLSPFIL accepts all spool files. This routine validates that the data specified in the command is valid decimal data. When used with SPOOLOPT=SELECT, the operand selects files from the spool queue and is interpreted as the highest numbered spool file selected.

ALLSYS

ALLSYS accepts the keyword ALL on a CSE command and the pseudo operand ALL on a rule. The pseudo operand ALL in a rule matches each system name, not just the keyword ALL on a command line. On a rule with the ALL pseudoname, each system name in the CSESYS table is matched to the system name on the command. If any one matches, this rule matches the command.

If a rule has a specific system name and the command has the keyword ALL in it, conditional processing is done to match this rule to the command. If the rule specifies ALLOW, the rule only matches the keyword ALL when it matches every name in the CSE name list. This means that if you allow commands for one system, you do not necessarily allow the command for all systems.

If, however, the rule is a PREVENT rule, the rule matches the keyword ALL if it matches any name in the CSE name list. In other words, if a rule prevents any single system and allows the rest, the routine prevents the ALL keyword on the command.

ALLSYS works like an ANY transposition routine on non-XA systems. Test these transposition routines on XA systems.

ALLURDEV

ALLURDEV accepts spool queues and converts the words PRINTER, PUNCH, READER, and CONSOLE to PRT, PUN, RDR, and CON, respectively. When you use this routine with SPOOLOPT=SELECT, it selects files from the spool queue. The routine also checks to ensure that the specified device is a real unit record device.

ANY

ANY accepts any operand as long as it is not greater than the maximum allowed length of the operand. The value of the operand is accepted as entered in the command syntax. For example, the password operand of the AUTOLOG command uses the ANY routine.

CLASS

CLASS validates that the operand is a valid class character. Possible classes are A-Z, 0-9, or * that means all classes. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue. For example, the CLASS operand of the CHANGE command uses the CLASS routine.

COPY

COPY accepts any decimal operand as long as it is not greater than the maximum allowed length of the operand. The value of the operand is accepted as entered in the command syntax. When used with SPOOLOPT=SELECT, it selects files from the spool queue.

Below is an example using no masking. The number portion must be a valid decimal digit.

Below is an example of using an asterisk (*) for masking. The transposition routine converts any operand with an asterisk to a low and a high range. It converts character positions with an asterisk in the low range to zeros and converts character positions with an asterisk in the high range to nines.

Following is an example of using a dash (-) for masking. The transposition routine converts any operand with a dash to a low and a high range. The value before the dash becomes the low range. The value after the dash becomes the high range. If you omit the high range, then the high range defaults to the largest value that the transposition routine can convert to a fullword.

Below is an example of using a combination of asterisks and dashes for masking.

CPSYSTEM

CPSYSTEM accepts the SYSTEM keyword that means the system SPOOL Q. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue.

DECIMAL

For a command request, DECIMAL checks to be sure the data specified in the command is really decimal data. For a rule validation request, DECIMAL checks for masking. If there is no masking in the rule, the routine treats the rule like a command; otherwise, the routine builds an upper and lower range and checks both for decimal data. Masking in this case is treated as numeric, with each asterisk (*) occupying a decimal position.

You can specify TYPE=RANGE to denote a decimal range.

Below is an example using no masking. The number portion must be a valid decimal digit.

Below is an example of using an asterisk (*) for masking. The transposition routine converts any operand with an asterisk to a low and a high range. It converts character positions with an asterisk in the low range to zeros and converts character positions with an asterisk in the high range to nines.

Following is an example of using a dash (-) for masking. The transposition routine converts any operand with a dash to a low and a high range. The value before the dash becomes the low range. The value after the dash becomes the high range. If you omit the high range, then the high range defaults to the largest value the transposition routine can convert to a fullword.

Below is an example of using a combination of asterisks and dashes for masking.

In the sample rule below, user OPR1 can issue the ECHO command 001 to 991 times. The second rule entry lets user OPR2 issue the ECHO command any number of times (NN is the pseudo operand). The third entry lets user OPR3 issue the ECHO command once.

$KEY(ECHO)
 **1 UID(OPR1) ALLOW
 NN UID(OPR2) ALLOW
 1 UID(OPR3) ALLOW

DEST

DEST accepts any operand as long as it is not greater than the maximum allowed length of the operand. The routine accepts the value of the operand as entered in the command syntax. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue. For example, the value for the DEST operand in the CHANGE command uses the DEST routine.

DSNAME

DSNAME validates that:

• The data set name is not more than eight characters between the periods (.), which are delimiters.
• The data set name is not less than one character.
• There are no embedded blanks in the string.
• The total length of the string is not greater than 24 characters.

For example, the dsname option for the NAME operand of the CHANGE command uses the DSNAME routine.

FORM

FORM accepts any operand as long as it is not greater than the maximum allowed length of the operand. The routine accepts the value of the operand as entered in the command syntax. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue. For example, the value for the FORM operand in the CHANGE command uses the FORM routine.

HEX

HEX is the same as DECIMAL except that it checks for valid hexadecimal arithmetic values. The input is right-justified and hex zero filled and then converted to a binary number. Refer to the HEXDATA transposition routine below for operands with hexadecimal character strings. You can specify TYPE=RANGE with HEX to denote a hexadecimal range.

For a command request, HEX checks to be sure the data specified in the command is really hexadecimal data. For a rule validation request, HEX checks for masking. If there is no masking in the rule, the routine treats the rule like a command; otherwise, the routine builds an upper and lower range and checks both for hexadecimal data. The routine treats masking in this case as numeric, with each asterisk (*) occupying a decimal position.

Below is an example using no masking. The number portion must be a valid hexadecimal digit.

Below is an example of using an asterisk (*) for masking. The transposition routine converts any operand with an asterisk to a low and a high range. It converts character positions with an asterisk in the low range to zeros and converts character positions with an asterisk in the high range to Fs.

Below is an example of using a dash (-) for masking. The transposition routine converts any operand with a dash to a low and a high range. The value before the dash becomes the low range. The value after the dash becomes the high range. If you omit the high range, then the high range defaults to the largest value that the transposition routine can convert to a fullword.

Below is an example of using a combination of asterisks and dashes for masking.

In the rule below, the first rule entry keeps anyone from setting an ADSTOP between address 0 - FFFF. (Each * is a place holder.) The second rule entry keeps anyone from setting an ADSTOP between 1000 and 1FFF. The first and second rule entries effectively prevent a user from setting an ADSTOP below address 2000.

$KEY(ADSTOP)
 **** UID(*) PREVENT
 1000-1FFF UID(*) PREVENT
 - UID(*) ALLOW

For example, the hexloc operand of the ADSTOP command uses HEX routine.

HEXDATA

Processes hexadecimal input as character type data.

Refer to the HEX transposition routine above for operands with hexadecimal arithmetic values.

The input string is validated for hexadecimal characters, then left-justified and right-filled with hex zeros, if required. This string can be masked in a rule. Masked strings are not allowed in commands. The string consists of an even number of characters, each representing half a hexadecimal character. A trailing mask of a dash fills the input string to an even number of characters, if required.

Below are examples of valid and invalid HEXDATA strings.

HHMM

During command syntax checking, HHMM converts hours and minutes to seconds. It locates the delimiter (:) between the HH and MM, right justifies both hours and minutes, then changes the value to seconds.

The routine checks for a mask that represents the valid time value during rules validation. If you do not use masking, the routine treats the rule like a command. If you do use masking, HHMM tries to find a delimiter in the mask (:). After finding the delimiter, the routine builds an upper and lower range of seconds for both the hours and minutes. If there is no delimiter, it converts the string to a seconds value.

HOSTSTRG

HOSTSTRG applies to XA operating systems only. It validates whether a STORE command has a host or guest operand specified. The default is a guest machine. If you did not specify a machine, the routine assumes guest.

STORE S20010 0000 HU00 THIS IS A TEST

In the above example, the routine returns HOST to the command interpreter (denoted by H in the HU00 operand).

LDEV

LDEV validates that the first character of a logical device is always L and the rest of the operand is a readable hexadecimal number. You can specify TYPE=RANGE with LDEV to denote a range of logical devices.

For a command syntax check, the routine checks only the first character to ensure it is an L. If not, then a syntax error occurs. If it is L, the HEX routine translates the hexadecimal number. For rules validation, you can specify the first character of a logical device address as a mask (*). For example, the LINES operand of the QUERY command uses the LDEV routine.

LDEVXA

.LDEVXA ensures that operands begin with L. It allows as many positions in the operand as specified in the syntax model, except that it limits the maximum number of numeric positions in a segment to eight digits. You can use masking, however, you cannot mask in ranges. The routine converts all values to binary for comparison purposes.

Below is an example using no masking. You must prefix the operand with L. The number portion must be a valid hex digit.

This is an example of using an asterisk (*) for masking:

Following is an example of using a dash (-) for masking. If you use a dash, it must be the last byte.

Below is an example of using a combination of asterisks and dashes for masking. If you use a dash, it must be the last byte.

LDEV Ranges:

The LDEV range technique provides more flexibility. You can use a dash as a range character, not a masking character. There are two parts to a range: the low segment and the high segment.

When using LDEV ranges, remember:

• You cannot mask in ranges.
• Each segment must start with L.
• The rest of the segment must contain valid hexadecimal numbers.
• The high segment must be greater in value than the low segment.

An example of LDEV ranges follows.

LOCALSYS

LOCALSYS converts an asterisk in a CSE-related command to the local system name defined in CSESYS in HCPSYS (the name of the system the user is on). The routine does not interpret an asterisk in the rule as the local system because it considers an asterisk to be a single character mask. The routine translates the asterisk in a command to the local system name before processing it against a command limiting rule. This lets you write a rule for a specific system.

LOCALSYS works like an ANY transposition routine on non-XA systems. Test these transposition routines on XA systems.

LPRT

LPRT accepts any operand as long as it is not greater than the maximum allowed length of the operand. The value of the operand is accepted as entered in the command syntax. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue.

For example, the value for the LPRT operand in the CHANGE command uses the LPRT routine.

MINSIZE

During command syntax checking, MINSIZE validates that the operand conforms to the syntax of MINSIZE=nnnK or MINSIZE=nnnM, where nnn is a valid storage size. This transposition routine is identical to STRSIZE except that you must precede the storage size with MINSIZE=. For more rule masking examples, see STRSIZE in this appendix. All values are normalized to K-bytes before comparison.

MMSS

During command syntax checking, MMSS converts minutes and seconds to seconds. It locates the delimiter (:) between the MM and SS, right justifies both minutes and seconds, then changes the value to seconds.

The routine checks for a mask that represents the valid time value during rules validation. If you do not use masking, the routine treats the rule like a command. If you do use masking, MMSS tries to find a delimiter in the mask (:). After finding the delimiter, the routine builds an upper and lower range of seconds for both the minutes and seconds. If there is no delimiter, the routine converts the string to a seconds value.

If you enter unmasked times in rules, the routine will not find a match.

PARMREGS

During command syntax checking, PARMREGS validates that the operand conforms to the syntax of PARMREGS=n-n or PARMREGS=n, where n is a valid decimal value with a maximum a two digits.

PERCENT

PERCENT validates and checks the syntax to ensure that the last character of the operand is a percent sign. The routine transposes the percent sign to a null and normal processing continues (for example, SET SRM IABIAS 10%).

When writing the rule, do not include the % character in the rule entry.

Below is an example using no masking. The number portion must be a valid decimal digit.

Below is an example of using an asterisk (*) for masking. The transposition routine converts any operand with an asterisk to a low and a high range. It converts character positions with an asterisk in the low range to zeros and converts character positions with an asterisk in the high range to nines.

Following is an example of using a dash (-) for masking. The transposition routine converts any operand with a dash to a low and a high range. The value before the dash becomes the low range. The value after the dash becomes the high range. If you omit the high range, then the high range defaults to the largest value the transposition can convert to a fullword.

Below is an example of using a combination of asterisks and dashes for masking.

PFKEY

PFKEY validates that the PF key number is between 01 and 24. For rule validation, you can mask the PF key number. Examples of this are shown below. If you do not mask the PF key number in the rule, the routine treats it like a command.

For example, the PF nn operand of the QUERY command uses the PFKEY routine.

RCUU

For a command request, RCUU validates that the real device address specified in the command is really a valid hexadecimal number. You can specify TYPE=RANGE with RCUU to denote a range of real device addresses.

For a rule validation request, RCUU checks for masking. If there is no masking in the rule, the routine treats it like a command. Otherwise, it builds an upper and lower range and checks both for hexadecimal data. Below is an example using no masking. The number portion must be a valid hexadecimal digit.

Below is an example of using an asterisk (*) for masking. The transposition routine converts any operand with an asterisk to a low and a high range. It converts character positions with an asterisk in the low range to zeros and converts character positions with an asterisk in the high range to Fs.

Below is an example of using a dash (-) for masking. The transposition routine converts any operand with a dash to a low and a high range. The value before the dash becomes the low range. The value after the dash becomes the high range. If you omit the high range, then the high range defaults to the largest value that the transposition routine can convert to a fullword.

Below is an example of using a combination of asterisks and dashes for masking.

For example, the rcuu operand of the ATTACH command, when specified a single device address, uses the RCUU routine.

REST

REST validates that the length of all remaining command operands is not greater than the allowed maximum. For example, the variable data operand of the AUTOLOG command uses the REST routine.

RUR (REAL)

RUR is the same as VUR (VIRTUAL) except that the routine scans the real device block for the device class and type to make sure it is a real device. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue. Specify the generic names of RDR, PRT, or PUN in the rule entry. When writing rules for operands that use this transposition routine, use the following:

Do not use real device addresses, such as 00C (commonly a reader) in rules, instead use RDR. The SPOOLOPT operand further restricts the use of any or all of these devices. During rules validation, the operand mask indicates PRT, PUN, RDR, or CON represents a generic type of unit record. We show some examples of this in the next example.

SELF

In a command syntax check, if the operand is an asterisk (*), the routine translates it to OWNER for rules validation. For rules validation, use the word OWNER to indicate the user can specify the asterisk (*) operand in the command. When you use SELF with SPOOLOPT=SELECT, it selects files from the spool queue. For example, the * operand of the ATTACH command uses the SELF routine.

SPOOL

For a command syntax check, SPOOL validates that the data specified in the command is really decimal data. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue.

For a rule validation request, SPOOL checks for masking. If there is no masking in the rule, the routine treats the rule like a command. Otherwise, the routine builds an upper and lower range and checks both for decimal data. For example, the spoolid operand of the CHANGE command uses the SPOOL routine.

SPOOLTO

SPOOLTO validates that the data specified in the command is decimal data or the END keyword. If you specify END, the routine converts it to 9999. When used with SPOOLOPT=SELECT, it selects files from the spool queue.

STORADDR

For a command syntax check, STORADDR locates one of the three possible delimiters: colon (:), dash (-), or period (.). Both the colon and dash indicate that the value is a fixed range. The period delimiter means the routine adds the value after the delimiter to the value before the delimiter. This results in a low-storage to high-storage address range for the command.

For a rules validation, the routine locates the delimiter. When the command delimiter is a dash, the routine validates that the dash is not the last character in the rule entry. If it is the last character, the routine treats it as a masking character for multiple characters during rule validation.

If the last character in the rule mask is not a dash, the routine checks the mask for one of the other delimiters. After the routine locates the real command delimiter, it converts the value before the delimiter to the low address and the value after the delimiter to the high address to build an address range. It then matches this range against the rules to validate execution of a command.

For example, the hexloc options of the DCP command use the STORADDR routine.

STORDISP

STORDISP is the same as STORADDR, except that the routine justifies the upper and lower address ranges to a 4-byte boundary. However, if you prefix the storage address with a T, the routine justifies the range to a 16-byte boundary.

STORDUMP

STORDUMP is the same as STORADDR, except that the routine justifies the upper and lower address ranges to a 32-byte boundary.

STORVDMP

STORVDMP is the same as STORADDR, except that the routine justifies the upper and lower address ranges to a 4K-byte boundary.

STRSIZE

During command syntax checking, STRSIZE validates that the operand is between 0K and 999M and checks for masking (* and -) and range values. If you use range values, the last position must be either K or M, and the numeric part must be a valid decimal number. You cannot mask range operands. The routine normalizes all values to K-bytes.

For rules validation, the routine converts the storage size to a nnnnnK value. When comparing to a rule mask, the routine uses a lower and upper range value. We show some examples of this conversion below. First is an example with no masking used.

Some examples of this conversion with masking using an asterisk (*) are:

We show some examples of this conversion with masking using a dash (-) below. The dash must be the last byte.

We show some examples of this conversion with masking using asterisk (*) and dash (-) below. The dash must be the last byte.

Listed below are some examples of storage ranges. This preferred technique specifies ranges of storage more easily. It lets you use a dash (-) as a range character, not a masking character. You cannot mask in a range.

SYSNAME

SYSNAME scans the CSESYS table in HCPSYS to validate that a system name is a valid CSE system name. A command fails with an CA ACF2 for z/ VM syntax error if the system name or alias specified on a command is not in this list. When you specify a valid system name or alias in the command, this transposition routine converts the alias name into the system name. This lets you write rules for the system name while protecting the alias name.

When you specify a valid system name or alias in a rule, this routine also converts the alias name into the system name for the rule. If you write the rule for the alias name, you also protect the system name. You can use a new pseudoname, LOCAL, to write rules that apply only to the system the user is on. This is similar to using OWNER when dealing with spool-related commands.

SYSNAME works like an ANY transposition routine on non-XA systems. Test these transposition routines on XA systems.

USER

During a command syntax check, USER verifies that the user ID is greater than one and less than (or equal to) eight characters. Except for CMDLIM rule compiles, it also checks to ensure the specified user ID is in the VM directory. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue. For example, the user ID operand of the QUERY command uses the USER routine. The routine checks the VM directory to help determine the command format the user is using so that CA ACF2 for z/ VM uses the correct FORMAT clause in the command model during validation.

VCUU

For a command request, VCUU validates that the data specified in the command is really hexadecimal data. You can specify TYPE=RANGE with VCUU to denote a range of hexadecimal data.

For a rule validation request, VCUU checks for masking. If there is no masking in the rule, the routine treats the rule like a command. Otherwise, the routine builds an upper and lower range and checks both for hexadecimal data.

Below is an example using no masking. The number portion must be a valid hexadecimal digit.

Below is an example of using an asterisk (*) for masking. The transposition routine converts any operand with an asterisk to a low and a high range. It converts character positions with an asterisk in the low range to zeros and converts character positions with an asterisk in the high range to Fs.

Below is an example of using a dash (-) for masking. The transposition routine converts any operand with a dash to a low and a high range. The value before the dash becomes the low range. The value after the dash becomes the high range. If you omit the high range, then the high range defaults to the largest value that the transposition routine can convert to a fullword.

Below is an example of using a combination of asterisks and dashes for masking.

For a rule validation request, VCUU checks for masking. If there is no masking in the rule, the routine treats the rule like a command. Otherwise, the routine builds an upper and lower range and checks both for hexadecimal data. For example, the vaddr operand of the ATTACH command uses the VCUU routine.

VUR (VIRTUAL)

During command syntax checking, VUR converts the words (or abbreviation) PRINTER, PUNCH, READER, or CONSOLE to PRT, PUN, RDR, or CON, respectively. It also checks to ensure that the device is really a PRT or PUN. When you use this operand with SPOOLOPT=SELECT, it selects files from the spool queue. For examples and restrictions, see Spool Related Operands (Format 4) in the chapter “Using the Model Setting.”

When writing rules for operands that use this transposition routine, use the following:

Do not use real device addresses, such as 00C (commonly a reader) in rules, instead use RDR. The SPOOLOPT operand further restricts the use of any or all of these devices.

During rules validation, the operand mask indicates PRT, PUN, RDR, or CON represents a generic type of unit record. We show some examples of this in the next example.

XSIZE

This transposition routine looks for a trailing M to normalize the storage size operand of the XSIZE command. If it finds one, it converts the decimal part of the operand into a binary word so that command limiting can match everything up (for example, ATTACH XSIZE 128000M).