obj_type=KC_PTERM

To add a printer or client (i.e. a terminal, an UPIC client or a TS application) to the configuration, you must place the data structure kc_pterm_str in the data area in which you will pass the name, address and properties of the client or printer to UTM. The table below shows you how to supply the fields of the structure with data.

openUTM on Windows systems does not support any printers.

	Field name 1	Meaning
m	pt_name[8]	Name of the client or printer. The name may be up to 8 characters long. The symbolic name under which the client/printer is known to the transport system should be specified in pt_name. See section "Format and uniqueness of object names" for information on the format of the name and its uniqueness. Names of objects that have been deleted and which belong to the same name class may not be used. If your application contains an LTERM pool with connect_mode='M' (multi), then the triplet (pt_name, pronam,bcamappl) must not be the same as any naming triplet in the LTERM pool (= the triplet made up of the name of an LTERM partner in the pool, the processor name of the pool client and the BCAMAPPL name of the application which is used to establish the connection from the client). Otherwise, no other client will be able to connect via this LTERM pool.
		Special features of communication via the socket interface: If the connection between the communication partner and the UTM application is to be realized via the socket interface (SOCKET), and if the partner is to use a specific port number when establishing the connection, you must supply the value PRTnnnnn for pt_name, nnnnn being the port number in the remote system, via which the partner will establish the connection. If the partner is a UTM application, the port number cannot be supplied, because UTM does not set the port number itself. If it is only the local application that establishes the connection, and not the partner application, the name is only required internally, e.g. for administration purposes.
(m)	pronam_long[64]	Name of the computer on which the client/printer is located.
		The complete host name (FQDN) under which the host is known in the DNS has to be specified. The name can be up to 64 characters long. Instead of a 64 character FQDN name, a short local name (on BS2000 systems: BCAM name) of the partner computer may be used (max. 8 characters). In this case, it must be possible for the transport system to map the local name to an FQDN name or an IP address using external additional information (in BS2000 systems: FQDN file, in Unix, Linux or Windows systems: hosts file).
		If ptype='*RSO' on BS2000 systems, then pronam_long='*RSO' must be specified.
		If the connection to the partner is established through the socket interface (TCP-IP-APPLI, t_prot='T' protocol) you must specify the system’s symbolic address or the real host name in pronam_long.
		On Unix, Linux and Windows systems pronam_long may be specified only with ptype='UPIC-R', 'APPLI' or 'SOCKET'. openUTM uses the default value (blanks) for terminals and printers.
o	bcamappl[8]	Name of the UTM application through which the connection between the UTM application and the client/printer is to be established. The application name must have been statically generated using a BCAMAPPL command or during the KDCDEF generation by defining it in MAX APPLINAME.
		If the connection to the communication partner is to be established vie the SOCKET protocol, you must specify a BCAMAPPL name with t_prot='T'.
		Only on BS2000 systems: When ptype is not equal to 'APPLI', 'SOCKET' or 'UPIC-R', only the application name generated in MAX APPLINAME (default value) may be specified for bcamappl.
(m)	ptype[8]	Type of client/printer You will find a list of possible types in chapter "kc_pterm_str - Clients and printers" (section "BS2000 systems"). When ptype='APPLI', 'SOCKET' or 'UPIC-R', lterm must be specified.
		The specification of a ptype is mandatory for UTM applications on BS2000 systems.
		It is not permissible to specify ptype='PRINTER' on Windows systems.
o	ptype_fotyp[8]	Only relevant for printers (ptype = 'PRINTER') on Unix and Linux systems. In ptype_fotyp you specify the type of the printer (printertype).
o	ptype_class[40]	Only relevant for printers (ptype = 'PRINTER') on Unix and Linux systems. In ptype_class you specify the name of the printer group (printer class) to which the printer belongs. The printer group is determined during the generation on the Unix or Linux system.
(m)	lterm[8]	Name of the LTERM partner to be assigned to this client/printer. This parameter is optional for terminals and printers. An LTERM partner can be assigned to them at a later time using the administration functions. If the name of an LTERM partner is specified in lterm, then it must have been statically or dynamically added to the configuration before the terminal/printer.
		For UPIC clients and TS applications (ptype = 'UPIC-R', 'APPLI' or 'SOCKET') lterm is a mandatory parameter. The LTERM partner specified must be created in the same transaction as the client. See "Changing the configuration dynamically" for more information.
