OVLY_OUT

Figure 1. Syntax

1  OVLY_OUT ( overlay ,
1! 0
1 start
2  ,
1! length(literal)
1 length
3  ,
3? !Ctype
3  ,
1 pad
4  )
Note: Commas following the last specified argument can be omitted.

Can be used in FASTREXX procedures.

Overlays the output record 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, the following occurs:
  • Character overlays are truncated on the right without error. For example, OVLY_OUT('ABCD',1,2) overlays 'AB'.
  • Numeric overlay truncations are considered to be an error. For example, OVLY_OUT(500000,1,2,'B') fails because you can't fit the specified value into a 2-byte binary field.
On successful execution, also updates the value of OUTPOS to one byte past the end of the field overlaid in the output record.
Returns
A single blank.
overlay
An expression that resolves to a string, which is overlaid on that part of the output record 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 and/or literal strings.
If the first character of the literal is an ampersand and the literal that follows matches an existing character or 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, packed or zoned, then the variable value is converted to binary, packed or zoned number.
Note:
  1. Conversion errors may occur when converting a character variable to a numeric.
  2. If a variable name is not found, then the string is interpreted as a literal.
start
Position, in bytes, in the output record 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 output record, the field is appended to the end of the output record. If start is greater than the current length of the output record, the record is padded with the specified or defaulted pad character from the current record 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 INPOS
Must be specified as IPx or INx. Must resolve to a non-negative integer.
Relative to current OUTPOS
Can be specified as OPx or ONx, or as Px or Nx. Must resolve to a non-negative integer.
length
Length, in bytes, of target field in the output record. Defaults as shown here:
Character fields
Defaults 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 record 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
Defaults to the last packed length value determined from the input record by a preceding function. For example, 
if FLD(1,P) = 2 then
OVLY_OUT('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 literal to be written to the output record.
B
Binary. The literal string must represent a positive or negative integer, and is stored in the output field as a signed two's-complement format binary number, right-justified in the target field. The length must be 2, 4, or 8, and cannot be omitted.
C
Character. This is the default.
P
Packed decimal. The literal string must represent a positive or negative integer, and is stored right-justified in the target field as a signed packed decimal number using the preferred positive ('c'x) and negative ('d'x) sign indicators. The length must be between 1 and 16.
Z
Zoned decimal (COBOL external decimal with non-character trailing sign). The literal string must represent a positive or negative integer, and is stored in the output field as a signed zoned decimal number. The length must be between 1 and 31.
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."

See FLD_OUT for a function to overlay the output record with a field from the input record.

Example 1

Set columns one and two of the output record to asterisks.

  OVLY_OUT('**',1,2)

Example 2

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

  OVLY_OUT(2,0,2,P)

Example 3

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

  If FLD_CO(1,,C,'AABB') Then
   OVLY_OUT('CC',IP2,2)