7.54.2 EXCHANGE Comments / Warnings

• Information is exchanged between functions in an "exchange list". The format of the exchange list is something like this:

       ||N|T|L|D|  V  ||N|T|L|D|   V    | ....... |N|T|L|D|     V    ||

       where:

N	is the name of a field
T	is the type of a field
L	is the length of a field
D	is the number of decimal positions
V	is the variable length value of the field

• Whenever a function is invoked, a CALL to another function completes, or a PROMPT_KEY handling function completes after being prompted from an input capable field, the exchange list is searched. If a field is found in the exchange list with the same name as a field used in the function it is "mapped" into the function. After the search has been completed the exchange list is cleared, regardless of whether or not any fields were found in it and mapped into the function.

• It can be seen that the exchange of information between functions is by name, not by position as with normal program parameters.

• There are two exchange lists: RDML and RDMLX. In general, RDML Fields are put on the RDML exchange list and RDMLX fields are put on the RDMLX exchange list. The exception is when the current Function or Component is RDMLX. In this case, if the field is RDML but the RDML exchange list is full, the RDML field will be put on the RDMLX exchange list. For more information see What Classifies a Field as RDMLX?

• An RDML field can be exchanged from an RDMLX function or component to an RDML Function and back again provided the RDML exchange list is not full. If the exchange list is full, the RDML function will not exchange the value as the RDML field value will be on the RDMLX exchange list.

• The "mapping" procedure mentioned above will automatically convert field types, lengths and decimal positions if the definition of the field in the exchange list is different to the definition of the field in the function. This does not mean that the conversion will always succeed. A 'best attempt' will be made to coerce the exchange value into the target field, and this may fail. The exchange list mechanism is designed for exchanging identical fields, and changing anything except the length is highly inadvisable.
  When the type of the target field is Alpha or String and the length of the target field is shorter than the exchanged value, then the value is truncated to the maximum length of the target field.
  When the type of the source field is Alpha or String, the Target Field is numeric and the length of the target field is shorter than the exchanged value, then the value is truncated to the left and right of the decimal point according to the length and decimals of the target field.
  When the target and source fields are of any other combination and the length is shorter than the exchanged value, the behavior is undefined. This undefined behavior may also change in the future in an undefined way. You should assume that a result obtained with this undefined behavior will change in a future release.

• It is possible to exchange a field with the ASQN attribute. Note that it is expected that the field is defined identically (including the ASQN attribute) in both sets of code.

• When a PROMPT_KEY processing function is automatically invoked from a DISPLAY, REQUEST or POP_UP command (ie: when the prompt function key is used), the following events occur:

• All fields nominated in EXCHANGE OPTION(*ALWAYS) commands are placed into the exchange list.

• The field being prompted is placed into the exchange list.

• If the field being prompted refers to another field for its definition, it is added to the exchange list again, but this time under the "refer" field name.

• Special fields PROMPT$FN and PROMPT$RN are placed onto the exchange list. These fields contain the name of the field that is being prompted and the name of its associated reference field (if any) respectively.

• As many of all the other fields used by the program as will fit into the space left in the exchange list are also added to the exchange list if the flag in the System Definition Data Area is set accordingly. If not, only the EXCHANGEd fields will be placed on the exchange list. Refer to The System Definition Data Areas in the LANSA for i User Guide.

• The prompt key processing function is invoked.

• If the prompt key processing function completes normally
  
  and
  
  the field being prompted was input capable on the screen at the time it was prompted, fields placed onto the exchange list by the prompting function are mapped back into the calling program's storage.

• Finally the exchange list is always cleared of all entries.

• The EXCHANGE command or the EXCHANGE parameter on the TRANSFER command are used to add a new entry into the EXCHANGE list.

• The net length of the RDML field exchange list cannot exceed 2000 characters at any time or the EXCHANGE or TRANSFER command that is attempting to add information to the list will end abnormally.

• The length of the RDMLX exchange list is only limited by available memory.

• When working with the function that receives the EXCHANGE information remember that the exchange of information takes place before the first RDML command in the function is executed (ie: during the function initialization procedures).

• If the EXCHANGE command or parameter does not appear to be working correctly it is probably because the first RDML command in the function sets the fields that have just been mapped from the exchange list to *DEFAULT or *NULL. This causes the EXCHANGE values to be overwritten.

• When retrieving fields (GET) from the exchange list in RPG / CL etc. use the same field length and number of decimal positions. If different lengths are used unpredictable results may occur.

• Shorter field lengths on GET:

• The decimal and / or integer parts may be truncated or trimmed.

• Characters may be trimmed.

• Longer field lengths on GET:

• Values will be padded with zeroes or blanks.

The introduction of the CALL PROCESS(*DIRECT) option has now made high volume calls possible. This was previously not recommended in LANSA. When implementing high volume calls to other functions, the size of the exchange list should be considered. In these circumstances, a large number of fields on the exchange list may cause a performance overhead. Investigate the option of passing data structures (CALL .... PASS_DS(#dddddd)) between functions instead of using the exchange option.