Extended Character Scan (ECSCAN)

Instruction Syntax

Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand 4 Operand [5-7]
ECSCAN 10D4 Receiver Base Compare operand Mode operand
ECSCANB 1CD4 Branch options Receiver Base Compare operand Mode operand Branch targets
ECSCANI 18D4 Indicator options Receiver Base Compare operand Mode operand Indicator targets
Operand 1: Binary variable scalar or binary array.

Operand 2: Character variable scalar.

Operand 3: Character scalar.

Operand 4: Character(1) scalar.

Operand 5-7:

  • Branch Form–Branch point, instruction pointer, relative instruction number, or absolute instruction number.
  • Indicator Form–Numeric variable scalar or character variable scalar.

Description:

This instruction scans the string value of the base operand for occurrences of the string value of the compare operand and indicates the relative locations of these occurrences in the receiver operand. The character string value of the base operand is scanned for occurrences of the character string value of the compare operand under control of the mode operand and mode control characters embedded in the base string.

The base and compare operands must both be character strings. The length of the compare operand must not be greater than that of the base string. The base and compare operand are interpreted as containing a mixture of 1-byte (simple) and 2-byte (extended) character codes. The mode, simple or extended, with which the string is to be interpreted, is controlled initially by the mode operand and thereafter by mode control characters embedded in the strings. The mode control characters are as follows:

Hex 0E =
Shift out of simple character mode to extended mode.
Hex 0F =
Shift into simple character mode from extended mode. This is recognized only if it occurs in the first byte position of an extended character code.

The format of the mode operand is as follows:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Mode operand Char(1)
0
0
  • Operand 2 initial mode indicator
    0 =
    Operand starts in simple character mode.
    1 =
    Operand starts in extended character mode.
  • Bit 0
0
0
  • Operand 3 initial mode indicator
    0 =
    Operand starts in simple character mode.
    1 =
    Operand starts in extended character mode.
  • Bit 1
0 0
  • Reserved (binary 0)
  • Bits 2-7
1
1
--- End ---
 

The operation begins at the left end of the base string and continues character by character, left to right. When the base string is interpreted in simple character mode, the operation moves through the base string 1 byte at a time. When the base string is interpreted in extended character mode, the operation moves through the base string 2 bytes at a time.

The compare operand value is the entire byte string specified for the compare operand. The mode operand determines the initial mode of the compare operand. The first character of the compare operand value is assumed to be a valid character for the initial mode of the compare operand and not a mode control character. Mode control characters in the compare operand value participate in comparisons performed during the scan function except that a mode control character as the first character of the compare operand causes unpredictable results.

The base string is scanned until the mode of the characters being processed is the same as the initial mode of the compare operand value. The operation continues comparing the characters of the base string with those of the compare operand value. The starting character of the characters being compared in the base string is always a valid character for the initial mode of the compare operand value. A mode control character encountered in the base string that changed the base string mode to match the initial mode of the compare operand value does not participate in the comparison. The length of the comparison is equal to the length of the compare operand value and the comparison is performed the same as performed by the Compare Bytes Left Adjusted (CMPBLA) instruction.

If a set of bytes that matches the compare operand value is found, the binary value for the relative location of the leftmost base string character of the set of bytes is placed in the receiver operand.

If the receiver operand is a scalar, only the first occurrence of the compare operand is noted. If the receiver operand is an array, as many occurrences as there are elements in the array are noted.

If a mode change is encountered in the base string, the base string is again scanned until the mode of the characters being processed is the same as the initial mode of the compare operand value, and then the comparisons are resumed.

The operation continues until no more occurrences of the compare operand value can be noted in the receiver operand or until the number of bytes remaining to be scanned in the base string is less than the length of the compare operand value. When the second condition occurs, the receiver value is set to zero. If the receiver operand is an array, all its remaining elements are also set to zero.

If the escape code encountered result condition is specified (through a branch or indicator option), verifications are performed on the base string as it is scanned. Each byte of the base string is checked for a value less than hex 40. When a value less than hex 40 is encountered, it is then determined if it is a valid mode control character.

If a byte value of less than hex 40 is not a valid mode control character, it is considered to be an escape code. The binary value for the relative location of the character (simple or extended) being interrogated is placed in the receiver operand, and the appropriate action (indicator or branch) is performed according to the specification of the escape code encountered result condition. If the receiver operand is an array, the next array element after any elements set with locations or prior occurrences of the compare operand, is set with the location of the character containing the escape code and all the remaining array elements are set to zero.

If the escape encountered result condition is not specified, verifications of the character codes in the base string are not performed.

Resultant Conditions

  • Positive–The numeric value(s) of the receiver operand is positive.
  • Zero–The numeric value(s) of the receiver operand is zero. In the case where the receiver operand is an array, the resultant condition is zero if all elements are zero.
  • Escape code encountered–An escape character code value was encountered during the scanning of the base string.

Authorization Required

  • None

Lock Enforcement

  • None

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 0C Computation
    • 0C08 Length Conformance
  • 10 Damage Encountered
    • 1004 System Object Damage State
    • 1044 Partial System Object Damage
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2201 Object Not Found
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 2208 Object Compressed
    • 220B Object Not Available
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
  • 2C Program Execution
    • 2C04 Branch Target Invalid
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 32 Scalar Specification
    • 3201 Scalar Type Invalid
    • 3203 Scalar Value Invalid
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed