TESTC

Figure 1. Syntax

1  TESTC ( name ,?  start , length , type ,
1! 'EQ"
1 operator
2?  + , value
2  , duplication
2?   VER
2  )

Can be used in FASTREXX condition expressions.

Note:
  1. The operator (operator) and non-numeric values should all be enclosed in quotation marks to avoid syntax errors.
  2. The start length and type parameters are optional to provide the capability to examine part of the variable. The second operand can be the operator. See examples provided.
  3. If you specify a value for length that would cause the record length to be exceeded, a false result is returned.
  4. If you specify a numeric type (types B, P, Z), and the specified field contains invalid data for that type, then the function returns a false result. Numeric data is always returned in integer form; that is, the function does not perform scaling of numeric data.
name
1–256 character variable identifier. Variable name matching is not case sensitive. If the name is not found, a variable is created with a length of 1 and value X'00'.
start
Position in bytes in the variable at which to start reading the field value. Can be specified as:
Absolute position
Must be a positive integer. If start is greater than the current length of the input record, the function has no effect.
Relative start position
Can be specified as IPx or INx, or as Px or Nx, OPx, or ONx. When testing a variable, the current variable position is the basis of calculation. The current variable position is changed by the TESTC function with a contains type operator. If this resolves to a value of less than or equal to zero, the function produces a false result. If this resolves to a value that is greater than the current length of the variable, the function produces a false result.
length
The length of the field in bytes.
  • For binary fields, you must specify the length. It can be 2, 4, or 8.
  • For character fields, if you omit the length, the length is defaulted:
    • For contains type operators, to the rest of the variable.
    • When all values are variable substitutions, to the rest of the variable.
    • Otherwise, the maximum literal value length is be used.
  • For packed decimal fields, if you specify the length, it must be in the range 1–16. If you omit the length, the function attempts to determine the packed field length from the variable value and returns only that field.
  • For zoned decimal fields, if you specify the length, it must be in the range 1–31 or, if the field contains a separate sign character, in the range 1–32. If you omit the length, the function returns the remainder of the variable. If this exceeds 32, then the function returns a false result.
type
The data type of the field. Valid values are:
B
Binary. The function interprets binary fields as being signed.
C
Character. This is the default.
P
Packed decimal.
U
Interprets the field as character, but converts it to uppercase before returning the string.
Z
Zoned decimal. Interprets all of the COBOL external decimal variants as numeric data.
operator
The default is EQ or =. This function supports all the operators described for dynamic template and criteria edit. For details about the operators supported and their description, see:
value
The value or values entered must be valid in the context of the operator and the field which is being referenced. For example, only certain operators like CO (contains) allow multiple values. Numeric values should be entered when testing numeric fields, and so on.
  • Specifying hexadecimal strings. A hexadecimal string must be in the form 'hhhhhh'x. The value enclosed in quotation marks must be an even number of characters and contain valid hexadecimal characters (0–9, A–F).
  • Specifying binary strings. A binary string must be in the form 'nnnnnn'b. The value enclosed in quotation marks must be a combination of "0"s and "1"s.
  • Specifying character strings. For non-numeric types, the value should be enclosed in quotation marks.
  • Specify a variable by specifying &variable_name. A variable is substituted for the value if a matching character, numeric, or tally variable can be located. If a matching variable cannot be found, the string is treated as a literal value. If a numeric comparison is being performed, a character variable is converted to a number - if the conversion fails, the function returns a false result. If a numeric or tally variable is referenced in a character comparison, then the value is the number converted to its display form with leading zeros removed.
duplication
Specify an integer n to duplicate the literal value n times.
Note: This can only be used for operators that support a single value (for example, Not contains) and where the value is a literal constant and not a substitute variable.
VER
Verify the field is composed only of characters specified in the value column.

Example 1

SET variable named TESTREC to current input record. Check the variable and process only those records that contain values of 'Smith' or 'Jones'.

Note: In this case, use the operator CU so the contains processing is not case-sensitive. The start, length, and type parameters have been omitted.
SETC('TESTREC','&ZINREC')

  if TESTC(TESTREC,'CU','Smith','Jones') then
     return
   else
     return 'DROP'

Example 2

Process all records with a salary greater than 75000, where salary is a packed-decimal value found at start position 28.

Note: In this case, allow File Manager to calculate the packed-decimal field length.
SETC('TESTREC','&ZINREC')
  if TESTC(TESREC,28,,P,'>',75000) then
     return
   else
     return 'DROP'