kc_tpool_str - LTERM pools for the application

The data structure kc_tpool_str is defined for the object type KC_TPOOL. In the case of KC_GET_OBJECT, UTM returns the following information on an LTERM pool in kc_tpool_str:

• the number of LTERM partners currently permitted for the LTERM pool

• the properties of the LTERM partners of the LTERM pool

• the type of clients that may connect to the application via this LTERM pool

• statistical data on the workload of the LTERM pool.

mod 1	Data structure kc_tpool_str
-	char lterm[8];
-	char pronam[8];
-	char ptype[8];
-	char bcamappl[8];
-	char connect_mode;
-	char max_number[10];
-	char kset[8];
-	char locale_lang_id[2]; (only on BS2000 systems)
-	char locale_terr_id[2]; (only on BS2000 systems)
-	char locale_ccsname[8]; (only on BS2000 systems)
-	char lock_code[4];
x(GP)2	char state;
x(GP)2	char state_number[10];
-	char format_attr; (only on BS2000 systems)
-	char format_name[7]; (only on BS2000 systems)
-	char qlev[5];
-	char termn[2];
-	char annoamsg; (only on BS2000 systems)
-	char netprio; (only on BS2000 systems)
-	char protocol; (only on BS2000 systems)
-	char actcon[10];
-	char maxcon[10];
-	char map;
x(GP)	char idletime[5];
-	char encryption_level;
-	char user_kset[8];
-	char usp_hdr;
-	char kerberos_dialog; (only on BS2000 systems)
-	char pronam_long[64];
-	char resolve_names;

1	The contents of the field can be modified with KC_MODIFY_OBJECT; see "obj_type=KC_TPOOL".
2	Wth KC_MODIFY_OBJECT both fields must be specified together.

The fields in the data structure have the following meanings:

lterm
	Contains the prefix for the names of the LTERM partners of the LTERM pools. The names of the LTERM partners consists of this prefix and a sequential number. The sequence goes from 1 up to the value returned in max_number. Example If max_number='1000' and lterm='LTRM', then the LTERM partners of the LTERM pool are named LTRM0001, LTRM0002, ..., LTRM1000.
pronam
	Specifies the computer on which the clients must be located in order to connect to the application via this LTERM pool. If a computer name with more than 8 characters has been generated for the LTERM-Pool, the complete name, up to 64 characters long, can be taken from the pronam_long field. In this case, the pronam field contains the first 8 characters of that name. UTM returns either the symbolic name under which the computer is known to the local transport system or the value '*ANY' for an open LTERM pool. '*ANY' means:  Every client can sign on to the application via the LTERM pool if the client fulfills the following conditions: Its terminal type matches the type specified in ptype. It was not explicitly added to the configuration (with the KDCDEF statement PTERM or dynamically with object type KC_PTERM). No other LTERM pool exists for the computer on which the client resides nor for its terminal type (ptype).
ptype
	The type of clients that are allowed to connect to the application via this LTERM pool. You can determine the meaning of the value returned by UTM in ptype from the tables for BS2000 Systems and for Unix, Linux and Windows systems in chapter "kc_pterm_str - Clients and printers". Only on BS2000 systems: If ptype='*ANY', then it is an open LTERM pool. All clients resident on or connected to the computer specified in pronam and for which the following statements are true can connect via this LTERM pool: The client is not entered explicitly in the configuration. No LTERM pool exists for which the client type is set in ptype for the computer in pronam.
bcamappl
	The name of the local UTM application (BCAMAPPL name) via which the connection between the client and the UTM application will be established. This name must be specified by the client when it wants to establish a connection to the local application.
