kc_pterm_str - Clients and printers

The data structure kc_pterm_str is defined for the object type KC_PTERM. In the case of KC_GET_OBJECT, UTM returns the following information in kc_pterm_str:

• The properties of clients and printers that were statically or dynamically added to the configuration of the application.

• The properties of clients that are presently connected to the application via an LTERM pool or multiplex connection.

• The properties and status of the connection to the corresponding client or printer.

• Statistical information on the connection load and the demands on the application for the individual clients/printers.

Clients and printers can be dynamically created with KC_CREATE_OBJECT, deleted with KC_DELETE_OBJECT or modified with KC_MODIFY_OBJECT.

mod 1	Data structure kc_pterm_str	see 2
-	char pt_name[8];	pt_name
-	char pronam[8];	pronam
-	char bcamappl[8];	bcamappl
-	char ptype[8];	ptype
-	char ptype_fotyp[8];	PRINTER
-	char ptype_class[40];	PRINTER
x(PD)	char lterm[8];	lterm
x(GPD)	char auto_connect;	auto_connect
x(GPD)	char state;	state
-	char cid[8];	cid
-	char map;	map
-	char termn[2];	termn
-	char protocol; (only on BS2000 systems)	protocol
-	char usage_type; (only on BS2000 systems)	usage_type
-	char listener_port[5];	listener_port
-	char t_prot;	t_prot
-	char tsel_format; (only on Unix, Linux and Windows systems)	tsel_format
x(A)	char connect_mode;	connect_mode
-	char pool;	pool
-	char mux; (only on BS2000 systems)	mux
-	char contime_min[10];	contime_min
-	char letters[10];	letters
-	char conbad[5];	conbad
-	char deleted;	deleted
X(GPD)	char idletime[5];	idletime
-	char encryption_level;	encryption_level
-	char ip_addr[15];	ip_addr
-	char curr_encryption;	curr_encryption
-	char t_mode; 3
-	char usp_hdr;	usp_hdr
-	char ip_addr_v6[39];	ip_addr_v6
-	char ip_v[2];	ip_v
-	char pronam_long[64];	pronam_long

1	Field contents can be modified with KC_MODIFY_OBJECT; see "obj_type=KC_PTERM".
2	The meaning of the fields is described on the pages indicated in this column.
3	UTM-internal field; the field contents is irrelevant and will not be discussed.

The fields in the data structure have the following meanings:

pt_name 

Contains the name of the client or printer. The client/printer is known to the transport system (BCAM, PCMX) under this (symbolic) name.

pronam 

The name of the computer on which the client can be found or to which the printer is connected.

In UTM applications on BS2000 systems pronam always contains data. For an RSO printer pronam contains the value '*RSO'.

In UTM applications running on Unix, Linux or Windows systems pronam contains blanks for a local client or printer.

If the real computer name is longer than 8 characters:

• The pronam field contains a symbolic local name assigned for this computer by the transport system.

• If no connection was established yet, pronam contains blanks.

• The complete name, up to 64 characters long, can be taken from the pronam_long field. 

bcamappl 

Name of the local UTM application via which the connection to the client/printer will be established.

For terminals and printers bcamappl always contains the name of the application that was specified for the KDCDEF generation in MAX APPLINAME.

For UPIC clients and TS applications bcamappl always (even if no connection is presently established) contains the application name assigned to the client when it was added to the configuration.

Only on BS2000 systems:

• For clients that are connected to the application via a multiplex connection, bcamappl contains the application name assigned to the multiplex connection when it was added to the configuration as long as the connection is established.

ptype 

The type of client or printer.

BS2000 systems

For clients/printers that are connected to a UTM application on a BS2000 system, either the partner type or the value '*ANY' or '*RSO' is returned. The partner types supported are listed in the following table:

