The REFER Option

In PL/I, you can describe self-defined length variable in string lengths and array boundaries with the REFER option.

The syntax is:

expression REFER (member-variable)

where:

  • expression is the expression that defines the actual length of a string or a value of an array bound.
  • member-variable is a field in the structure before the REFER option. This field, which contains the value of the expression, can be used by the PL/I program to access the actual string length or an array boundary.
Note: In PL/I, expression is not limited to numeric constants and can be any expression that is evaluated by the PL/I program if the structure is allocated. The Plug-in does not impose any additional requirements and allows all valid expressions.

In this example, TXT_FIELD is a field of 10 characters and LEN_VAR contains 10: 

DECLARE 1 ROOT,
          2 LEN_VAR FIXED BIN(31),
          2 TXT_FLD CHAR(10 REFER(LEN_VAR));

In this example, ARRAY is an array of 10 items and LEN_VAR is set to 10: 

DECLARE 1 ROOT,
          2 LEN_VAR FIXED BIN(31),
          2 ARRAY(10 REFER(LEN_VAR)) FIXED BIN(15);

In this example, ARRAY is an array of eight items (ARRAY(3) through ARRAY(10)); LEN_VAR1 contains the value 3; and LEN_VAR2 contains the value 10: 

DECLARE 1 ROOT,
          2 LEN_VAR1 FIXED BIN(31),
          2 LEN_VAR2 FIXED BIN(31),
          2 ARRAY(3 REFER(LEN_VAR1) : 10 REFER(LEN_VAR2)) FIXED
            BIN(15);

The Plug-in processes the REFER option as follows:

  • During parsing:
    • For strings, the Plug-in calculates the number of characters according to the member-variable value in the binary data.
    • For arrays, the Plug-in calculates the number of items according to the values of REFER member-variable specified in array bounds in the binary data.
    • member-variable, which is in the XML output of the parse activity, can be used in mappings along with the variable-length field itself.
  • During rendering—
    • The Render activity expects member-variable to be set to a value that is consistent with the receiving PL/I program.
Warning: Be sure not to exceed the actual allocation size of the element that receives data in the PL/I program.
  • For strings, the Plug-in calculates the number of characters according to the member-variable value supplied through mapping. If the actual value of the string is shorter, member-variable stipulates that the string is padded.
  • For arrays, the Plug-in calculates the number of items according to the values of the member variables specified in array bounds and supplied through mapping. If the actual number of items in the input XML is smaller, the Plug-in adds empty items. If INITIAL is specified, the Plug-in initializes those items accordingly.
Note: A difference exists in how errors are processed in strings and arrays during rendering. The following rules apply:
  • If a string value supplied through mapping is longer than the calculated length, the Plug-in considers that a runtime error and throws SerializationException.
  • The number of array items in the mapping can exceed the number that is calculated on the basis of the member variables. In that case, the Plug-in renders only the REFER-based number of items and ignores the rest.