connect_mode
	Specifies if a client can connect to the UTM application via the LTERM pool more than once under the same name.
	'S'	Each client can only connect once under the same name via the LTERM pool.
	'M'	An UPIC client (ptype='UPIC-R' or 'UPIC-L') or a TS application (='APPLI' or 'SOCKET') that runs more than once on the same computer can connect to the UTM application via the LTERM pool more than once under the same name. A new name does not have to be created for every connection. The UPIC client or the TS application can connect to the LTERM pool as many times as there are LTERM partners allowed for the LTERM pool. The name of the corresponding pool LTERM partner will be set in this case to the name of the client or TS application, i.e. the partner will then be identified in the application by the name triplet (name of the LTERM partner, pronam and bcamappl). The UPIC client or the TS application is not known in the UTM application under its local name or its application name.
max_number
	Specifies the maximum number of clients that may be simultaneously connected via this LTERM pool, i.e. max_number specifies how many LTERM partners comprise this LTERM pool.
kset	Contains the name of the key set assigned to the LTERM pool. The key set determines which transaction codes the clients that connect to the application via this LTERM pool may call. The clients may only start a transaction code if the key set contains a key code that numerically matches the lock code of the transaction code, or if the transaction code does not have access security, i.e. it does not possess a lock code. If the LTERM pool is not assigned a key set, then kset contains blanks. The following applies for ptype='UPIC-...', 'APPLI' or 'SOCKET': kset specifies the maximum number of access of a client which connects through this LTERM pool. kset always comes into effect when the client passes a true user ID to UTM during session/conversation establishment. The access privileges result from the set of key codes contained both in the key set of the user ID an in kset. If the client does not pass a true user ID to openUTM for the session/conversation, the access privileges result from the subset of key codes in kset an user_kset (minimum access rights).
locale_lang_id, locale_terr_id, locale_ccsname (only on BS2000 systems)
	These contain the three components of the locale assigned to the LTERM pool. The locale defines the language environment of the clients that connect to the application via this LTERM pool (see also the openUTM manual “Generating Applications”). locale_lang_id  Contains the up to two characters long language code. locale_terr_id  Contains an up to two characters long territory code. locale_ccsname  (coded character set name) Contains the name (up to 8 characters) of an expanded character set (CCS name; see also the XHCS User Guide).
lock_code
	Contains the lock code assigned to the LTERM partners of the LTERM pool (access protection). Only users/clients who possess the corresponding key code may connect via this LTERM pool.  The lock_code can contain a number between '0' and '4000'. '0' means that the LTERM pool is not protected by a lock code.
state, state_number
	The number of LTERM partners comprising this LTERM pool is set in the KDCDEF generation of the LTERM pool (see max_number). The number of LTERM partners via which clients can connect to the application can, however, be reset to a smaller value during operation by the administration. The rest of the LTERM partners are disabled by this action. In the state and state_number fields UTM specifies how many LTERM partners of the LTERM pool are currently permitted, i.e. not disabled. The number of LTERM partners allowed determines how many clients can connect to the application via this LTERM pool at the same time. If state contains the value 'Y', the pool is permitted for the number of communication partners specified in state_number (ON). If state contains the value 'N', the pool is locked for the number of communication partners specified in state_number (OFF). If all LTERM partners of the LTERM pool are disabled, then state contains the value 'Y' and state_number the value '0'.
format_attr, format_name (only on BS2000 systems)
	These define the start format for users on terminals connected via this LTERM pool. After the connection between the terminal and the application is established, the formats described in format_attr and format_name will be output on the terminal as long as no terminal-specific restart is being executed. format_attr  Contains the format code:
	'A'	(format attribute ATTR) The start format is a format with user attributes. The properties of the format fields can be changed by the KDCS program unit. The format name at the KDCS program interface is +format_name.
	'N'	(format attribute NOATTR) The start format is a format without user attributes. Neither the field nor the format properties can be changed by the KDCS program units. The format name at the KDCS program interface is *format_name.
	'E'	(format attribute EXTEND) The start format is a format with expanded user attributes. The properties of the format fields as well as global format properties can be changed by the KDCS program unit. The format name at the KDCS program interface is #format_name.
	format_name  Contains the name of the start format. The name can be up to 7 characters long and contains only alphanumeric characters.