ptype	Type of client/printer	termn field
*ANY	The client was added to the configuration without an exact specification of its device type. In this case, UTM uses the device type of the client from the user service log when establishing the connection. Only then will it be decided if the partner type is supported or not. Advantage of ptype='*ANY': You can add clients to the configuration without knowing their type. In addition, the administration of the configuration is made easier because even if the type is modified in the configuration, for example, this client will still be able to establish a connection to the application without you having to change the configuration of the application.	If the terminal mnemonic was not explicitly specified during configuration, then the standard terminal mnemonic of the partner type is used when establishing the connection. Otherwise, the value specified during configuration is stored here.
T100	Teletype T100	C0
T1000	Teletype T1000	E1
T8103	8103	FD
T8110	8110	C2
T8121V12	Printer 8121 on 8112	F7
T8122V12	Printer 8122 on 8112	F8
T8124	Printer 8124	FC
T8151	DSS 8151	F1
T8152	DSS 8152	F2
T8160	DSS 8160	F4
T8162	DSS 8162	F6
T8167	DSS 8167	FB
T9748 1	DSS 9748	FE
T9749	DSS 9749	FE
T9750 1	DSS 9750	FE
T9751	DSS 9751	FE
T9752	DSS 9752	FF
T9753	DSS 9753	FE
T9754	DSS 9754	FI
T9755 2	DSS 9755	FG
T97562	DSS 9756	FG
T9763	DSS 9763	FH
T9770	DSS 9770	FK
T9770R	DSS 9770R	FK
T3270	DSS 3270 (IBM)	FL
THCTX28	DSS X28 (TELETYPE)	C5
TVDTX28	DSS X28 (VIDEO)	C6
TPT80	Data station PT80	C4
T9001	9001 printer	C7
T9002	9002 printer	FA
T9003	9003 printer	F9
T9004	9004 printer	FD
T9001-3	9001-3 printer	CA
T9001-89	9001-893 printer	CB
T9011-18	9011-18 printer	CC
T9011-19	9011-19 printer	CD
T9012	9012 printer	CE
T9013	9013 printer	C9
T9021	9021 printer	CH
T9022	9022 printer	CF
T3287	3287 printer	CG
*RSO	Printer supported by RSO. Instead of establishing a transport connection, UTM reserves the printer with RSO and transmits the message to be printed to RSO.	RS
THOST	Intelligent terminal	A3
APPLI	Transport system application that is not a socket application (e.g. : DCAM, CMX or UTM application)	A1
UPIC-R	UPIC client	A5
SOCKET	USP-Socket application	A7
SOCKET	HTTP Client	A8
SOCKET	Secure USP-Socket application	A9
SOCKET	HTTPS Client	AA

1	T9748 and T9750 designate the same terminal type.
2	T9755 and T9756 designate the same terminal type.

The VTSU versions that support the individual terminals can be obtained from the DCAM, FHS or TIAM Manual.
If a terminal is not supported by VTSU, then UTM rejects a request for connection from this terminal. UTM triggers the UTM messages K064 and K107.

Unix, Linux and Windows systems

In a UTM application on Unix, Linux or Windows systems, ptype can contain the following values.

ptype	Type of client/printer	termn field
TTY	The client is a terminal. Default value	F1
PRINTER	ptype ='PRINTER' is only relevant on Unix and Linux system and is not allowed under openUTM on Windows systems. The significance of ptype ='PRINTER' depends on the contents of the ptype_fotyp field.	F2
	pt_name specifies the name of a printer to which the spool on Unix or Linux systems will print.
	ptype_fotyp and ptype_class either contains blanks or the appropriate printer type or printer group of pt_name.
APPLI	The client is a TS application that does not use the socket interface (e.g. UTM, CMX, or DCAM application).	A1
UPIC-L	The client is a local Client application with the UPIC carrier system.	A5
UPIC-R	The client is a remote Client application with the UPIC carrier system.	A5
SOCKET	USP-Socket application	A7
SOCKET	HTTP Client	A8
SOCKET	Secure USP-Socket application	A9
SOCKET	HTTPS Client	AA

lterm
	Name of the LTERM partner assigned to this client/printer.
auto_connect
	Specifies if the connection to the client/printer will be automatically established at the start of the application:
	'Y'	When starting the application, UTM attempts to establish the connection automatically if the client/printer is available when the local application is started.
	'N'	No automatic establishing of the connection when starting.
state
	Specifies if the client or printer is currently disabled.
	'Y'	The client/printer is not disabled, i.e. as long as the LTERM partner assigned to this client/printer is not disabled, connections between the client/printer and the local application can be established, or there are already established connections.
	'N'	The client/printer is disabled. No connections between the client/printer and the local application can be established.
