9.24 COMPOSER_USE
Þ Note: Built-In Function Rules.
This Built-In Function associates a symbolic name with the details necessary for COMPOSER_CALLF or COMPOSER_RUN to connect to a nominated LANSA or LANSA Composer server system.
The association persists only for the duration of the current session or until COMPOSER_USE is used again to specify different LANSA Composer or LANSA Systems with the associated symbolic name.
The Result code of OK must be received before the LANSA Composer server symbolic name is used with the COMPOSER_RUN or COMPOSER_CALLF Built-In Functions.
Note that no connection is actually attempted until either the COMPOSER_RUN or COMPOSER_CALLF Built-In Functions is executed. Thus, connection errors arising from incorrect values used in this Built-In Function will not be evident until the connection is attempted by either the COMPOSER_RUN or COMPOSER_CALLF Built-In Functions.
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 that will be used to identify the connection details specified. If successful, the symbolic name may be specified in subsequent invocations of the COMPOSER_RUN and/or COMPOSER_CALLF Built-In Functions in the current session.
|
1
|
10
|
|
|
|
2
|
A
|
Opt
|
Partition name.
Specifies the name of the LANSA partition in the specified LANSA system in which LANSA Composer is installed.
'LIC' is the default. This partition name is used in a standard LANSA Composer installation.
|
3
|
3
|
|
|
|
Arguments - IBM i server only
These arguments are ignored when running on a Windows server.
For a Windows Windows server, specify *DEFAULT for these arguments.
|
3
|
A
|
Opt
|
LANSA program library name. (IBM i server only)
Specifies the name of the LANSA program library for the LANSA system in which LANSA Composer is installed. In a default LANSA Composer installation, the library name would be LICPGMLIB. This is the default value used if this argument is not specified.
|
1
|
10
|
|
|
|
4
|
A
|
Opt
|
Reserved for future use. Must be blank.
|
1
|
256
|
|
|
|
5
|
A
|
Opt
|
Reserved for future use. Must be blank.
|
1
|
256
|
|
|
|
Arguments - Windows server only
These arguments are ignored when running on an IBM i server system.
Note that although this Built-In Function allows for the long user names and passwords to be specified, the current version (3.0) of LANSA Composer does not yet support the use long user names and passwords.
|
6
|
A
|
Opt
|
LANSA system path. (Windows server only)
Specifies the path to the X_WIN95 folder in the LANSA system in which LANSA Composer is installed:
Default is C:\Program Files\LANSA Composer Server\X_WIN95
This would be the path in a default LANSA Composer installation.
|
1
|
256
|
|
|
|
7
|
A
|
Opt
|
User name. (Windows server only)
Specifies the user name used to connect to the LANSA system in which LANSA Composer is installed.
(This value corresponds to the X_RUN parameter USER=.)
|
1
|
256
|
|
|
|
8
|
A
|
Opt
|
Password. (Windows server only)
Specifies the password used to connect to the LANSA system in which LANSA Composer is installed.
(This value corresponds to the X_RUN parameter PSPW=.)
|
1
|
256
|
|
|
|
9
|
A
|
Opt
|
Data Source (Windows server only)
Identifies the user database used with the LANSA system in which LANSA Composer is installed.
(This value corresponds to the X_RUN parameter DBID=.)
|
1
|
32
|
|
|
|
10
|
A
|
Opt
|
Database type. (Windows server only)
Specifies the type of database specified in the previous argument.
(This value corresponds to the X_RUN parameter DBUT=.)
|
1
|
20
|
|
|
|
11
|
A
|
Opt
|
Database user. (Windows server only)
Specifies the user name for the database login, if required.
(This value corresponds to the X_RUN parameter DBUS=.)
It is 256 bytes long on Windows.
|
1
|
256
|
|
|
|
12
|
A
|
Opt
|
Database password. (Windows server only)
Specifies the password for the database login, if required.
(This value corresponds to the X_RUN parameter DBPW=.)
It is 256 byte long Windows.
|
1
|
256
|
|
|
|
13
|
A
|
Opt
|
LANSA system overrides. (Windows server only)
This argument may be used to specify a string of further X_RUN parameter names and values required to connect to the LANSA system in which LANSA Composer is installed.
For more information, refer to The X_RUN Command.
|
1
|
128
|
|
|
|
14
|
A
|
Opt
|
LANSA Composer Request Server logging enabled? (Windows server only)
'Y' if logging is enabled.
|
1
|
1
|
|
|
|
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'. Any other result code signifies that an error occurred.
|
2
|
2
|
|
|
|
Examples
This example defines a connection with the symbolic name, COMPOSER, to the LANSA or LANSA Composer system in partition LIC (the default value) in the default LANSA Composer installed location on either IBM i or Windows servers:
use builtin(COMPOSER_USE) with_args('COMPOSER')
This example defines a connection with the symbolic name ISERVER1 to partition 'PRD' in a LANSA or LANSA Composer system on the IBM i server that is executing the Built-In Function. The program library name for the target system is specified in variable #PGMLIB. The result code is received in variable #RESULT:
use builtin(COMPOSER_USE) with_args('ISERVER1' 'PRD' #PGMLIB) to_get(#RESULT)
This example defines a connection with the symbolic name WINSERVER1 to partition 'PRD' in a LANSA or LANSA Composer system on the Windows server that is executing the Built-In Function. The path to the target system is specified n variable #XWIN95. Literal values have been used to specify the remaining connection details - for example, the user name and password is specified as 'PCXUSER', and the target system uses a Sybase SQL anywhere database with name LX_LANSA. LANSA Composer request server logging is enabled. The result code is received in variable #RESULT:
use builtin(COMPOSER_USE) with_args('WINSERVER1' 'PRD' *default *default *default #XWIN95 'PCXUSER' 'PCXUSER' 'LX_LANSA' 'SQLANYWHERE' 'DBA' 'SQL' *default 'Y') to_get(#RESULT)