qlev ( queue level)
	Specifies the maximum number of asynchronous messages that may be temporarily stored in the message queue of the LTERM partner belonging to this LTERM pool for processing at one time by UTM. If the control value for an LTERM partner of the LTERM pool is exceeded, then UTM will reject any additional asynchronous jobs sent to this LTERM partner. The control value is specified in the KDCDEF generation.
termn ( terminal mnemonic)
	Contains the code for the type of client that can connect via this LTERM pool. When running, UTM KDCS program units that were started via the LTERM pool provide the code in the KCTERMN field of the communication area header. The code is a maximum of 2 characters long. The values that termn may contain can be obtained from the table for ptype in chapter "kc_pterm_str - Clients and printers" (section "BS2000 systems" or "Unix, Linux and Windows systems").
annoamsg (announce asynchronous message, only on BS2000 systems))
	Specifies if UTM will announce asynchronous messages on the terminal with a UTM message in the system line before output.
	'Y'	UTM announces every asynchronous message to this terminal with the UTM message K012 in the system line. The user must then explicitly request the asynchronous message with the KDCOUT command.
	'N'	Asynchronous messages are output on the terminal immediately, i.e. without announcement. For annoamsg = 'N', the establishing of the connection to this LTERM pool via a multiplex connection will only be possible starting with OMNIS V7.0.
netprio
	Specifies the transport priority used on the transport connection between theapplication and the clients connected via this LTERM pool.
	'M'	Medium transport priority
	'L'	Low transport priority
protocol (only on BS2000 systems)
	Specifies whether the NEABT user service protocol will be used on connections between the UTM application and a client that connects via this LTERM pool.
	'N'	The user protocol service will not be used between the UTM application and the client/printer. For UPIC clients (ptype='UPIC-R') and TS applications (ptype='APPLI' or 'SOCKET'), protocol='N' will always be output. No connections can be established via a multiplex connection to an LTERM pool for which protocol='N' is set.
	'S'	(STATION) The user protocol service (NEABT) is used between the UTM application and the client/printer. UTM uses the NEABT user protocol service for LTERM pools with ptype='*ANY', for example to determine the type (ptype) of a client. In this case, NEABT is always used.
actcon
	Specifies how many clients are currently connected to the application via this LTERM pool.
maxcon
	Contains the maximum number of clients that were simultaneously connected to the application via this LTERM pool in the current application run.  The counter is reset to 0 at the start of the application.
map
	Specifies whether UTM performs a code conversion (ASCII <-> EBCDIC) for user messages without any formatting flags which are exchanged between the partner applications. User messages are passed in the message area on the KDCS interface in the message handling calls (MPUT/FPUT/DPUT).
	'U'	(USER) UTM does not convert user messages, i.e. the data in the message is transmitted unchanged to the partner application.
	'1', '2', '3', '4' (SYS1 | SYS2 | SYS3 | SYS4)
		is only permitted for the following TS applications: BS2000 systems: ptype='SOCKET' Unix, Linux and Windows systems: ptype='APPLI' or 'SOCKET' If you specify one of these values, UTM converts the user messages according to the code tables provided for the code conversion, see the "Code conversion" section in the openUTM manual "Generating Applications", i.e.: Prior to sending, the code is converted from ASCII to EBCDIC on Unix, Linux and Windows systems and from EBCDIC to ASCII on BS2000 systems. After receival, the code is converted from EBCDIC to ASCII on Unix, Linux and Windows systems and from ASCII to EBCDIC on BS2000 systems. openUTM assumes that the messages contain only printable characters. For more information on code conversion, please refer to the openUTM manual „Programming Applications with KDCS”; keyword „code conversion".
idletime
	idletime contains the time in seconds which UTM waits for a response from a client after a single-step transaction is terminated or after sign-off (KDCSIGN). If the time is exceeded, the connection to the client is closed down. If the client is a terminal, message K021 was issued before connection shutdown. The value 0 means wait without time limit.
