|
|
|
|
SNAP-IX includes a command-line utility that enables a user or the writer of a TP installation program to define an invokable TP. You can run this utility on a server or client.
The syntax of the command is different depending on whether you are defining, removing, or querying TP definitions, and between Solaris and Windows:
snatpinstall -a file_name
tpinst32 -a file_name
This command adds one or more TP definitions from the specified file_name. If the TP named in the file has already been defined, the information in the file replaces the existing definition. For information about the required file format, see File Format for an Invokable TP Definition.
snatpinstall -r -t TP_name [ -l LU_alias ]
This command removes the entry that has the specified TP name and (if more than one APPC TP is defined with the same TP name) the specified LU alias. Omit the option if the entry is for a CPI-C application, or if there is only one APPC TP defined with the specified TP name.
tpinst32 -r -t TP_name
This command removes the entry that has the specified TP name.
snatpinstall -q [ -t TP_name ] [ -l LU_alias ]
This command queries the entry that has the specified TP name and (if more than one APPC TP is defined with the same TP name) the specified LU alias. Omit the option if the entry is for a CPI-C application, or if there is only one APPC TP defined with the specified TP name. If you do not include the option , the command queries all invokable TP definitions.
tpinst32 -q -t TP_name
This command queries the entry that has the specified TP name. If you do not include the option , the command queries all invokable TP definitions.
The file that supplies configuration information for an invokable TP is an ASCII text file that can be modified using any standard text editor. Each entry in the file has the following format:
[TPname] PATH = full_pathname_of_executable_file ARGUMENTS = command-line_arguments_separated_by_spaces TYPE = QUEUED | QUEUED-BROADCAST | NON-QUEUED TIMEOUT = nnn
USERID = user_ID
GROUP = group_ID
LUALIAS = LU_alias
ENV = environment_variable=
value
.
.
.
ENV = environment_variable=
value
SHOW = MAXIMIZED | MINIMIZED | HIDDEN | NORMAL | NOACTIVATE | MINNOACTIVATE SECURITY_TYPE = APPLICATION | SERVICE SERVICE_NAME = name_of_installed_service
The parameters are as follows. For an operator-started TP, the only parameters used are the TP name, the TP type, the timeout value, and (for an APPC TP on Solaris) the LU alias; the other parameters apply only to automatically started TPs.
On Solaris machines, SNAP-IX returns an error message if you enter an invalid parameter.
On Windows machines, SNAP-IX ignores invalid parameters.
The name of the TP (1-64 characters, with no embedded space characters). The TP name specified on the Receive_Allocate, or on the incoming Allocate request, is matched against this name. If the TP is an automatically started TP, it must specify this TP name on the Receive_Allocate when it starts up, to enable SNAP-IX to route the incoming Attach to the correct TP.
This name must be enclosed within square brackets. The name can be specified as an ASCII string, enclosed in double quotation marks (for example, ["TPNAME1"]). Alternatively, it can be specified as a hexadecimal array representing the EBCDIC characters of the TP name (for example, [<53504E414D45F1>]) or as a combination of the two (for example, [<3f>"TP1"]). In this example, the first character is the unprintable character 0x3f, and the following characters are "TP1".
SNAP-IX converts a supplied ASCII string to EBCDIC, but does not perform any conversion on a hexadecimal string (which is assumed to be in EBCDIC already). It then pads the name with EBCDIC spaces on the right (to a total of 64 characters) before matching against the specified TP name.
The path and file name of the executable file for this TP.
This line is optional. If it is not included, SNAP-IX assumes that the executable file name is the same as the TP name. If you specify a file name with no path, the default path for Solaris systems is /etc/opt/sna; for a Windows client, SNAP-IX uses the normal Windows mechanisms for locating the executable file.
Any command-line arguments to be passed to the TP, separated by spaces. These arguments are passed to the TP in the same order as they appear on the command line.
This line is optional. If it is not included, the TP is invoked without any command-line arguments.
Specify one of the following values:
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.
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 QUEUED-BROADCAST instead of QUEUED avoids having to configure explicit routing information for 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, you should use QUEUED.
The TP is a nonqueued TP. SNAP-IX starts a new copy of the TP each time an incoming Allocate request arrives for it. Do not specify the TIMEOUT parameter for a nonqueued TP.
A TP defined as nonqueued cannot be started by an operator; it is always started automatically by SNAP-IX. Do not specify NON-QUEUED if the TP is to be operator-started. If a user attempts to start a nonqueued TP, SNAP-IX rejects the Receive_Allocate because no incoming Allocate request is waiting for it.
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, SNAP-IX 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, SNAP-IX starts a new instance of the program.
If you use NON-QUEUED, more than one copy of the TP can be running at a time. If the TP writes to files, you need to ensure that different copies of the TP do not overwrite each other's files. To do this, use one of the following methods:
Ensure that the TP appends data to an existing file instead of creating the file (so that all copies of the TP append data to the same file)
Design the TP to generate file names at run-time, based on the process ID with which the TP is running (so that each copy of the TP writes to a different file).
This line is optional. If it is not included, or if an invalid value is specified, the default is QUEUED.
The maximum length of time, in seconds, that a Receive_Allocate call
issued by the TP should block if there is no incoming Allocate request pending.
If no incoming Allocate is received in this time, the call fails with a return
code indicating State check - Allocate not pending.
A timeout value of 0 indicates that the call always fails unless an incoming Allocate is already pending when the call is issued. A timeout value of -1 indicates that the call waits indefinitely for an incoming Allocate and does not time out.
This line is optional. If it is not included, or if an invalid value (a non-numeric value) is specified, the default is -1 (infinite).
Do not specify this parameter if the TYPE parameter is set to NON-QUEUED. SNAP-IX uses a timeout value of 0 for nonqueued TPs, because the TP is always started in response to an incoming Allocate and so there is always one pending.
Specify the user ID that SNAP-IX uses to start the TP. 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, SNAP-IX searches for the file in this home directory; if the application specifies a file name with a relative path, SNAP-IX searches for the file in the specified directory relative to this home directory.
This line is required, and must be specified. The ID must be a valid Solaris login ID on the SNAP-IX computer; it can be up to 64 characters, unless your Solaris configuration restricts user names to fewer characters.
The executable file for the TP, specified by the PATH parameter, must have execute permission for the specified user. In addition, if USERID 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 SNAP-IX.
Specify the group ID that SNAP-IX uses to start the TP. This must be a valid Solaris group ID on the SNAP-IX computer; it can be up to 64 characters, unless your Solaris configuration restricts group names to fewer characters.
This line is optional; if it is not included, the default is other.
Specify the local LU alias from which the TP is to accept incoming Attaches.
This parameter can be used only if the TP is an APPC TP. If the TP is a CPI-C application, do not specify this parameter. CPI-C does not support accepting incoming Attaches from a particular local LU; specifying an LU alias (even a blank LU alias) for a CPI-C application will cause errors in routing the incoming Attach to the TP.
This is an eight-character name that must match the name of a SNAP-IX local APPC LU.
To indicate that the TP accepts incoming Attaches from any local LU, set this parameter to two double quotation mark characters, "", indicating a blank LU alias. If the invokable TP data file contains more than one entry for the same TP name, only one of these entries can specify a blank LU alias; each of the others must specify a different explicit LU alias. SNAP-IX matches an incoming Attach for this TP name to a TP specifying the appropriate LU alias, if possible, or to a TP specifying a blank LU alias if no LU alias match can be found.
If a non-blank LU alias is specified in the file, the TP must use the extended form of the APPC RECEIVE_ALLOCATE verb and specify this LU alias as a parameter to the verb. This enables SNAP-IX to route the incoming Attach to the correct TP. For more information about the different forms of RECEIVE_ALLOCATE, refer to SNAP-IX 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 ENV parameter), and designing the application to read this environment variable in order to determine how to issue RECEIVE_ALLOCATE.
This line is optional; if it is not included, the default is to accept incoming Attaches from any local LU, and the TP can use either form of the APPC RECEIVE_ALLOCATE verb.
Specify any environment variables required by the TP. Each variable is specified in the form environment_variable =value on a separate ENV line. Up to 64 ENV lines can be included; the variables are set in the same order as they appear here.
The string environment_variable =value must not contain space or tab characters before or after the = character.
Specify how the application should be displayed when it is started. This parameter is passed to the application, and not processed by SNAP-IX; it is the application's responsibility to interpret it and act on it. You can enter any of the following values:
The application is maximized.
The application is minimized.
The application does not appear on the screen.
The application is displayed at its normal size and position.
The application is displayed at its normal size and position, and the focus remains on the previously active window. This application's window does not become the active window.
The application is minimized, and the focus remains on the previously active window.
This parameter is optional. If it is not included, the default is NORMAL.
Specify the security type of the TP executable:
The TP executable is started as an application using the CreateProcess system call.
The TP executable is started as a service using the StartService system call. In this case, the service must have been previously installed with the Service Control Manager using the name specified by the SERVICE_NAME parameter.
This value is valid only for Windows NT, and not for Windows 95. It refers to a TP running as a Windows NT Service (not to an SNA service TP with a name consisting of 4 characters specified in hexadecimal). Windows NT allows only one copy of a Service to be running at a time, and so the TYPE parameter should not be set to NON-QUEUED; if you specify this value, the value QUEUED-BROADCAST will be used instead.
The name of the service installed with the Service Control Manager. This parameter is only used if the SECURITY_TYPE is SERVICE.
Note the following points about the format of these entries:
You can include a comment line by including # as the first character of the line; SNAP-IX then ignores this line. SNAP-IX also ignores completely blank lines.
Each parameter= value entry must be on one line; it cannot contain line-break characters. The maximum length of a line is 255 characters; additional characters are ignored.
White space (space characters and tab characters) at the start or end of a line, or before or after the = character, is ignored (except in the string environment_variable =value for the ENV parameter).
Each TP definition begins with the line identifying the TP name, and ends with the end of the file or the next TP name.
Except for the ENV line, which can occur up to 64 times, do not specify the same parameter more than once for the same TP. If you do specify the same parameter more than once, only the last instance of each keyword is used.
|
|
|
 |
|