The TPOOL control statement allows you to define the name and properties of an LTERM pool. LTERM pools allow you to connect numerous clients with the same technical properties (partner and processor type) to a UTM application via LTERM partners. Printers are not supported in this case. The TPOOL statement merely defines the type (PTYPE=) and processor name (PRONAM=) for the client. The LTERM partner assigned to the client is specified dynamically in the UTM system code during connection setup on the basis of the LTERM partner name and client name defined in the TPOOL statement. This assignment applies only for the duration of a session, i.e. it is not a static assignment as in the case of the statement pair LTERM / PTERM. The clients contained in an LTERM pool need not be configured explicitly in the application (by defining a PTERM). The number of clients that can be simultaneously signed on is equal to the number of LTERM partners generated in the LTERM pool.
For clients that connect via an LTERM pool (i.e. that are not explicitly generated), the establishment of the connection can only be initiated "from outside", i.e. from the client itself. It is therefore not possible to establish a connection via UTM administration commands.
Also it is not possible to establish a connection via BCAM administration commands or using predefined BCAM connections on BS2000 systems.
The TPOOL statement allows you to define LTERM pools with different levels of availability for connection setup:
With PRONAM=processorname and PTYPE=partnertyp, an LTERM pool is generated such that only clients of the same type located on the specified system can establish connections with the UTM application via this LTERM pool.
With PRONAM=*ANY, all clients of a particular type can sign on to the UTM application irrespective of the system on which they are located.
On BS2000 systems with PTYPE=*ANY, you can define an LTERM pool without specifying the client type. This LTERM pool can then be used by clients of all types located on the specified system to establish connections with the UTM application.
With PRONAM=*ANY and PTYPE=*ANY, all clients on all systems can sign on to the UTM application on BS2000/PSD (open LTERM pool).
It is possible to define several LTERM pools, i.e. issue several TPOOL statements in each KDCDEF run. However, please note the following:
BS2000 systems:
The combination PRONAM / PTYPE / BCAMAPPL must be unique for LTERM pools for which the NEABT user protocol is defined (PROTOCOL=STATION). The combination PRONAM/BCAMAPPL must also be unique for LTERM pools with PROTOCOL=NO.
The client must support the user services protocol specified in the TPOOL statement. PROTOCOL=NO must be generated for clients with PTYPE=APPLI, PTYPE=SOCKET or PTYPE=UPIC-R. PROTOCOL=STATION must be specified for LTERM pools generated with PTYPE=*ANY.
During connection setup, openUTM takes the type (PTYPE) of the client generated with PTYPE=*ANY from the user services protocol (connection letter). openUTM then checks whether or not this client type is supported. If not, the connection request is rejected.
Unix, Linux and Windows systems:
The combination PRONAM/PTYPE/BCAMAPPL must be unique for LTERM pools.
For LTERM pools, the maximum number of connections that can be established via one transport system endpoint at a time must be taken into account.
The LTERM partners of an LTERM pool are generated with LTERM ..., RESTART=NO. During connection setup, therefore, all messages buffered in the message queue of the LTERM partners of the LTERM pool are deleted. An LTERM-specific service restart is not performed. In applications generated without user IDs, a service restart cannot be executed after a connection is cleared and then re-established for clients that are connected to the application via an LTERM pool.
You can specify access rights for an LTERM pool (KSET operand) that clients connected through the LTERM pool may exercise. In applications with user IDs you can limit the access rights specified with KSET for LTERM pools generated for connecting UPIC clients or
TS applications using the USER-KSET operand. The access rights in KSET are then applicable to clients that explicitly specify a user ID when signing on. The limited access rights in USER-KSET take effect when the client does not specify a user ID when signing on, i.e. when the “connection user ID“ is active.
Using the LOCALE operand, you can define a client-specific language environment for each LTERM pool.
|
additional operands BS2000 systems |
1 only on BS2000 systems
2 only on Unix, Linux and Windows systems
3 mandatory on BS2000 systems only
ANNOAMSG= | (announce asynchronous message) This operand is only supported on BS2000 systems. This applies only to LTERM pools used by terminals to sign on to the UTM application. It defines whether or not openUTM announces asynchronous messages before outputting them in the system line on the terminal. | ||||||
Y | Asynchronous messages are announced in advance. The user must then request the message using the KDCOUT command. Default: Y | ||||||
N | Asynchronous messages are sent without prior announcement. | ||||||
BCAMAPPL= | local_appliname Name of the local UTM application. This name is then used to establish a connection between the client and the UTM application. local_appliname is defined either with MAX ...,APPLINAME= or in the BCAMAPPL statement (see "BCAMAPPL - define additional application names"). If you specify a value other than APPLI, SOCKET or UPIC-R for the PTYPE= operand, you can only specify the name defined with MAX ...,APPLINAME=appliname for local_appliname. Default: appliname, specified under MAX ...,APPLINAME=. BS2000 systems: The BCAMAPPL statement allows you to define whether or not NEA or ISO transport protocols or native TCP/IP (socket interface) are to be used when communicating with partners that sign on to this application. To establish a connection with the UTM application, the client must generally specify local_appliname as the partner name. One exception are LTERM pools that are generated with PTYPE=SOCKET. In this case, clients that connect via the LTERM pool must know the port number on which the UTM application "listens". This port number is specified in BCAMAPPL LISTENER-PORT= . Unix, Linux and Windows systems: | ||||||
CONNECT-MODE= | This defines whether a client can use the same name for multiple sign-ons to the UTM application via this LTERM pool. | ||||||
SINGLE | Multiple sign-ons via the LTERM pool under the same name are not permitted. Default: SINGLE | ||||||
MULTI | This is permitted only for LTERM pools that are used by UPIC partners or TS applications to connect. A UPIC client or TS application can connect a maximum of number1 times to the LTERM pool (see NUMBER=number1, "TPOOL - define an LTERM pool"). In the case of CONNECT-MODE=MULTI, the UTM application does not identify the communication partner or the connection to the partner (as usual) using the name of the partner that the partner specified when the connection was established. The UTM application does not even know the partner under its application name. Instead, the partner is identified using the name of the pool LTERM partner (ltermname) through which it is connected. In order for openUTM to be able to uniquely identify the partner, the triplet consisting of the ltermname of the LTERM pool, the processorname and the local_appliname must not be explicitly generated in any PTERM, CON or OSI-CON statement. Additionally, the name that the partner specifies when establishing the connection may not match any LTERM name of the LTERM pool. | ||||||
ENCRYPTION-LEVEL= | |||||||
Only relevant for UPIC clients that support encryption and on BS2000 systems for some terminal emulations that support encryption also. In ENCRYPTION-LEVEL you set the minimum encryption level for the communication with the clients, that connect via an LTERM pool with the application. You specify whether or not the UTM application should request encryption of the message on the connection via the LTERM pool to the client. You can also define the client as a "trusted" client. This means that every client that connects via this LTERM pool is considered to be a trusted client.(see also section "Message encryption on connections to clients" for more information on encryption). Default values: TRUSTED is the default value for:
Other values for these partners are changed to TRUSTED by KDCDEF without issuing a message. NONE is the default value for
For partners with PTYPE different from UPIC-R, and on BS2000 different from T9763, the values 3, 4, 5 are changed to NONE by KDCDEF without issuing a message. You can specify the following: | |||||||
NONE | Encryption of the messages exchanged between the client and the UTM application is not requested by openUTM. Default: NONE | ||||||
3 | 4 | 5 | Messages exchanged between the client and the UTM application are encrypted by openUTM by default. The value specifies the encryption level. Only clients that support at least this encryption level can connect via this LTERM pool. If a client does not support the specified encryption level, openUTM rejects connection setup to the client. The values have the following meaning:
BS2000 systems: If the application is generated with OPTION GEN-RSA-KEYS=NO, no RSA keys are created in the KDCDEF run. In order to use the encryption functions, you must create the required keys using administration facilities (KC_ENCRYPT or WinAdmin or WebAdmin) or transfer them from an old KDCFILE using KDCUPD. | ||||||
TRUSTED | Messages between the client and the application are not encrypted. TRUSTED should only be selected for an LTERM pool if communication is conducted through a secure connection. | ||||||
FORMAT= | This operand is supported on BS2000 systems only. Start format for users on terminals that sign on to the application via this LTERM pool (see also the statement LTERM ...,FORMAT=, in section "LTERM - define an LTERM partner for a client or printer"). Default: No start format | ||||||
| IDLETIME= | time The maximum time in seconds that openUTM may wait for input from the client outside of a transaction, i.e. after the end of a transaction or after signing on. If this time is exceeded, then openUTM clears down the connection to the client. If the client is a terminal, then message K021 is output before the connection is cleared. This function serves to improve data security: Default: 0 (= no wait time limit). For TPOOLs that HTTP clients can connect to, the default value is 180 seconds. If you specify a value that is greater than zero and smaller than the minimum value, KDCDEF replaces the value with the minimum value. | ||||||
| KERBEROS-DIALOG = | This operand is supported on BS2000 systems only. | ||||||
Y | A Kerberos dialog is performed when a connection is established for terminals that support Kerberos and that connect to the application directly via this terminal pool (not via OMNIS). openUTM stores the Kerberos information in the length resulting from the maximum lengths generated for MAX PRINCIPAL-LTH and MAX CARDLTH. If the Kerberos information is longer, it is truncated to this length and stored. The KDCS call INFO (KCOM=CD) allows a program unit run to read this information. | ||||||
N | No Kerberos dialog is performed, | ||||||
KSET= | keysetname1 Name of a key set assigned to this LTERM pool. The key set must be defined with a KSET statement. This defines the access permissions for the LTERM partners of this LTERM pool with respect to using the services of the application and remote services (LTACs) generated in this application. An LTERM partner of this LTERM pool can only be used to start services of the application that are protected with a lock code or an access list and only address remote services that are protected with a lock code or an access list if the following applies: The key set assigned to the LTERM partner and the KSET of the UTM user ID under which sign-on using this LTERM partner was performed must contain the key code or access code that matches the lock code or access list. With PTYPE=APPLI, SOCKET, UPIC-R, UPIC-L the following additionally applies with respect to the key set of the user ID:
| ||||||
LOCALE= | (lang_id,terr_id,ccsname) This operand is supported on BS2000 systems only. Language environment of clients that sign on to the UTM application via the LTERM pool. | ||||||
lang_id | Freely selectable language identifier for the clients of the LTERM pool, up to two characters in length. | ||||||
terr_id | Freely selectable territorial identifier for the clients of the LTERM pool, up to two characters in length. The territorial identifier may be queried by the program units of the application, so that any special territorial features of the client’s language can be taken into consideration in messages. | ||||||
ccsname | (coded character set name) The character set with the specified name is used for:
Default: If TPOOL ...,LOCALE is not specified, then the locale of the | ||||||
LOCK= | lockcode Access protection to the LTERM pool. Lock code assigned to the LTERM partners of the LTERM pool. lockcode is a numeric value between 1 and the maximum value permitted in the application (MAX ...,KEYVALUE=). You can only sign on to the application on an LTERM partner of this LTERM pool under a UTM user ID (USER) for which a key set was generated with a key code that matches the lock code of the LTERM pool. Default: 0 (the LTERM pool is not secured with a lock code) | ||||||
LTERM= | ltermprefix Prefix for the names of LTERM partners of the LTERM pool. LTERM names are eight characters in length, and consist of the prefix specified here followed by a serial number between 1 and the value defined for NUMBER=number1. The maximum length of ltermprefix depends on the number of decimal places in number1. The number of characters in ltermprefix plus the number of decimal places in number1 must be less than 8. When specifying ltermprefix and number1, please note that LTERM partner names must be unique within the application. This applies for names generated with TPOOL ...,LTERM= (in all TPOOL statements) and for names defined in LTERM statements. Example These names must not be specified in any LTERM statement. The specified names must not be assigned to any other object in name class 1. See also section "Uniqueness of names and addresses". | ||||||
MAP= | Controls the code conversion (EBCDIC <-> ASCII) for the user messages exchanged between the communication partners. User messages are passed in the message area on the KDCS interface in the message handling calls (MPUT/MGET/FPUT/DPUT/FGET). | ||||||
USER | openUTM does not convert the data of the message area, i.e. the messages are transferred between the partners application unchanged. For TPOOLs, to which exclusively HTTP clients may connect, only the default value USER may be specified for parameter MAP. On BS2000 systems a code conversion for HTTP clients can be configured using the statements CHAR-SET and HTTP-DESCRIPTOR, see the description in chapters "CHAR-SET- assign names to code tables (BS2000 systems)" and "HTTP-DESCRIPTOR - define a HTTP Descriptor". Default: USER | ||||||
| SYSTEM | SYS1 | SYS2 | SYS3 | SYS4 | |||||||
This parameter is only permitted for the following partners:
UTM converts the user messages based on the conversion tables provided for the code conversion (see section "Code conversion"), i.e.:
The specifications SYSTEM and SYS1 are synonymous. UTM assumes that the messages contain only printable characters. | |||||||
NETPRIO= | This operand is supported on BS2000 systems only. Transport priority to be used on the transport connections assigned to this LTERM pool. NETPRIO is not relevant when the connection from the partner application is established via the socket interface (transport protocol SOCKET). Default: MEDIUM | ||||||
NUMBER= | number1 Maximum number of LTERM partners in this LTERM pool. Up to number1 clients can then sign on to the application via the LTERM pool. The maximum value permitted for number1 depends on the number of names generated in the UTM application (see section "Number of names"). Minimum value: 1 | ||||||
PRONAM= | System on which the clients must be located in order to sign on to the application via this LTERM pool. Unix, Linux and Windows systems:
BS2000 systems:
| ||||||
| { processorname | C’processorname’ } | |||||||
Name of the partner computer. The complete name (FQDN) by which the computer is known in the DNS must be specified. The name can be up to 64 characters long. Only clients located on this system can sign on to the application via this LTERM pool. If processorname contains special characters it must be entered in the form of a character string using C’...’ . Instead of the name of the partner computer name you can enter the mapped name of a SUBNET statement. These names begin with a "*". All clients which belong to the subnet defined with this SUBNET statement can connect themselves to a TPOOL generated in this way. Please note that in this case you must specify the local application name of the associated SUBNET statement in the BCAMAPPL operand. | |||||||
*ANY | Any client that fulfills the following conditions can sign on to the application via the LTERM pool:
| ||||||
PROTOCOL= | This operand is supported on BS2000 systems only. This operand specifies whether or not the user services protocol (NEABT) is to be used between the UTM application and the clients accessed via this LTERM pool. | ||||||
N | openUTM does not use a user services protocol. PROTOCOL=N must be generated for UPIC client programs (PTYPE=UPIC-R) and for TS applications (PTYPE=APPLI or SOCKET). In this case, openUTM ignores the entry PROTOCOL=STATION without outputting a UTM message. If you specify PTYPE=*ANY, openUTM ignores the entry PROTOCOL=NO. | ||||||
STATION | The user services protocol (NEABT) is used between the UTM application and the clients accessed via this LTERM pool. With PTYPE=*ANY, you must specify PROTOCOL=STATION. In this case, openUTM requires the user services protocol (NEABT) to determine the partner type if this is not explicitly specified during generation (PTYPE=*ANY). Default: | ||||||
PTYPE= | Type of client that can sign on to the application via this LTERM pool. If you have specified an application name in BCAMAPPL= that is generated for communication via the socket interface (BCAMAPPL statement with T-PROT=SOCKET), then you must set PTYPE=SOCKET. This is a mandatory operand. | ||||||
partnertyp | Type of client. A list of partner types supported can be found in the description of the PTERM control statement in section "PTERM - define the properties of a client/printer and assign an LTERM partner". Please note that printers cannot be connected via LTERM pools. | ||||||
*ANY | only permitted on BS2000 systems. In this case, openUTM takes the partner type from the user services protocol during connection setup. Only then can it be determined whether or not the partner type is supported. The advantage of PTYPE=*ANY is that it allows you to include clients in the configuration without having to know their type. The configuration is also easier to maintain because even if the type is modified in the terminal emulation, for example, this client can still sign on to the application without having to modify the KDCDEF generation. | ||||||
QLEV= | queue_level_number (queue level) Default: 32767 If you exceed the maximum value, KDCDEF automatically resets your entry to the default value without outputting a UTM message. | ||||||
STATUS= | NUMBER=number1 defines the number of LTERM partners in the LTERM pool. STATUS=number2 defines the number of clients that are unlocked (ON) and locked (OFF) for the LTERM pool when the application is started. Default: | ||||||
ON | number2 clients are unlocked. | ||||||
OFF | number2 clients are locked. | ||||||
number2 | Number of clients (and thus the number of LTERM partners of the LTERM pool) which are locked or unlocked. | ||||||
TERMN= | termn_id Identifier up to two characters in length, which indicates the type of client. openUTM provides this identifier to the application program in the KCTERMN field of the KB header. termn_id is not queried by openUTM, but can be used by the user for analysis purposes. Default values: If this operand is not specified, openUTM sets the KCTERMN field to the default ID of the partner type specified in the PTYPE operand. However, the user can select other values if desired. The default values are listed in the partner type table for the PTYPE operand of the PTERM statement "PTERM - define the properties of a client/printer and assign an LTERM partner". BS2000 systems: | ||||||
USER-KSET= | keysetname2 This is only allowed if the application is generated with user IDs and PTYPE=APPLI, SOCKET, UPIC-R or UPIC-L is specified. You may only set USER-KSET= in conjunction with KSET= . You must specify the name of a key set for ksetname2. The key set must be defined with a KSET statement. You specify the minimum access rights that a client connected via this LTERM pool can exercise with USER-KSET= . ksetname2 takes effect when the client is signed on under the connection user ID. Its access rights are the result of the set of key codes that are contained in the key set generated with KSET= and in the key set generated with USER-KSET= (intersection). For this reason, all key codes contained in USER-KSET=ksetname2 should also be contained in KSET=ksetname1. Default: No key set | ||||||
USP-HDR= | Specifies the output messages for which openUTM is to create a UTM socket protocol header for the connections generated with this statement. A value that is not equal to NO may only be specified with LTERM pools for which communication is configured via socket connections (PTYPE=SOCKET). A description of the USP header can be found in the openUTM manual „Programming Applications with KDCS”. For TPOOLs to which exclusively HTTP clients may connect, only the default value NO may be specified for parameter USP-HDR. | ||||||
ALL | For all output messages (dialog, asynchronous, K messages) openUTM creates a UTM socket protocol header and adds this to the front of the message. | ||||||
MSG | openUTM only creates a UTM socket protocol header and adds this to the front of the message for K messages only. | ||||||
NO | No UTM socket protocol headers are created. Default: NO | ||||||