LTERM - define an LTERM partner for a client or printer

The LTERM control statement allows you to define an LTERM partner as the logical access point for a client or printer of the application. Clients are terminals, UPIC clients and transport system applications (DCAM, CMX and socket applications, or UTM applications generated as transport system applications).

LTERM partners are used by clients and printers to establish a connection with the UTM application. They are assigned physical clients or printers using the PTERM statement. You can also define pools of LTERM partners; further information can be found in the description of the TPOOL statement in section "TPOOL - define an LTERM pool".

LTERM partners can also be predefined, i.e. they aren’t assigned to a client/printer yet. The LTERM partner -> PTERM assignment can be defined later on during operation using the KDCSWTCH administration command.

A separate LTERM statement must be issued for all clients defined in a PTERM statement.

Printers are not supported by openUTM on Windows systems.

LTERM

ltermname [ ,BUNDLE=master-lterm] [ ,GROUP=primary-lterm] [ ,KSET=keysetname ] [ ,LOCK=lockcode ] [ ,QAMSG={ YES | NO } ] [ ,QLEV=queue_level_number ] [ ,RESTART={ YES | NO } ] [ ,STATUS={ ON | OFF } ] [ ,USAGE={ D | O } ] [ ,USER=username ] additional operands on BS2000, Unix and Linux systems [ ,CTERM=ltermname2 ] [ ,PLEV=print_level_number ] additional operands on BS2000 systems [ ,ANNOAMSG={ Y | N } ] [ ,FORMAT= { + | * | # }formatname ] [ ,KERBEROS-DIALOG = { YES | N O } ] [ ,LOCALE=( [ lang_id ][,[ terr_id ][ ,ccsname ] ] ) ] [ ,NETPRIO={ MEDIUM | LOW } ]

The operands LOCK=, KSET=, USER= and ANNOAMSG= are only valid for clients; the operands CTERM= and PLEV= are only valid for printers.

ltermname	Name of the LTERM partner up to eight characters in length. ltermname is used to assign a client or printer to the LTERM partner in the PTERM statement. by the program units of the application to address clients, printers, and other TS applications (not server-to-server communication) assigned to the LTERM partner. The specified name must be unique and must not be assigned to any other object in name class 1. See also "Uniqueness of names and addresses".
ANNOAMSG=	(announce asynchronous message) This operand is only supported on BS2000 systems. This operand applies only for LTERM partners used by terminals (USAGE=D) to sign on to the UTM application.
Y	An asynchronous message to this terminal is announced in advance by outputting UTM message K012 in the system line. The user must then request the message using the UTM command KDCOUT. Default: Y
N	An asynchronous message to this terminal is sent immediately, i.e. without prior announcement.
BUNDLE=	master-lterm Name of a master LTERM in a LTERM bundle (connection bundle). By specifying master-lterm, this LTERM becomes a slave LTERM of the corresponding connection bundle. The master LTERM specified here must have been generated in a preceding LTERM statement. Do not assign a PTERM to a master LTERM. Connection bundles permit load balancing (see "LTERM bundle"). Connection bundles can be generated for APPLI or SOCKET connections (PTYPE operand of the corresponding PTERM statement). BUNDLE must not be specified together with GROUP or CTERM.
CTERM=	ltermname2 (control terminal) This operand is only supported on BS2000, Unix and Linux systems. This only needs to be specified for LTERM partners generated for printers (USAGE=O). ltermname2 is the name of an LTERM partner (up to eight characters in length) which was configured as a printer control LTERM (LTERM ...,USAGE=D). The printer control LTERM can be assigned one or more LTERM partners which were configured for printers. It is used to manage printers, print jobs, and printer queues. Default: Blanks, i.e. no printer control LTERM
GROUP=	primary-lterm Name of a primary LTERM. By specifying primary-lterm, this LTERM becomes an alias LTERM of the corresponding primary LTERM. They define a LTERM group. In a LTERM group you assign several LTERMs to one connection (see "LTERM groups" ). The primary LTERM specified here must have been generated in a preceding LTERM statement. The primary LTERM must be a normal LTERM assigned to a PTERM with PTYPE=APPLI or PTYPE=SOCKET or the master LTERM of a connection bundle. Do not assign a PTERM to an alias LTERM. GROUP must not be specified together with BUNDLE or CTERM.
FORMAT=	This operand is only supported on BS2000 systems. Designates the start format of the LTERM partners. Start formats can only be defined for terminals. It only makes sense to specify a start format if the application is generated without user IDs or if you are using your own signon service. If the LTERM partner is assigned to a UPIC client, then specifying a start format has no effect. If the application is generated without user IDs, this format is output instead of UTM message K001. Following a terminal-specific restart, the start format is not displayed, rather the KDCDISP command is executed. If the application is generated with user IDs, the name of the start format can be queried in the first part of the sign-on procedure using the SIGN ST call. If you do not use your own sign-on procedure, you cannot use the LTERM-specific start format. The sign of the format consists as follows: +, * or # followed by an alphanumeric name (formatname) up to seven characters in length. #formats can only be used in the context of a sign-on procedure. The terms have the following meanings:
+	When the next MGET call of the program unit is issued, each entry in a format field is preceded by 2 bytes for the attribute field in the KDCS message area, i.e. the field properties can be modified by the program unit. The format name at the KDCS interface is +formatname.
*	When the next MGET call of the program unit is issued, the entry in a format field is not preceded by any bytes for an attribute field, i.e. the field properties cannot be modified by the program unit. The format name at the KDCS interface is *formatname.
#	This identifies a format with extended user attributes. The field properties and global format properties can be modified by the program unit. The format name at the KDCS interface is #formatname. Default: no start format
KERBEROS-DIALOG =
	This operand is only supported on BS2000 systems.
YES	A Kerberos dialog is performed when a connection is established for terminals that support Kerberos and that connect to the application directly via this LTERM partner (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 unless a user subsequently signs on with an ID card. In this event, the Kerberos information is overwritten by the ID card information. If the maximum of the lengths generated for MAX PRINCIPAL-LTH and MAX CARDLTH is zero, a warning message is issued.
NO	No Kerberos dialog is performed. Default.
KSET=	keysetname This applies only to clients generated as dialog partners (USAGE=D). keysetname is the name of a key set defined using the KSET statement and assigned to the LTERM partner ltermname. keysetname may be up to 8 characters long. A maximum of one key set can be assigned to each LTERM partner. This defines the access permissions for this LTERM partner with respect to using the services of the application and remote services (LTACs) generated in this application. This LTERM partner 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. The lock/key code concept and the access list concept are described in detail in the openUTM manual “Concepts und Functions”. An introduction to data access control can be found in section "Lock/key code concept". Services whose TACs are not secured with codes can be called by the user or the client program without restriction. In the case of an application in which user IDs have been defined and for which data access control is not required for terminals, you can assign all key codes to the terminals as follows: LTERM ...,KSET=MASTERSET KSET MASTERSET,KEYS=MASTER Default: No key set
LOCALE=	(lang_id,terr_id,ccs_name) This operand is only supported on BS2000 systems. Language environment of the client that signs on to the application via this LTERM partner.
lang_id	Freely selectable language identifier for the client, up to two characters in length. The language identifier may be queried by the program units of the application, so that messages can be sent to the terminal in the communication partner’s language.
terr_id	Freely selectable territorial identifier for the client, up to two characters in length. The territorial identifier may be queried by the program units of the application, so that messages can be sent to the terminal taking into consideration any special territorial features of the communication partner’s language.
ccsname	(coded character set name) Name of an extended character set (CCS name) up to eight characters in length. The specified CCS name must belong to one of the EBCDIC character sets defined under the BS2000 system (see also the XHCS User Guide). The character set must be compatible with an ISO character set supported by the terminal assigned to this LTERM partner. During generation, KDCDEF cannot check the validity of the CCS name under the BS2000 system or the compatibility condition. If you specify a CCS name which is not defined in XHCS, this results in a PEND ER when an attempt is made to establish a connection via this LTERM partner during runtime. The character set with the specified CCS name is used for: outputting dialog messages on 8-bit terminals if the application is generated without user IDs or if a user is not signed on to the terminal, and another CCS name is not explicitly selected using an edit profile or a format. outputting asynchronous messages on 8-bit terminals if another CCS name is not explicitly selected using an edit profile or a format. Default: Locale defined in the MAX statement
LOCK=	lockcode This applies only for clients (USAGE=D). Lock code assigned to the LTERM partner as a logical numerical lock. lockcode is a number between 1 and the maximum value permitted by the application (MAX ...,KEYVALUE=number). It is only possible to sign on to this LTERM partner under a UTM user ID (USER) for which a key set has been generated with a key code that contains the lock code of the LTERM partner. If the application is generated without user IDs (no USER statement), the LOCK= operand is ignored. Default: 0, i.e. no lock code Maximum value: Value of MAX ...,KEYVALUE=number
NETPRIO=	This operand is only supported on BS2000 systems. Transport priority to be used on the transport connection assigned to this LTERM partner. NETPRIO has no significance for LTERM partners that are assigned to a PTERM using PTYPE=SOCKET or PTYPE=*RSO. Default: MEDIUM for clients LOW for printers
PLEV=	print_level_number (print level) This operand is only supported on BS2000, Unix and Linux systems. This applies only for printers. The PLEV= operand allows you to access printers from various UTM applications (printer sharing). The connection between the UTM application and the printer exists only while the print job is being transferred, thus allowing other applications to establish a connection as required. This operand defines the number of printer messages at which openUTM attempts to establish a connection with the printer. openUTM continues to collect these messages until the threshold value defined with PLEV= is reached. It then establishes a logical connection to the printer. The connection is shut down again as soon as there are no further messages for this printer. Another application can then output messages to the printer if necessary. If the client is assigned a printer pool, openUTM attempts to establish a connection to all printers in the pool as soon as the threshold value is reached. When all messages have been sent, the connection to all printers in the pool is shut down again. If the connection to the printer is shut down (e.g. by administration) even through the threshold value PLEV= is still exceeded, openUTM attempts to reestablish the connection at intervals defined in MAX ...,CONRTIME=time. If PLEV=0 is specified, the connection is not shut down even if there are no further output messages. If PLEV>0 is specified, the operands RESTART=NO or USAGE=D must not be specified for the LTERM partner. On BS2000 systems QAMSG=NO must also not be specified. If PLEV>0 is specified, the operand CONNECT=YES of the associated PTERM statement has no effect. Default value: 0 Minimum value: 0 Maximum value: 32767 If you exceed the maximum value, KDCDEF automatically resets your entry to the default value without outputting a UTM message.
QAMSG=	(queue asynchronous message)
YES	An asynchronous message (FPUT job) to the client or printer is buffered by openUTM in the message queue of this LTERM partner, even if the client or printer is not connected to the application. Default: If RESTART= YES
NO	An FPUT job sent to this client or printer is rejected with the return codes KCRCCC=44Z and KCRCDC=K705 if the client or printer is not connected to the application. Default: If RESTART=NO
QLEV=	queue_level_number (queue level) Specifies the maximum number of asynchronous messages simultaneously buffered by openUTM in the message queue of the LTERM partner. If this threshold value is exceeded, openUTM rejects all further FPUT or DPUT calls for this LTERM partner with 40Z. QLEV= can be used to control the size of the page pool more effectively. This is because the number of asynchronous messages cannot exceed the queue_level_number. Default value: 32767 Minimum value: 0 Maximum value: 32767 (i.e. unlimited) If you exceed the maximum value, KDCDEF automatically resets your entry to the default value without outputting a UTM message. You should not specify a QLEV < PLEV for a printer, as this would mean that the connection to this printer would have to be established by administration.
RESTART=	Processing of asynchronous messages when the client link is disconnected.
YES	When the link to the client assigned to this LTERM partner is disconnected, asynchronous messages are retained. If user IDs are not generated in this application, openUTM performs an automatic service restart for this LTERM partner. Default: YES
NO	When the link to the client assigned to this LTERM partner is disconnected, openUTM deletes all asynchronous messages in the message queue of the LTERM partner. If these are messages of a UTM message complex, the negative confirmation job is activated. It is possible to relieve the load on the page pool by specifying RESTART=NO. If QAMSG=YES is specified, you must not specify RESTART=NO. If user IDs are not defined in the application, openUTM does not perform an automatic service restart for clients or printers, i.e.: If the connection is shut down by KDCOFF, if it is lost, or if the application is terminated normally, the service is rolled back to the last synchronization point and terminated. The event exit VORGANG is then called with KCKNZVG=D (=Disconnect). During a UTM warm start following abnormal termination of the application, an open service for this LTERM partner is terminated without calling the event exit VORGANG. Following connection setup, KDCDISP/KDCLAST behaves in the same way as after regeneration, i.e. the UTM message K020 NO MESSAGE(S) PRESENT is output.
STATUS=	Status of the LTERM partner following connection setup. This can be modified during runtime using the administration command KDCLTERM.
ON	The client or printer assigned to this LTERM partner is not locked, i.e. you can work with it as soon as the connection has been established. Default: ON
OFF	The client or printer assigned to this LTERM partner is locked.
USAGE=	Type of LTERM partner
D	The LTERM partner is configured as a dialog partner. Both the client and the application can send messages via the connection between the client and the local application. Default: D
O	The LTERM partner is configured for an output medium. It is only possible to send messages from the application to the printer or TS application etc.
USER=	username This only applies if the LTERM has been configured as a dialog partner (USAGE=D). Depending on the type of the assigned client, this operand has the following effect: If a terminal is assigned to the LTERM partner, openUTM executes an automatic KDCSIGN for the user ID username when establishing a logical connection between the client assigned to this LTERM partner and the UTM application. Note that when the automatic KDCSIGN is used, access protection is limited. You should not specify this operand unless you are certain that an authorized user is working under this user ID at this client. After the logical connection is set up, the client is in the same state as if the user username executed the KDCSIGN command (BS2000 systems) or signon check (Unix, Linux and Windows systems) successfully. The user ID must be defined using the USER statement. If the LTERM partner is assigned a client of type APPLI or UPIC, then the user ID username is reserved for this client (as the connection user ID). The client is signed on under this user ID when the connection is established. Another client or terminal user cannot sign on to the UTM application with this user ID. If a user ID with the name of the LTERM partner was generated explicitly by means of a USER statement, openUTM assigns this user ID exclusively to the LTERM partner. If the LTERM partner is to send administration calls to the application, then a user ID with administration authorization must be specified if the client is not signed-on using a real user ID. If transaction codes are to be called from this client that are protected by lock codes, then this user ID must be assigned an appropriate key set. If no user ID was specified, then KDCDEF implicitly creates a user ID with the name of the LTERM partner and the value defined in LTERM ...,RESTART=. Default: No automatic KDCSIGN