Absolute and relative positioning in external REXX functions

All File Manager external REXX functions that refer to positions within the input or output record can use absolute values to determine the byte location within the record. For example, the FLD function syntax is:

FLD(start_column,length,type)

where start_column can be an integer that refers to a specific byte in the input record.

However, some external REXX functions also allow positions to be specified as an offset value, relative to the “current position” within the input or output record. The current position is initialized as each record is processed but can be modified by these functions.

For input records, this allows you to perform tasks such as searching for a string in the input record and then testing or copying the contents of a field relative to the located string.

For output records, this allows you to easily append fields or constants at positions relative to the most recently updated output record field. For example, you could append a number of constants and fields, one after the other in the output record, without needing to keep track of the exact current starting position or manually updating the starting position with the length of added fields.

Note: You cannot use the REXX external functions to write data beyond the logical record limitations of the output data set. For example, when using a Fixed Block data set that has an LRECL of 80, you cannot write data to position 81 or beyond.

The following functions support relative positioning:

  • CHG_OUT
  • CHG_VAR
  • FINDNEXT
  • FINDPREV
  • FLD
  • FLD_CO
  • FLD_OUT
  • FLD_TM
  • FLD_TYPE
  • FLDI
  • FLDO
  • MOD_DATE
  • OVLY_OUT
  • OVLY_VAR
  • SETC
  • SETN
  • TESTC
  • TESTN
  • VAR_OUT
  • VAR_TM

To maintain the current position within the input and output records, these functions use two internal variables, INPOS and OUTPOS. These values have not been externalized to the REXX environment and can only be accessed or altered indirectly by using the functions listed above or SET_OLEN (which does not support relative position arguments but does alter the value of OUTPOS in some circumstances).

INPOS
For each new record that is processed, INPOS is set to 1. INTPOS is then modified (as a side effect) when the following functions are used:
FLD_CO
Whenever the FLD_CO function executes a successful search for a needle that is a string (type C or U), INPOS is then changed for the current input record. If a needle is found, INPOS is set to the first byte of the located needle. If no needle is found, INPOS is unchanged.
FLDI
Whenever the FLDI function (with contains operator) executes a successful search for a needle that is a string (type C or U), INPOS is then changed for the current input record. If a needle is found, INPOS is set to the first byte of the located needle. If no needle is found, INPOS is unchanged.

When you use the FLDI function with the VER operator and the verification fails, INPOS is set to the column of the character that failed the verification.

FINDNEXT
Whenever the FINDNEXT function executes a successful search for a needle, the INPOS is changed and set to the first byte of the located needle. If no needle is found, then INPOS is unchanged.
FINDPREV
Whenever the FINDPREV function executes a successful search for a needle, the INPOS is changed and set to the first byte of the located needle. If no needle is found, then INPOS is unchanged.
OUTPOS
For each new record that is processed, OUTPOS is set to 1 greater than the length of the current output record. The output record is initially the same length as the input record, unless templates have been used to reformat the record. OUTPOS is then modified (as a side effect) when the following functions are used:
CHG_OUT
CHG_OUT sets OUTPOS to one byte past the end of the last changed field in the output record.
FLD_OUT
FLD_OUT sets OUTPOS to one byte past the end of the field being overlaid in the output record.
OVLY_OUT
OVLY_OUT sets OUTPOS to one byte past the end of the field being overlaid in the output record.
SET_OLEN
SET_OLEN only changes OUTPOS if it truncates the output record so that the existing OUTPOS becomes greater than the reduced record length. In this case, OUTPOS is reset to the reduced length plus 1.
FLDO with contains operator
Whenever the FLDO function (with contains operator) executes a successful search for a needle that is a string (type C or U), OUTPOS is then changed for the current input record. If a needle is found, OUTPOS is set to the first byte of the located needle. If no needle is found, OUTPOS is unchanged.

When you use the FLDO function with the VER operator and the verification fails, OUTPOS is set to the column of the character that failed the verification.

VARPOS
For each new record that is processed, VARPOS is set to 1. VARPOS is then modified (as a side effect) when the following functions are used:
CHG_VAR
CHG_VAR sets VARPOS to one byte past the end of the last changed field in the variable.
OVLY_VAR
OVLY_VAR sets VARPOS to one byte past the end of the field being overlaid in the variable.
TESTC
Whenever the TESTC function (with contains operator) executes a successful search for a needle that is a string (type C or U), VARPOS is then changed for the current variable. If a needle is found, VARPOS is set to the first byte of the located needle. If no needle is found, VARPOS is unchanged.

When you use the TESTC function with the VER operator and the verification fails, VARPOS is set to the column of the character that failed the verification.