CALL_FUNCTION
This activity calls a named LANSA function. The LANSA function may be contained in another LANSA configuration on the same or a different (*) server. The activity can pass and receive up to seven values via the LANSA exchange list. All parameters are passed as A(256).
(* Note a LANSA Composer Remote Request Server license is required for the remote server in order to call a LANSA function on a different server system.)
It is the user's responsibility:
- To ensure that the function is available in the necessary LANSA system and partition
- To ensure that the executing job (*) has the necessary authorities to make the call
- To ensure that the called function is appropriate for the purpose.
(*) Depending on the request, the executing job will usually be a job submitted by the LANSA Composer Request Server.
Further important information about the CALL_FUNCTION activity is provided under the following headings later in these notes:
LANSA programming considerations for the called function
Calling a function in the same system and partition as LANSA Composer
Calling a function in another LANSA system or partition
Function calls executed through the LANSA Composer Request Server
You should also refer to:
2.3.10 LANSA System Configuration
Appendix F. The LANSA Composer Request Server
INPUT Parameters:
LANSACONFIG : Optional
This parameter specifies the name of a LANSA system configuration that identifies the LANSA system and partition containing the function to be called and the connection details, if required, to connect to the server system on which the LANSA system resides. The partition containing the function to be called must be a multilingual partition.
PROCESS : Optional
This parameter specifies the name of the process containing the function to call. If not specified, the activity assumes *DIRECT. If *DIRECT is specified or assumed, the function must be defined with FUNCTION OPTIONS(*DIRECT). On Windows servers the process name (not *DIRECT) must be specified for requests that will be processed through the request server.
FUNCTION : Required
This parameter specifies the name of the function to call. The function name must always be specified.
SYNCHRONOUS : Optional
This parameter specifies whether the activity waits for the function call to complete. It defaults to YES, which means the activity does wait. If any other value is specified, the activity posts the function call request and completes immediately. Note that the activity can only receive values returned from the called function (in the EXCH01 ... EXCH07 input/output parameters) if this parameter is YES.
SYNCHTIMEOUT : Optional
This parameter specifies the number of seconds the activity waits for a synchronous call to complete when executed through the request server. If not specified, a default of 30 seconds is used. If the timeout is exceeded, the activity ends with an error. Note the timeout ONLY applies to requests executed through the request server.
EXPIRES : Optional
On IBM i servers only, this parameter specifies the number of seconds, after it is posted to the request server, that the request remains effective. If more than the specified interval has elapsed before the request server begins to process the request, the request server will consider the request to have expired and will not process it. If not specified, a default of zero (0) is used, which means that no expiry applies to the request. Note that the expiry ONLY applies to requests executed through the request server for IBM i servers. No expiry applies when running on Windows servers.
LANSASYS : Optional (deprecated)
This parameter specifies the name of the program library for the LANSA system containing the function to call. If not specified, the activity assumes the same LANSA system as is executing LANSA Composer. This parameter is only used on IBM i servers and is provided for backwards compatibility. On Windows servers (and for new solutions on IBM i servers) you should specify a LANSA system configuration name in the LANSACONFIG parameter. If a LANSA system configuration is named in the LANSACONFIG parameter, the value of this parameter is not used.
PARTITION : Optional (deprecated)
This parameter specifies the name of the partition containing the function to call. If not specified, the activity assumes the same partition in which LANSA Composer is executing. This parameter is only used on IBM i servers and is provided for backwards compatibility. On Windows servers (and for new solutions on IBM i servers) you should specify a LANSA system configuration name in the LANSACONFIG parameter. If a LANSA system configuration is named in the LANSACONFIG parameter, the value of this parameter is not used. The partition containing the function to be called must be a multilingual partition.
INPUT and OUTPUT Parameters:
EXCH01EXCH02
EXCH03
EXCH04
EXCH05
EXCH06
EXCH07 : Optional
These parameters 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 parameter values. If the called function needs to return values via these variables, it must execute the EXCHANGE command at the appropriate point.
The activity will place on and receive from the exchange list the number of parameters (up to seven) for which you specify values or alternate variable names. If used, they must be specified contiguously (the activity stops looking after the first parameter whose value is not specified).
Note that the activity can only receive values returned from the called function when executed synchronously - see the description of the SYNCHRONOUS parameter.
Refer to the description of the EXCHANGE RDML command in the LANSA product documentation for further information on exchanging information via the exchange list.
LANSA programming considerations for the called function
The following LANSA programming considerations apply to the way in which the called function must be defined:
- 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 partition containing the function to be called must be a multi-lingual partition.
- The function must define fields EXCH01 ... EXCH07 in order to receive values (via the exchange list) that are specified in the corresponding CALL_FUNCTION activity parameters.
- The function must use the EXCHANGE command with fields EXCH01 ... EXCH07 in order to return values (via the exchange list) for variables that are specified in the corresponding CALL_FUNCTION activity parameters.
- On IBM i servers only, if the CALL_FUNCTION activity will execute via the LANSA Composer request server, position 487 of LANSA data area DC@A01 must be set to 'Y' before compiling the function. If this condition is not met, the called function will not correctly receive or return the EXCH01 ... EXCH07 variable values.
Refer to LANSA documentation for more information on LANSA features referred to above.
Depending on all the requirements, these considerations may sometimes necessitate that your programming staff write functions specifically for the purpose. However, even if this is necessary, the functions can frequently be simple "stub" functions that call other existing functions in the LANSA application.
Calling a function in the same system and partition as LANSA Composer
If you want to call a function that is available in the same LANSA system and partition as LANSA Composer, you only need to specify the function name in the FUNCTION parameter, and any values to be exchanged with the function in the EXCH01 ... EXCH07 parameters. You do not need to specify values for the LANSACONFIG, PROCESS or SYNCHRONOUS parameters (nor the deprecated LANSASYS and PARTITION parameters).
Providing (1) *DIRECT is specified or assumed for the PROCESS parameter, and (2) YES is specified or assumed for the SYNCHRONOUS parameter, the function call will be performed directly from the activity processor, in the same job and context. When the CALL_FUNCTION activity runs in this mode, the value of the SYNCHTIMEOUT parameter is ignored.
Functions called in this way must be defined with FUNCTION OPTIONS(*DIRECT).
Calling a function in another LANSA system or partition
You can call a function that is available in a different LANSA system and/or partition than LANSA Composer on the same or a different server system. To do this, you should:
a)create a LANSA system configuration in LANSA Composer that identifies the LANSA system and partition you wish to use, and
b)specify the LANSA system configuration name on the LANSACONFIG parameter.
Such requests offer greater flexibility, including the ability to call the required function through a specified process (instead of with *DIRECT) and synchronously or asynchronously processing the request. These types of function calls will execute through the LANSA Composer Request Server, and some special considerations apply.
Function calls executed through the LANSA Composer Request Server
The CALL_FUNCTION activity will seek to execute the function call through the LANSA Composer request server if any of the following are true:
- You specify a LANSA system configuration name using the LANSACONFIG parameter
(OR on IBM i servers only, the values specified for the LANSASYS and PARTITION parameters identify a LANSA system and/or partition that is not the same as for the LANSA Composer system.)
- You specify a process name (other than *DIRECT) in the PROCESS parameter.
- You specify a value other than YES for the SYNCHRONOUS parameter.
When executed this way, the function call executes in another process or job (the request server). LANSA Composer and the request server process or job communicate cooperatively to execute the request and return the results.
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
You should refer to Appendix F (The LANSA Composer Request Server) in the LANSA Composer guide for detailed information about considerations for requests executed through the LANSA Composer Request Server.