cid (control identification)
	Only contains data if information about a printer is requested. cid contains the printer ID (CID) as long as a CID was assigned to the printer when it was added to the configuration. The CID has the following function: Using the CID, the printer can be identified at the program interface for the purpose of printer control. If the printer is assigned to a printer control LTERM, then the printer will be identified by the administration from the printer control LTERM using the CID.
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".
termn (terminal mnemonic)
	Contains the code for the type of communication partner. UTM KDCS program units provide the code in the KCTERMN field of the communication area header.  The values that termn may contain can be obtained from the table for ptype in "kc_pterm_str - Clients and printers" (BS2000 systems) or in "kc_pterm_str - Clients and printers" (Unix, Linux and Windows systems).
protocol (only on BS2000 systems)
	Specifies if the NEABT user protocol service ("station protocol") will be used on connections between the UTM application and the client/printer.
	'N'	The user protocol service will not be used between the UTM application and the client/printer. protocol='N' will always be output for: UPIC clients (ptype='UPIC-R') TS applications (ptype='APPLI' or 'SOCKET') printers access via RSO (ptype='*RSO') Clients for which protocol='N' is specified cannot connect to the application over a multiplex connection.
	'S'	(STATION) The user protocol service (NEABT) is used between the UTM application and the client/printer. UTM uses the user protocol service NEABT, among others, to determine the type (ptype) of a client or printer if the type was not explicitly specified when the client/printer was added to the configuration (added with ptype='*ANY').
usage_type (only on BS2000 systems)
	Specifies if the communication partner in pt_name is a dialog partner or purely an output medium.
	'D'	The client is a dialog partner. The client as well as the local application can send messages on the connections between the client and the local application. UPIC clients are always dialog partners (ptype='UPIC-R').
	'O'	The client/printer is used purely as an output medium. Messages can only be sent from the application to the client/printer. usage_type='O' is always output for printers.
listener_port
	BS2000 systems: Only relevant if t_prot='T'.  Unix, Linux and Windows systems: Only relevant if t_prot ='T' or 'R'. listener_port contains the port number of the partner application in the remote system in TCP/IP connections. In the case of KC_GET_OBJECT, the port number defined when the client was generated is returned. If listener_port = '0', then no listener port number was generated.
t_prot
	Contains the address format that the client uses to sign on to the transport system. The following address formats are possible:
	'T'	native TCP/IP transport protocol TCP-IP for communication via the socket interface (SOCKET)
	Only on Unix, Linux and Windows systems:
	'R'	RFC1006, ISO transport protocol class 0 using TCP/IP and the convergence protocol RFC1006.
	If the client was not assigned an address format when added to the configuration, then the t_prot field contains a blank.
tsel_format (only on Unix, Linux and Windows systems)
	Contains the format indicator of the T-selector in the address of the client. The following format indicators may occur:
	'T'	TRANSDATA format
	'E'	EBCDIC character format
	'A'	ASCII character format
	The meanings of the address formats are described in the "PCMX documentation" (openUTM documentation). If the client was not assigned a format indicator when added to the configuration, then the tsel_format field contains a blank.
connect_mode
	Specifies the current status of the connection to the client:
	'Y'	The connection is established.
	'W'	UTM is currently attempting to establish the connection (waiting for connection).
	'N'	The connection is not established.
	In UTM applications on BS2000 systems connect_mode can also contain the following values for clients/printers that are connected to the application via a multiplex connection (mux = 'Y'):
	'T'	(timer) The session with the client is in the DISCONNECT-PENDING state; the timer used for timing the wait for the confirmation of the closing of the connection is running.
	'E'	(expired) The session is in the DISCONNECT-PENDING state and the timer used for timing the wait for the confirmation of the closing of the connection has run down before the confirmation was received. The session must be explicitly released (for example using KC_MODIFY_OBJECT and connect_mode = 'R',see table in list item "Set up or shut down t the connection to the client/printer" in chapter "obj_type=KC_PTERM" ).
pool
	Specifies if the client is connected to the application via an LTERM pool.
	'Y'	The client is connected to the application via an LTERM pool.
	'N'	The client is not connected to the application via an LTERM pool.
mux (only on BS2000 systems)
	Specifies if the client is connected to the application via a multiplex connection.
	'Y'	The client is connected to the application via a multiplex connection.
	'N'	The client is not connected to the application via a multiplex connection.
contime_min
	Specifies how long the connection to the client/printer has already existed. The length of time is specified in minutes.
letters
	Contains the number of input and output messages for the client/printer since the last start of the local application.