encryption_level
	Only relevant for UPIC clients and, on BS2000 systems, for some terminal emulations. encryption_level specifies whether, on the connection to the client that wants to connect to the application via the LTERM pool, the UTM application wants to demand encryption of messages by default, if it does, which encryption level must be used, wants to know whether the clients are „trusted“ clients. The following values are possible:
	'N'	(NONE) UTM does not want the messages to be encrypted. Services for which encryption was generated (see kc_tac_str.encryption_level in chapter "kc_tac_str - Transaction codes of local services") can only be started by a client connected through this pool if the client agrees encryption when setting up the connection. Passwords are transmitted encrypted if both partners support encryption.
	'3'	(LEVEL 3) UTM demands by default the encryption of messages with encryption level 3. In other words, the messages are encrypted with the AES-CBC algorithm and an RSA key with a key length of 1024 bits is used for exchange of the AES key. Connection establishment to the client is rejected by UTM if the client does not support at least this encryption level.
	'4'	(LEVEL 4) UTM demands by default the encryption of messages with encryption level 4. In other words, the messages are encrypted with the AES-CBC algorithm and an RSA key with a key length of 2048 bits is used for exchange of the AES key. Connection establishment to the client is rejected by UTM if the client does not support at least this encryption level.
	'5'	(LEVEL 5) only for Unix, Linux and Windows systems The key length is the same LEVEL 4. The Diffie-Hellman method based on Elliptic Curves is used to agree the session key and input/output messages are encrypted with the AES-GCM algorithm. The connection to the client is rejected by UTM if the client does not support at least this encryption level.
	'T'	(TRUSTED) The client is a “trusted” client. Messages and passwords exchanged between the client and the application are not encrypted. A “trusted” client can also start services for which the service TAC requires encryption (generated with kc_tac_str.encryption_level = '2' or '5'; see chapter "kc_tac_str - Transaction codes of local services"). Connections that are established using a transport system endpoint (BCAMAPPL) that is generated with T-PROT=(..., SECURE) are always classified as trusted by UTM.
user_kset
	Only relevant with ptype='UPIC-...', 'APPLI' or 'SOCKET'. user_kset contains the name of the key set defining the minimum access privileges of the client in the local application. The key set specified in user_kset only comes into effect if the client has signed on under the connection user ID (see also kset). The access rights in kset always apply.
usp_hdr
	Indicates the output messages for which UTM creates a UTM socket protocol header on this connection. Possible values are:
	'A'	(ALL) UTM creates a socket protocol header for all output messages (dialog, asynchronous, K messages) and precedes the message with it (ALL).
	'M'	(MSG) UTM creates a UTM socket protocol header for the output of K messages and precedes the message with it (MSG).
	'N'	(NO) UTM does not create a UTM socket protocol header for any output message (NO).
	The values 'A' and 'M' can only occur for LTERM pools that are configured for communication via socket connections (ptype='SOCKET').
kerberos_dialog (only on BS2000 systems)
	'Y'	When the connection is established ,a Kerberos dialog is conducted for clients that support Kerberos and are connected directly to the application via this terminal pool (not via OMNIS).
	'N'	No Kerberos dialog is performed.
	For more detailed information, refer to the openUTM manual “Generating Applications”.
pronam_long
	Specifies the computer on which the clients have to be located in order to be able to connect to the application using this LTERM-Pool. UTM returns either the symbolic name under which the computer is known to the local transport system or the value '*ANY' for an open LTERM-Pool. '*ANY' means that any client satisfying the following conditions can sign on to the application using the LTERM-Pool: Its type corresponds to the specification in ptype. It has not been explicitly entered in the configuration (with the KDCDEF statement PTERM or dynamically with the object type KC_PTERM). No other LTERM-Pool exists for the computer on which the client is located and its terminal type (ptype).
resolve_names
	Specifies whether or not a name resolution via DNS is to take place after a connection is established. See KDCDEF Statement SUBNET.