OVLY_VAR

Figure 1. Syntax

1  OVLY_VAR ( name  , overlay  ,
2.1! 0
2.1 start  , length  ,? ! C type  ,?  pad  )

(Can be used in FASTREXX procedures.)

Note: Commas following the last specified argument can be omitted.
Overlays the named character variable with a string. If the length of the target field exceeds the length of the literal, the target field is padded to the specified length using the pad character. If the length of the target field is less than the length of the literal:
  • Character overlays are truncated on the right without error. For example, OVLY_VAR(MYVAR,'ABCD',1,2) overlays 'AB'.
  • Numeric overlay truncations are considered to be an error. For example, OVLY_VAR(MYVAR,500000,1,2,'B') fails because you cannot fit the specified value into a 2-byte binary field.

On successful execution, also updates the value of current variable position to one byte past the end of the field overlaid in the variable.

Returns
A single blank.
name
1–256 character variable identifier. Variable name matching is not case sensitive. If the name is not found, a severe error occurs and the procedure is terminated. Cannot be a system character variable or a system numeric variable. See Using FASTREXX variables.
overlay
An expression that resolves to a string, which is overlaid on that part of the variable specified by start and length. To be eligible for FASTREXX processing, this must be a literal string, a symbol, or a blank-delimited sequence of symbols or literal strings. If the first character of the literal is an ampersand and the literal that follows matches an existing character, numeric variable, or tally literal (matching not case-sensitive), then the variable value is substituted according to the type. For example, if the type is character and a numeric or tally value are referenced, then the literal is the numeric value in display format with no leading zeros. If the type is binary then the variable value is converted to a binary number.
Note: Conversion errors may occur.
start
Position, in bytes, in the variable at which to start overlaying the string. If you omit start, specify zero, or specify a value one greater than the length of the current variable, the field is appended to the end of the variable. If start is greater than the current length of the variable, the record is padded with the specified or defaulted pad character from the current variable length to the specified start position. Can be specified as:
Absolute position
Must be a non-negative integer that is less than or equal to the maximum length of the output data set. Default value is 0.
Relative to current variable position
Must be specified as IPx or Inx, OPx or ONx, or as Px or Nx. Must resolve to a non-negative integer.
length
Length, in bytes, of target field in the variable. Defaults:
Character fields
To the length of the literal. A value of 0 indicates that the target field length is the greater of the source (literal) length and the remaining variable length. In particular, if 0 is specified for both start and length, then the length of the literal is used as the target length.
Packed decimal
To the last packed length value determined from the input record by a preceding function. For example: 
if FLD(1,P) = 2 then
OVLY_VAR(MYVAR,'5',1,,P)
Uses the length determined by the FLD function to default the packed decimal length. If no previous packed decimal length was calculated a length error occurs and the procedure is terminated.
type
The data type of the field. Valid values are:
B
Binary. FLD_CO interprets binary fields as being signed.
C
Character. This is the default. The comparison is case sensitive.
P
Packed decimal.
U
Interprets the field as Character, but converts it to uppercase before comparing it with needle.
Z
Zoned decimal. Interprets all of the COBOL external decimal variants as numeric data.
pad
Pad character. Defaults to the pad character set on the File Manager System Processing Options panel. If the current pad setting is OFF, the default pad character is a blank. For numeric types such as B, P, or Z, the pad character is not used when pre-fill characters are required to right-justify a numeric field. The pre-fill characters are always leading zeros, as required by the field type.

Example 1

Set columns one and two of the variable to asterisks.

    OVLY_VAR(MYVAR,'**',1,2)

Example 2

Append the two-byte packed decimal value 2 to the end of the variable.

    OVLY_VAR(MYVAR,2,0,2,P)

Example 3

Search the variable for a literal and then overlay the last two bytes of that literal with a new literal in the variable.

    If TESTC(MYVAR,'CU','AABB') Then
     OVLY_VAR(MYVAR,'CC',IP2,2)