TP invocation parameters on a server

This section describes the parameters required by the Motif administration program or the command-line administration program when configuring an invokable TP on a server. For information about configuring an invokable TP on a client, see Configuring an invokable TP from the command line.

The following parameters are required for a TP that can be invoked on the local node:

TP name

A TP name in one of the following forms:

Application TP

If the TP is a user application, supply the name as normal characters (up to 64 characters in length).

Service TP

If the TP is an SNA service transaction program, enter the name in hexadecimal (up to eight hexadecimal digits, representing 4 bytes).

You can define multiple APPC invokable TPs that have the same TP name, provided each TP definition specifies a different LU alias. You cannot do this for CPI-C invokable TPs, because you cannot specify a particular LU alias to use; each CPI-C invokable TP must have a different name.

Parameters are for invocation on any LU/on specific LU

If the TP is an APPC TP, this parameter specifies whether to make the TP invokable on any LU or only on a specific LU. By default, the TP can be invoked on any LU.

Note: If the TP is a CPI-C application, this field must be set to make the TP invokable on any LU. CPI-C does not support accepting incoming Attaches from a particular local LU; attempting to specify this option for a CPI-C application will cause errors in routing the incoming Attach to the TP.

LU alias

This field must not be used if the TP is a CPI-C application. If the TP is an APPC application, it applies only if you specify that the parameters for this TP definition are for invocation on any LU.

The local LU alias from which the TP is to accept incoming Attaches. This name must match the name of a local APPC LU on the CS Linux node. If you do not specify an LU alias, the TP accepts incoming Attaches from any local LU.

If a non-blank LU alias is specified, the TP must use the extended form of the RECEIVE_ALLOCATE verb and specify this LU alias as a parameter to the verb. This enables CS Linux to route the incoming Attach to the correct TP. For more information about the different forms of RECEIVE_ALLOCATE, refer to IBM Communications Server for Data Center Deployment on AIX or Linux APPC Programmer's Guide. If you need to permit the TP to determine the correct LU alias at run-time rather than building it into the application, you can do this by setting an environment variable to contain the appropriate LU alias (using the Environment parameter), and designing the application to read this environment variable in order to determine how to issue RECEIVE_ALLOCATE.

You can define multiple TPs that have the same TP name, provided each TP definition specifies a different LU alias.

Multiple instances supported

If you do not select this option, the TP is a queued TP. Any incoming Allocate requests arriving while the TP is running are queued until the TP issues another Receive_Allocate, or until it finishes running and can be restarted. An incoming Allocate request is routed to this TP only if it is received by an LU that is configured to route incoming Allocate requests to this computer, or if it is received by an LU on this computer that has no routing information configured.

If you select this option, the TP is a nonqueued TP. CS Linux starts a new copy of the TP each time an incoming Allocate request arrives for it. A nonqueued TP cannot be started by an operator; it is always started automatically by CS Linux. For a nonqueued TP, CS Linux permits more than one copy of the TP to be running at a time. All copies run with the same user and group IDs and the same working directory, as defined by the User ID and Group ID parameters. If the TP writes to files on the local system, you need to ensure that different copies of the TP do not overwrite each other's files.

After a nonqueued TP has ended a conversation, it may terminate, or it may issue another RECEIVE_ALLOCATE. For frequently-used programs, this provides a way of avoiding the performance overhead of starting a new instance of the program for each conversation. Each time an Attach is received for a nonqueued, automatically started TP, CS Linux checks whether there is already a RECEIVE_ALLOCATE outstanding from an instance of this TP. If so, this TP is used for the incoming conversation; otherwise, CS Linux starts a new instance of the program.

Route incoming Allocates to running TP

This option applies only if multiple instances are not supported.

Select this option if the TP is a broadcast queued TP. Any incoming Allocate requests arriving while the TP is running are queued until the TP issues another Receive_Allocate, or until it finishes running and can be restarted. When the TP is started, information about the TP is broadcast to all servers on the LAN; if an LU on another computer receives an incoming Allocate request and has no routing information configured, it can dynamically locate the TP and route the Allocate request to it.

Using this option avoids having to configure explicit routing information on LUs, and enables load-balancing by running more than one copy of the same TP on different computers. However, if you want to avoid broadcasting information in order to reduce LAN traffic, or if you need to ensure that incoming Allocate requests arriving at a particular LU are always routed to the same copy of the TP, do not select this option.

Full path to TP executable

The full path and file name of the executable file for this TP.

The file must have execute permission for the user specified by the User ID parameter. In addition, if the executable file is to be run with User ID set to root, the file must be owned by root and must have setuid and setgid permission in order to be started automatically by CS Linux.

Arguments

Any command-line arguments to be passed to the TP, separated by spaces. The arguments are passed to the TP in the same order as they appear here.

This value is optional. If it is not included, the TP is invoked without any command-line arguments.

User ID

The user ID that CS Linux uses to start the TP. This line is required, and must be specified. The ID must be a valid Linux login ID on the CS Linux computer.

The TP is started in the home directory associated with this user ID. This home directory is also the default path for trace files and any other files accessed by the TP (unless the application overrides it by specifying a full path). If the application specifies a file name without a path, CS Linux searches for the file in this home directory; if the application specifies a file name with a relative path, CS Linux searches for the file in the specified directory relative to this home directory.

The executable file for the TP, specified by the Full path to TP executable parameter, must have execute permission for the specified user. In addition, if User ID is set to root, the file must be owned by root and must have setuid and setgid permission in order to be started automatically by CS Linux.

Group ID

The group ID that CS Linux uses to start the TP. This must be a valid Linux group ID on the CS Linux computer.

This parameter is optional. If it is not included, the default is sna.

Standard input

Specify the full path name of the standard input file or device used by the TP.

This parameter is optional. If it is not included, the default is /dev/null.

Standard output

Specify the full path name of the standard output file or device used by the TP.

This parameter is optional. If it is not included, the default is /dev/null.

Standard error

Specify the full path name of the standard error file or device used by the TP.

This parameter is optional. If it is not included, the default is /dev/null.

Environment

Specify any environment variables required by the TP.

Each variable is specified in the form environment_variable=value, and can be up to 255 characters long. The string environment_variable=value must not contain space or tab characters before or after the = character.

In the Motif administration program, if you need to specify more than one environment variable (up to a maximum of 64), separate them using the | character. The variables are set in the same order as they appear here.

If the TP is a CPI-C application, note that you cannot set the environment variable APPCLLU using this field. The local LU cannot be specified for an automatically-loaded CPI-C application.

This field is optional. If it is not included, no environment variables are used.