9 23 COMPOSER_RUN

9.23 COMPOSER_RUN

Þ Note: Built-In Function Rules.

COMPOSER_RUN runs a LANSA Composer Processing Sequence, in the LANSA Composer system identified by the server symbolic name argument, through the LANSA Composer Request Server. It can pass up to five named parameter values to the processing sequence.

COMPOSER_RUN assumes that the target system (the system identified by the LANSA Composer server symbolic name argument) 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.

 

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 at the end of these notes.

For further information, also refer to the COMPOSER_RUN activity and Appendix F - The LANSA Composer Request Server, in the LANSA Composer Guide.

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. The symbolic name is 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 Processing Sequence identifier Identifies the LANSA Composer processing sequence to run.  Specify either the external identifier (name) or the internal identifier. 1 32     3 A Opt Parameter name 1 (see Processing Sequence Parameters). 1 20     4 A Opt Parameter value 1 (see Processing Sequence Parameters). 1 200     5 A Opt Parameter name 2 (see Processing Sequence Parameters). 1 20     6 A Opt Parameter value 2 (see Processing Sequence Parameters). 1 200     7 A Opt Parameter name 3 (see Processing Sequence Parameters). 1 20     8 A Opt Parameter value 3 (see Processing Sequence Parameters). 1 200     9 A Opt Parameter name 4 (see Processing Sequence Parameters). 1 20     10 A Opt Parameter value 4 (see Processing Sequence Parameters). 1 200     11 A Opt Parameter name 5 (see Processing Sequence Parameters). 1 20     12 A Opt Parameter value 5 (see Processing Sequence Parameters). 1 200     13 A Opt Synchronous call? Specifies whether the Built-In Function waits for the processing sequence to complete. Defaults is 'Y', to wait. If any other value is specified, the Built-In Function posts the processing sequence run request and ends immediately. 1 1     14 N Opt Synchronous time-out (seconds). The number of seconds the Built-In Function waits for a synchronous processing sequence run to complete. If the timeout is exceeded, the Built-In Function ends with a result code of 'TM'. Defaultisf 30 seconds.  1 5 0 0 15 N Opt Request expires (seconds). IBM i servers only. Expiry does not apply to Winders servers. The number of seconds the request remains 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, the request server will consider that the request has expired and will not process it. Default is zero (0). This means that  no expiry applies to the request.  1 5 0 0

 

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Opt Result code. OK, if the Built-In Function completes successfully. TM, if the synchronous request timed out. Any other result code signifies that an error occurred. 2 2

 

Examples

This example uses a previously defined connection to a LANSA Composer system, with the symbolic name COMPOSER (see COMPOSER_USE), to call the processing sequence 'EXAMPLE_AATEST1'.

use builtin(COMPOSER_RUN) with_args('COMPOSER' 'EXAMPLE_AATEST1')

 

This example uses the same connection as above to call processing sequence 'EXAMPLE_AATEST2'. A single parameter: 'DIRECTORY' is passed with the value of '/'. The result code is received in variable #RESULT.

use builtin(COMPOSER_RUN) with_args('COMPOSER' 'EXAMPLE_AATEST2' 'DIRECTORY' '/') to_get(#RESULT)

 

This example uses the same connection as above to call processing sequence 'EXAMPLE_AATEST1', passing no parameters. The timeout value has been doubled from 30 seconds to 60 seconds.

Use Builtin(COMPOSER_RUN) With_Args('COMPOSER' 'EXAMPLE_AATEST1' *Default *Default *Default *Default *Default *Default *Default *Default *Default *Default *Default 60) to_get(#RESULT)

 

Processing Sequence Parameters

The Built-In Function arguments can be used to pass up to five parameter values to the processing sequence run. A pair of Built-In Function arguments is used for each processing sequence parameter:

• The first argument in each pair (Parameter name n) should specify the parameter name as defined in the processing sequence to be run.  If not specified, a default of '*NONE' is used which means that parameter pair is not used.

• The second argument in each pair (Parameter value n) should specify the value that is to be passed to the processing sequence for the corresponding parameter name.  The maximum value length that can be passed is 200.  If not specified, a default of '*NONE' is used.  However, you should specify the parameter value for each parameter name that is specified.

 

Further considerations for processing sequences executed through the LANSA Composer Request Server

This Built-In Function will run the processing sequence through the LANSA Composer request server.

When executed this way, the processing sequence runs 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)

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.