o	auto_connect	Specifies if the connection to the client/printer is to be established automatically when the application is started:
		'Y'	UTM is to try to establish a connection to the client/printer every time the application is started.
		'N'	UTM is not to try automatically to establish the connection.
		For UPIC clients, only auto_connect='N' is allowed.
o	state	Specifies if the client/printer is to be disabled at first after being added.
		'Y'	The client/printer is not be disabled (ON).
		'N'	The client/printer is to be disabled (OFF).
o	cid[8]	Only relevant for printers on BS2000, Unix and Linux systems. In cid you specify the printer ID (CID). The CID may contain a maximum of 8 characters. The CID is required if the printer is to be administered using a printer control LTERM. The printer control LTERM identifies the printer using the CID. The CID must be unique to the printer control LTERM.
o	map	Only relevant for TS applications (ptype = 'APPLI') or SOCKET-USP applications
		In map you specify whether or not UTM is to perform a code conversion (EBCDIC <-> ASCII) for the user messages exchanged between the communication partners. User messages are transferred at the KDCS interface with the calls for message handling (MPUT/FPUT/DPUT) in the message area.
		'U' (USER) UTM does not convert the data in the KDCS message area, i.e. the data of the message area are exchanged between the communication partners without any changes.
		'S', '1' , '2', '3', '4' 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.In this case, the specifications 'S' and 'S1' are synonymous. For more information on code conversion, please refer to the openUTM manual „Programming Applications with KDCS”; keyword „code conversion“.
o	termn[2]	Code for the type of client/printer (terminal mnemonic). The code is a maximum of 2 characters long. Default values for termn can be found in the table in chapter "kc_pterm_str - Clients and printers" (section "BS2000 systems" or "Unix, Linux and Windows systems").
o	protocol	Only on BS2000 systems: Specifies if the NEABT user utility protocol is to be used for connections to the client/printer.
		'N' (NO): Do not use NEABT.
		'S' (STATION): Use NEABT.
		For clients connected through a multiplex connection, you must set protocol = 'S'.
		For UPIC clients, RSO printers and TS applications connected via the socket interface, you must set protocol = 'N'. In these cases, protocol = 'N' is ignored.
o	usage_type	Only on BS2000 systems: Specifies whether a dialog partner or an output medium is to be configured. You can specify the following:
		'D' for a dialog partner 'O' for an output medium (printer, for example)
o	listener_port[5]	You specify in listener_port the port number in the remote system at which the partner application awaits requests for connection establishment from outside. All port numbers are allowed.
		On BS2000 systems, listener_port is only allowed in the case of ptype='APPLI' or 'SOCKET'. The specification is mandatory for ptype='SOCKET'. A port number not equal 0 may only be specified, if the local application specified in the bcamappl parameter was not generated with T-PROT=NEA.
		On Unix, Linux and Windows systems, listener_port is only relevant for t_prot='T' and 'R'.
o	t_prot	Only relevant for clients of the type pttype='APPLI', 'SOCKET' or 'UPIC-R' on Unix, Linux and Windows systems. You specify the address format of the client’s transport address. Possible values are:
		'R'	RFC1006, ISO transport protocol class 0 using TCP/IP and the RFC1006 convergence protocol (APPLI, UPIC-R)
		'T'	Native TCP-IP transport protocol for communication via the socket interface (SOCKET)
o	tsel_format	Only relevant for clients of the type pttype='APPLI', 'SOCKET' or 'UPIC-R' on Unix, Linux and Windows systems. You specify the format of the T-selector for the client address. Possible values are:
		'T': TRANSDATA format 'E': EBCDIC character format 'A': ASCII character format
