9.22 COMPOSER_CALLF
Þ Note: Built-In Function Rules.
This Built-In Function can only be used with LANSA Composer greater than V3.0.
This Built-In Function assumes that the source system (the system in which the Built-In Function executes) is a LANSA Composer system, greater than Version 3, and contains the LANSA Composer Request Server software. This Built-In Function will fail if this is not the case.
COMPOSER_CALLF calls a named LANSA function, in the LANSA or LANSA Composer system identified by the server symbolic name argument, through the LANSA Composer Request Server.
It can pass and receive up to seven values via the LANSA exchange list. All exchange variables are passed as A(256) using exchange variable names EXCH01 - EXCH07.
This Built-In Function is intended for use in custom activity processors or other user-defined plug-in components of LANSA Composer to invoke processing logic contained in another LANSA application that may be installed in a different LANSA system and/or partition.
You must execute the 9.24 COMPOSER_USE Built-In Function to define the server connection details and a symbolic name representing them before executing this Built-In Function.
Further important information about this Built-In Function is provided later in these notes in:
LANSA programming considerations for the called function
Further considerations for functions calls executed through the LANSA Composer Request Server
You should also refer to LANSA Composer documentation of the CALL_FUNCTION activity and of the LANSA Composer Request Server for further information and considerations.
For use with
|
Arguments
|
Return Values
|
Examples
This example uses a previously defined connection to a LANSA system, with the symbolic name COMPOSER (see COMPOSER_USE), to do a simple function call. The process name is specified in the variable #PROCESS and the function name is specified in the variable #FUNCTION.
use builtin(COMPOSER_CALLF) with_args('COMPOSER' #PROCESS #FUNCTION)
This example connects to the same LANSA system as the above to call a function. The process name is specified in the variable #PROCESS and the function in the variable #FUNCTION. Two parameter values are passed: 'VALUE 1' and 'VALUE 2'. To receive these values through the exchange list, the called function must have fields EXCH01 and EXCH02 defined. In this case, the activity will not wait for the function to complete before proceeding as the call is asynchronous.
use builtin(COMPOSER_CALLF) with_args('COMPOSER' #PROCESS #FUNCTION 2 'VALUE 1' 'VALUE 2' *Default *Default *Default *Default *Default N) to_get(#RESULT)
This example connects to the same LANSA system as the above to call a function. The process name is specified in the variable #PROCESS and the function in the variable #FUNCTION. Two parameter values are passed and three are returned. In order to receive these variables via the exchange list, the called function must have the fields EXCH01 and EXCH02 defined. In addition, to return the variables the field EXCH03 must also be defined and the fields must be exchanged.
use builtin(COMPOSER_CALLF) with_args('COMPOSER' #PROCESS #FUNCTION 2 'VALUE 1' 'VALUE 2') to_get(#RESULT #VAR1 #VAR2 #VAR3)
The Built-In Function arguments and return values can be used to pass and receive up to seven values to/from the called function via the LANSA exchange list. The parameters are placed on and received from the exchange list as character variables of length 256 using the variable names EXCH01 ... EXCH07.
The called function must also use the variables names EXCH01 ... EXCH07 in order to receive the exchange values. If the called function needs to return values via these variables, it must execute the EXCHANGE command at the appropriate point.
The Built-In Function will place on and receive from the exchange list the number of parameters (up to seven) specified in the fourth argument. If used, they must be specified contiguously - for example, if you specify the value three, the Built-In Function will exchange the variables EXCH01, EXCH02 and EXCH03 and the values for the remaining exchange variable arguments will be ignored.
Note that the Built-In Function can only receive values returned from the called function when executed synchronously.
Refer to the description of the EXCHANGE command for further information on exchanging information via the exchange list.
LANSA programming considerations for the called function
- If *DIRECT is specified or assumed for the PROCESS parameter, the function must be defined with FUNCTION OPTIONS(*DIRECT)
- Called functions may be RDML or they may be fully RDMLX enabled.
- The function must define fields EXCH01 ... EXCH07 in order to receive values (via the exchange list) that are specified in the corresponding Built-In Function arguments.
- The function must use the EXCHANGE command with fields EXCH01 ... EXCH07 in order to return values (via the exchange list) to populate the corresponding Built-In Function return values.
- On IBM i servers only, position 487 of LANSA data area DC@A01 in the LANSA system containing the function to be called must be set to 'Y' before compiling or executing the function. If this condition is not met, the called function will not correctly receive or return the EXCH01 ... EXCH07 variable values.
Depending on all the requirements, these considerations may sometimes require developers to write functions specifically for the purpose. If this is necessary, the functions can often be simple "stub" functions that call existing functions in the LANSA application.
Further considerations for functions calls executed through the LANSA Composer Request Server
This Built-In Function will execute the function call through the LANSA Composer request server.
When executed this way, the function call executes in another process or job (the request server). The Built-In Function and the request server process or job communicate cooperatively to execute the request and return the results.
This is generally transparent to your application. However, some special considerations apply to this mode of execution, including considerations related to:
- User profiles, authorities and execution environment
- IBM i work management (jobs and subsystems)
- The way in which the called function must be compiled
For information about requests executed through the LANSA Composer request server, refer to (The LANSA Composer Request Server) in the .