7.54.3 EXCHANGE Accessing the Exchange List from RPG/COBOL

A flag field in the system definition data area DC@A01 must be set to indicate that the exchange capability is required. Refer to The System Definition Data Area DC@A01 in the LANSA for i User Guide.

Normally the exchange list is only used to communicate information between LANSA processes and functions, however, a facility does exist to allow RPG/COBOL/etc programs that call LANSA applications or are called by LANSA applications to access the exchange list.

This facility is actually a program called M@EXCHL that is shipped with LANSA. By placing calls to M@EXCHL, RPG/COBOL/etc programs are able to place things onto the exchange list and get things off the exchange list, just like LANSA processes and functions do.

You cannot use the M@EXCHL facility with RDMLX functions because X_RUN is not aware of external exchange lists. You can only CALL a LANSA RDML function and not RDMLX if the exchange list is needed. That is,

RPG calling LANSA - this must be an RDML function
LANSA calling RPG - this could be either an RDML or RDMLX function. To do this, you need to create a simple RDML function for the MC@EXCHL values and then they can be exchanged to the RDMLX function. That is, call this RDMLX function from RDML to exchange the values.

Following are two different scenarios that demonstrate how to use M@EXCHL.

Scenario 1 - RPG/COBOL/etc calling a LANSA application

The RPG/COBOL/etc program would have logic like this:

CALL M@EXCHL to "CLR" any rubbish left on the list.
CALL M@EXCHL to "PUT" information into the list.
CALL LANSA to run the LANSA function. This must be an RDML function, not an RDMLX function (called via LANSA X_RUN).
CALL M@EXCHL to "GET" information from the list.

The actual logic flow of these operations works like this:

M@EXCHL clears any rubbish on the user list.
M@EXCHL places requested details into the user list.
As LANSA is invoked, it appends the user list to the current exchange list and clears the user list. The function then runs under the normal exchange list rules. Just before control is returned to the RPG/COBOL/etc application, the exchange list is mapped into the user list and the exchange list is cleared.
M@EXCHL searches the user list and returns information.

Scenario 2 - A LANSA application calling RPG/COBOL/etc

A LANSA function places a call to an RPG/COBOL/etc program via the RDML CALL command. Since this program wishes to access the exchange list, the PGM_EXCH(*YES) parameter is used. This may be an RDML or RDMLX function, but only RDML fields can be exchanged. Refer to the CALL command for further information.
The RPG/COBOL/etc program receives control.
It calls M@EXCHL to "GET" details from the list.
It calls M@EXCHL to "CLR" the list.
It does whatever processing is required.
Then it calls M@EXCHL to "PUT" details back onto the list.
Control returns to the LANSA function, and details from list appear and are processed just like an exchange via the exchange list with another LANSA function.

The actual logic flow of these operations works like this:

Any OPTION(*ALWAYS) fields are added to the exchange list, and then the exchange list is mapped into the user list, then the exchange list is cleared, and the CALL to the RPG/COBOL/etc application is placed.
The RPG/COBOL/etc program receives control.
M@EXCHL searches the user list and returns information.
M@EXCHL clears the user list.
As above.
M@EXCHL places requested details into the user list.
Control returns to the LANSA function, which replaces the exchange list with the user list, and clears the user list. Next the exchange list is searched for matches with fields in the function and, where required, mapping occurs. Finally, the exchange list is cleared.

Parameters required by M@EXCHL

M@EXCHL has 1 parameter that must be specified on a CALL, and up to 10 "pairs" of parameters that are used to define and contain information that is to be placed on or received from the exchange list. This means a minimum of 1 and a maximum of 21 parameters can be passed to M@EXCHL on any call.

In detail these parameters look like this:

Parm Number	Type	Min Len	Max Len	Comments
01	Alpha	3	3	PUT = Put data onto list GET = Get data from list CLR = Clear list
02,04, 06,08, 10,12, 14,16, 18,20	Alpha	15	15	Format : nnnnnnnnnntllld where: nnnnnnnnnn is the field name t is the field type (A/P/S) lll is the field length or the total digits d is the number of decimals
03,05, 07,09, 11,13, 15,17, 19,21	Any	1	256	This is the field's value.

Examples of calling M@EXCHL

Example 1: From a CL (control language) program place the value of field COMPNO (company number) and ACCTYP (account type) onto the exchange list. Run a LANSA function and get back a field called TOTAMOUNT from the exchange list.

   DCL &COMPNO    *DEC (3 0)
   DCL &ACCTYP    *CHAR 5
   DCL &TOTAMOUNT *DEC (13 2)
   CALL M@EXCHL ('CLR')
   CALL M@EXCHL ('PUT' 'COMPNO   P0030' &COMPNO  ACCTYP   A0050' &ACCTYP )
   LANSA RUN ... etc .....
   CALL M@EXCHL ('GET' 'TOTAMOUNT P0132' &TOTAMOUNT)

Example 2: Do the same thing from RPG.

   E                    ATR     1   3 15
   C*
   C* CLEAR THE LIST
   C*
   C                     CALL 'M@EXCHL'
   C                     PARM 'CLR'     A@EXCH  3
   C*
   C* PUT TO THE LIST
   C*
   C                     CALL 'M@EXCHL'
   C                     PARM 'PUT'     A@EXCH
   C                     PARM           ATR,01
   C                     PARM           COMPNO  30
   C                     PARM           ATR,02
   C                     PARM           ACCTYP   5
   C*
   C* INVOKE THE FUNCTION
   C*
   C                     CALL 'LANSA'
   C           ---------- ETC -----------
   C           ---------- ETC -----------
   C           ---------- ETC -----------
   C*
   C* GET FROM THE LIST
   C*
   C* NOTE: The field is named "TOTAMOUNT" in the exchange
   C*        list, but is actually returned into a field
   C*        called TOTAMT.
   C                     CALL 'M@EXCHL'
   C                     PARM 'GET'     A@EXCH
   C                     PARM           ATR,03
   C                     PARM           TOTAMT 132
   C*
   C                     MOVE '1'       *INLR
   C                     RETRN
   **
   COMPNO    P0030
   ACCTYP    A0050
   TOTAMOUNT P0132

Example 3: Write a CL program that is to receive the name of a file and library from the exchange list, copy the file to tape and place a return code back onto the exchange list.

   COPYTAPE: PGM
   DCL &FILE      *CHAR 10
   DCL &LIBRARY   *CHAR 10
   DCL &RETCODE   *CHAR  1
   CALL M@EXCHL ('GET' 'FILE      A0100' &FILE    'LIBRARY   A0100' &LIBRARY )
   CALL M@EXCHL ('CLR')
   CHGVAR &RETCODE 'Y'
   CPYTOTAP  ... etc .....
   MONMSG (CPF0000 MCH0000) EXEC(CHGVAR &RETCODE 'N')
   CALL M@EXCHL ('PUT' 'RETCODE   A0010' &RETCODE)
   ENDPGM

Example 4: Write the RDML code required to display a screen panel, input the file and library name, call the CL program in example 3 and act upon the return code.

   DEFINE #FILE *CHAR 10
   DEFINE #LIBRARY *CHAR 10
   DEFINE #RETCODE *CHAR 1
   REQUEST  FIELDS(#FILE #LIBRARY)
   EXCHANGE FIELDS(#FILE #LIBRARY)
   CALL     PGM(COPYTAPE) PGM_EXCH(*YES)
   IF       ('#RETCODE *NE Y')
   MESSAGE  MSGTXT('Copy to tape failed')
   ENDIF