9 22 COMPOSER_CALLF

LANSA Technical

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:

Exchange Variables

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

LANSA for i

YES

Visual LANSA for Windows

YES

Visual LANSA for Linux

NO

 

 

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

LANSA Composer server symbolic name.

Specifies a symbolic name used to identify the connection details for the required LANSA Composer server system.  The name must have previously been specified in the COMPOSER_USE Built-In Function in the current session.

1

10

 

 

2

A

Req

Name of the LANSA process containing the function to be called.

IBM i: if *DIRECT is specified, the function must be defined with FUNCTION OPTIONS(*DIRECT).

Windows servers: the process name (not *DIRECT) must be specified.

1

10

 

 

3

A

Req

Name of the LANSA function to be called. Compulsory.

1

7

 

 

4

N

Opt

Number of exchange variables used. If not specified, a default of 0 (zero) is assumed.

1

5

0

0

5

A

Opt

Value of exchange variable EXCH01 (see Exchange Variables).

1

256

 

 

6

A

Opt

Value of exchange variable EXCH02 (see Exchange Variables).

1

256

 

 

7

A

Opt

Value of exchange variable EXCH03 (see Exchange Variables).

1

256

 

 

8

A

Opt

Value of exchange variable EXCH04 (see Exchange Variables).

1

256

 

 

9

A

Opt

Value of exchange variable EXCH05 (see Exchange Variables).

1

256

 

 

10

A

Opt

Value of exchange variable EXCH06 (see Exchange Variables).

1

256

 

 

11

A

Opt

Value of exchange variable EXCH07 (see Exchange Variables).

1

256

 

 

12

A

Opt

Synchronous call?

Specifies whether the Built-In Function waits for the function call to complete.

Default is 'Y', to wait.
If any other value is specified, the Built-In Function posts the function call request and ends immediately.

Note that this Built-In Function can only receive values returned from the called function (in the EXCH01 ... EXCH07 exchange variables) if this parameter is 'Y'.

1

1

 

 

13

N

Opt

Synchronous time-out (seconds).

The number of seconds the Built-In Function waits for a synchronous call to complete. If the timeout is exceeded, the Built-In Function ends with a result code of 'TM'.
Default is 30 seconds.

1

5

0

0

14

N

Opt

Request expires (seconds). IBM i only. Expiry does not apply to Windows servers.

On IBM i servers only, specify the number of seconds for the request to remain effective after it is posted to the request server. If more than the specified interval has elapsed before the request server begins to process the request, it will consider the request to have expired and will not process it.

Default is zero (0), 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.

1

5

0

0

 

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Opt

Result code.

If the Built-In Function completes successfully, the result code will contain 'OK'.  If the synchronous request timed out, the result code will contain 'TM'.  Any other result code signifies that an error occurred.

2

2

 

 

2

A

Opt

Value of exchange variable EXCH01 (see Exchange Variables).

1

256

 

 

3

A

Opt

Value of exchange variable EXCH02 (see Exchange Variables).

1

256

 

 

4

A

Opt

Value of exchange variable EXCH03 (see Exchange Variables).

1

256

 

 

5

A

Opt

Value of exchange variable EXCH04 (see Exchange Variables).

1

256

 

 

6

A

Opt

Value of exchange variable EXCH05 (see Exchange Variables).

1

256

 

 

7

A

Opt

Value of exchange variable EXCH06 (see Exchange Variables).

1

256

 

 

8

A

Opt

Value of exchange variable EXCH07 (see Exchange Variables).

1

256

 

 

 

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)

 

Exchange Variables

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 Appendix F (The LANSA Composer Request Server) in the LANSA Composer Guide.