o	idletime[5]	May only be specified for dialog partners. In idletime you define the maximum duration in seconds which UTM waits for a response from the client after the end of a transaction or after a sign-off (KDCSIGN). If the time is exceeded, the connection to the client is closed down. If the client is a terminal, message K021 is issued before the connection is closed down. The value for idletime must not be smaller than the timer value in kc_timer_par_str.termwait_in_ta_sec and kc_timer_par_str.pgwttime_sec (see "kc_timer_par_str - Timer settings").
		The purpose of this function is to improve data protection: If a user forgets to sign off when interrupting or finishing work at a terminal, the connection is automatically closed down when the idle time expires. This reduces the danger of unauthorized access.
		Maximum value: '32767' Minimum value: '60' The value 0 means wait without time limit. In the case of values smaller then 60 but not equal to 0, the value 60 is used.
		In the case of an invalid value, UTM sets idletime to the lowest value allowed and issues the return code KC_MC_OK with the subcode KC_SC_ INVALID_IDLETIME.
o	encryption_level	Only relevant for UPIC clients and also for some terminal emulations on BS2000 systems.
		In encryption_level you define the lowest encryption level for communication with a client, whether the encryption of messages is demanded by default or not which encryption level is demanded, or whether the client is a “trusted” client. Possible values are:
		'N'	(NONE) UTM does not demand data encryption. The client can only activate services for whose service TACs encryption was generated (see kc_tac_str.encryption_level in chapter "kc_tac_str - Transaction codes of local services"), if the client agrees encryption.
		'3'	(LEVEL 3) UTM demands that messages are encrypted 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.
		'4'	(LEVEL 4) UTM demands that messages are encrypted 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.
		'5'	(LEVEL 5)  UTM demands that messages are encrypted with encryption level 5. In other words, the messages are encrypted with the AES-GCM algorithm. The Agreement of the AES key is done with the Ephemeral Elliptic Curve Diffie-Hellman method (ECDHE) and an RSA Key with key length of 2048 bits.  Level 5 is only supported in openUTM on Unix, Linux, and Windows systems.
			Establishment of a connection to the client is rejected by UTM if the client does not support at least the specified encryption level (3, 4 or 5). Specifying encryption_level=3 ... 5 is meaningful only if the encryption funcions are available on your system. Otherwise the client cannot connect.
		'T'	(TRUSTED) The client is a trusted client. Messages exchanged between the client and the application are not encrypted. A “trusted client” can activate services for which the service TACs require encryption (generated with kc_tac_str.encryption_level ='2' or '5'; see "kc_tac_str - Transaction codes of local services"). Select this setting only if the client is not generally accessible and communication runs through a protected connection.
		The following applies for the individual client types with regard to the encryption level: Encryption Levels 3 to 5 are meaningful for remote UPIC clients (PTYPE=UPIC-R). Encryption Level 3 4 or 5 is replaced by TRUSTED by openUTM for local UPIC clients (PTYPE=UPIC-L) of an application on Unix, Linux or Windows systems. For HTTP clients which connect to the application via a transport system end point (BCAMAPPL) that is generated with T-PROT=(..., SECURE) the encryption level is always set to TRUSTED by UTM. If 3 ... 5 is specified for a partner of another type, the value is replaced by NONE by openUTM without issue of a message.
		For data to be encrypted on a connection to the client the corresponding RSA keys must be available. If the application is generated with OPTION GEN-RSA-KEYS=NO, KDCDEF does not create RSA keys, i.e. by default no RSA keys are available. It is however possible to transfer RSA keys by means of KDCUPD or to create them with KC_ENCRYPT. These keys can then be used by newly generated objects.
o	usp_hdr	This parameter is only significant for PTERMs with ptype='SOCKET'. It specifies the output messages for which UTM sets up a UTM socket protocol header on this connection. The 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 only and precedes the message with this.
		'N'	UTM does not create a UTM socket protocol header for any output message.

1	All fields in the data structure kc_pterm_str that are not listed and all fields that are not relevant to the operating system you are using are to be set to binary zero. The data structure is described in full in chapter "kc_pterm_str - Clients and printers".