conbad
	Specifies how often the connection to the client/printer has been lost since the last start of the application.
deleted
	Specifies whether or not the client/printer has been deleted from the configuration.
	'Y'	The client/printer has been deleted. The name, however, is disabled, i.e. no new client/printer can be added using this name.
	'N'	The client/printer has not been deleted.
idletime
	Only relevant for dialog partners. idletime contains the time in seconds, which UTM waits for a response from a client, after a transaction is terminated or after sign-off. If the time is exceeded the connection to the client is closed down. If the client is a terminal, the message K021 was issued before connection close-down. 0 means indefinite wait.
encryption_level
	Only relevant for UPIC clients and, on BS2000 systems, with some terminal emulations. encryption_level specifies whether the UTM application demands by default for all messages on the connection to the client to be encrypted or not, which encryption level is demanded, or whether the client is a “trusted” client. The following values are possible:
	'N'	(NONE) UTM does not demand the messages exchanged between the client and the UTM application 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 if the client explicitly selects encryption. Passwords are transmitted encrypted if both partners support encryption.
	'3'	(LEVEL 3) UTM demands 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 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 Key length is the same as for 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 ='1' or '2'; see "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.
ip_addr
	Returns the partner IP address used by UTM for this connection if the address is an IPv4 address. On BS2000 systems, IP adresses are output only for partners where ptype='SOCKET' , An IPv6 address is returned in the ip_addr_v6 field (see "kc_pterm_str - Clients and printers") In ip_addr, UTM returns the IP address of the client computer. The address is stored in the object table of the application. UTM uses this address to establish the connection to the client. UTM reads the IP address from the name service with the aid of the generated processor name (pronam) when the application is started. If the object table does not contain an IPv4 address for the client, e.g. because the client does not use the appropriate protocol, UTM returns blanks in ip_addr.
curr_encryption
	Only relevant for UPIC clients and on BS2000 systems for some terminal emulations. In curr_encryption, UTM returns the encryption level for an existing connection to a client which was agreed between the UTM application and the client for this specific connection. For information on the properties of encryption Levels 3 to 5 see also "kc_pterm_str - Clients and printers".
	'N'	(NONE) Messages exchanged on this connection are not encrypted. Passwords are transmitted encrypted if both partners support encryption.
	'3'	(LEVEL 3) All messages on the connection are encrypted. Encryption level 3 is used.
	'4'	(LEVEL 4) All messages on the connection are encrypted. Encryption level 4 is used.
	'5'	(LEVEL 5) (only for Unix, Linux and Windows Systems) All messages on the connection are encrypted. Encryption Level 5 is used.
	' '	(Blank)There is currently no connection to this client.
usp_hdr
	This is only relevant for socket partners. It indicates for which output messages UTM sets up a UTM socket protocol header on this connection. Possible values are:
	'A'	UTM creates a UTM socket protocol header for all output messages (dialog, asynchronous, K messages) and precedes the message with it.
	'M'	UTM creates a UTM socket protocol header for the output of K messages and precedes the message with it.
	'N'	UTM does not create a UTM socket protocol header for any output message.
ip_addr_v6
	Returns the partner IP address used by UTM for this connection if the address is an IPv6 address or an IPv4 address embedded in an IPv6 format. On BS2000 systems, IP adresses are output only for partners where ptype='SOCKET' , An IPv6 address is returned in the ip_addr_v6 field (see "kc_pterm_str - Clients and printers") UTM returns the IP address of the client computer stored in the object table of the application in ip_addr_v6. UTM uses this address to establish the connection to the client. UTM reads the IP address from the Name Service using the generated computer name (pronam) when the application is started. If there is no IPv6 address in the object tables for the client, UTM returns blanks in ip_addr_v6.
ip_v
	Specifies whether the IP address used by UTM for this connection is an IPv4 or an IPv6 address:
	'V4'	IPv4 Address.
	'V6'	IPv6 address or IPv4 address embedded in IPv6 format.
	If no IP address can be returned, openUTM returns blanks.
pronam_long
	Name of the computer on which the client or the printer is located. In UTM applications on BS2000 systems, pronam_long is always filled. The computer name in pronam_long is identical to the name specified during BCAM generation or in the RTF file for this computer. For an RSO printer pronam_long contains the value '*RSO'. In UTM applications on Unix, Linux and Windows systems, pronam_long contains blanks for a local client or a printer.