9.24 COMPOSER_USE

Note: Built-In Function Rules     Usage Options

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.

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)