This general macro searches a data field for the presence of any specified
characters. A match with one of these specified characters will result
in a branch to a specified location, or an ENTNC to any specified
program. The user specifies the field to be searched and up to 9
characters, which will be used for matching arguments.
Associated with each of the 9 possible characters to be searched for is an
option relating to the performance of the macro when a match is found.
The count of bytes may either include the character that caused the match, or
it may not.
Format
- label
- A symbolic name can be assigned to the macro statement.
- AT=symbol1|R1
- The symbolic name of an application register other than R0 referring to
the first byte of a data field to be scanned. R1 will be assumed if the
parameter is omitted.
- CHKn
- Characters to be used for matching with bytes in the input field.
Each CHK parameter must have a corresponding GOTO parameter. The CHK
parameters may be any of the following:
- NONUM
- Any nonnumeric character (that is, not digits 0-9).
- NUM
- Any numeric character (that is, digits 0-9) will cause a
match.
- ALPHA
- Any alpha character (that is, A-Z) will cause a match.
Consider use of the ALPHA macro instead of this action.
- ALPHAX
- Any true alpha character (that is, A-Z, but excluding the nonalpha
characters in the gap between EBCDIC I and J, and in the gap between EBCDIC R
and S) will cause a match.
- location
- Any byte location that will, at macro execution time, contain a character
to be used for matching.
- Aterm
- An A followed by any character or hexadecimal self-defining
value that can be coded in a CLI instruction.
Examples are:
CHK1 = AC'B (defines a B character).
CHK1 = AX'1C' (defines a hexadecimal value of 1C).
- COUNT=symbol2|R15
- The symbolic name of an application register other than R0 which will
contain, at completion of the macro, the number of bytes including the byte
that caused the macro to stop scanning, or if OPTION is EXC, the number of
bytes preceding the byte which caused the macro to stop scanning.
R15 is assumed if the parameter is omitted.
If parameter MAX is a 1, code manipulating this register is not included
since there is no need for counting.
- FALSE=symbol3
- A symbolic location that will be branched to if no match is found within
the data field. If omitted, control will be returned to the next
sequential instruction (NSI).
- GOTOn
- An action to be performed if a match occurs for the
CHK1...CHK9 characters. The GOTO parameters are
defined as follows:
- location
- This is a location where the program branches if a match is found with the
corresponding CHKn parameter. (The symbol must not start with a
B).
- Bprogram
- This is a 4 character program name preceded by a B. The program is
entered with no return on a match with the corresponding CHKn
parameter.
- MAX
- The maximum number of bytes in the data field that are to be scanned or a
reference to a register that contains the maximum. The default maximum
is 256. The maximum for the MAX parameter is 65 536.
- symbol4
- A register containing the maximum number of bytes (meeting the
requirements of literal1). If the maximum number of bytes is equal to
1, symbol2 will not be used, since there will be no need to keep a count of
the number of bytes scanned.
- literal1
- Any number defined by the limits 1 <= literal1 <= 256. If
equal to 1, COUNT parameter is ignored.
- OPTION
- Specify one of the following:
- INC
- Causes the count of bytes to include the character that caused the
match.
- EXC
- Causes the count of bytes to exclude the character that caused the
match.
- The field to be scanned must be referenced by symbol1.
- If the CHK parameter uses a symbolic location, that location must contain
the character to be used in the match at execution time.
Entry Requirements
R9 must contain the address of the ECB being processed.
Return Conditions
- The contents of R14 and R15 are unknown. Only the registers
specified in the macro call are used by the macro:
- symbol1
- At macro initialization, will contain a reference to the first byte of the
field to be scanned. At macro completion, symbol1 will point to the
character that caused a match; or if no match occurred, symbol1 will
point to the beginning of the field + MAX.
- symbol2
- The count register is initialized to zero, and at macro completion
contains the number of characters scanned as specified by the OPTION
PARAMETER. If MAX=1, this parameter is not used.
- symbol3
- If used, the register specified containing the maximum number of bytes to
be scanned will be unchanged at macro completion.
- Control is returned on a match according to the GOTO parameters. If
MAX is reached before a match, and (symbol3) is used, control is returned to
the location specified by (symbol3); if no (symbol3) is used, control is
returned to the next sequential instruction.
- (symbol2) contains the number of characters scanned as specified by the
OPTION Parameter. If OPTION is INC, symbol2 will contain the number of
bytes including the byte which caused the macro to stop scanning, or if OPTION
is EXC, the number of bytes preceding the byte that caused the macro to stop
scanning. If MAX is a 1, this parameter is not used.
- The scanned field is not altered.
- (symbol1) points to the character that caused a match.
- The condition code is changed.
Programming Considerations
- This macro can be executed on any I-stream.
- When the maximum number to be scanned has been reached, and no match has
been found, the FALSE parameter will indicate where control will be
returned. If no FALSE parameter is used, control is returned to the
next sequential instruction.
- The CHKi parameters will be processed in numerical order (that is, CHK1,
CHK2, and so on). Processing in numerical order can be used to
advantage with the ALPHA, ALPHAX, NONUM, or NUM options. For example,
the NONUM option will cause a match on special characters as well as
alphabetic characters. If a slash, an A, and NONUM were desired as
separate options the code would be:
SCANA CHK1 = AC/,GOTO1 = PCA01,
CHK2 = ACA,GOTO2 = PCA02,
CHK3 = NONUM,GOTO3 = PCA03
If CHK1 was set as NONUM, the A and / would be treated as nonnumeric and no
distinction would be achieved.
- When searching for an ALPHA character only, consider using the ALPHA
macro.
Examples
- The following example defines a scan starting at a location pointed to by
R14 for a byte at location BXCMD1. The number of bytes scanned (and the
match byte) reaching the match character is placed in R7. If a match is
found, control transfers to location CBXM00, but if a match isn't found,
control transfers to location BCXMER0.
SCANA AT=R14,COUNT=R7,CHK1=BCXMD1,GOTO1=CBXM00,FALSE=BCXMER0
- The following example defines a scan starting at the address in R1 for a
either a slash character (/) or a non-numeric character. If a
slash is found, control transfers to location CIPF160, but if a non-numeric
character is found, control transfers to location GIPFMR08. A maximum
of four characters is scanned and the number of characters scanned before a
match is found is placed in R15.
SCANA MAX=4,CHK1=AC'/',GOTO1=CIPF160,CHK2=NONUM,
GOTO2=GIPFMR08,OPTION=EXC
- The following example defines a scan starting at the address in R6 for a
maximum of bytes indicated in R3. These bytes are scanned for either a
X'15', a X'01' or any true alphabetic character. If
X'15' is found, control transfers to location CIM130. If
X'01' is found, control transfers to location CIM160, and if any
exclusive alphabetic character is found, control transfers to CIM180.
If no match is found, control resumes at the NSI. The number of
characters scanned (including the match byte) is placed in R15 at the
conclusion of the scan.
SCANA AT=R6,COUNT=R15,FALSE=CIM140,MAX=R3,CHK1=AX'15',
GOTO1=CIM130,CHK2=AX'01',GOTO2=CIM160,
CHK3=ALPHAX,GOTO3=CIM180