To add a client or printer you must call KC_CREATE_OBJECT with object type KC_PTERM. To add an LTERM partner, you must specify object type KC_LTERM.
Printers are not supported in UTM applications running on Windows systems.
To enable you to connect a client or printer to the application, an LTERM partner must be assigned to it. If you specify this LTERM partner when adding a client or printer, the LTERM partner must either already exist in the configuration of that application or have been created in the same transaction prior to the client/printer. The following rule therefore applies:
LTERM partner (KC_LTERM) before client/printer (KC_PTERM) |
When adding clients/printers, you must distinguish between the following two cases:
terminals and printers
TS applications and UPIC clients
Terminals and printers
You can add terminals and printers to the configuration without assigning an LTERM partner directly to them, i.e. you do not have to specify an LTERM partner when adding them. You can then assign the LTERM partner to the terminal or printer at a later date. To do this, you are provided with the administration command KDCSWTCH and the call KC_MODIFY_OBJECT (object type KC_PTERM). Actual assignment must then take place in a separate transaction.
However, if you do specify an LTERM partner when adding a terminal or printer then, according to the rule stated above, this LTERM partner must already exist in the configuration of that application or have been created in the same transaction as the terminal or printer before the terminal or printer was added.
You can assign an LTERM partner to a printer even if the LTERM partner is already assigned to another printer. This does not cancel the previous assignment. One LTERM partner can be assigned to a number of printers. These printers then form a printer pool and process the message queue of the LTERM partner jointly.
You can only assign an LTERM partner which is not already assigned to another client. Any assignment to another terminal which already exists must be cancelled before the client is created in a separate transaction (with the administration command KDCSWTCH or the call KC_MODIFY_OBJECT).
If an LTERM partner is to be created explicitly with an automatic KDCSIGN to connect a terminal, you must, during the create operation, assign the user ID under which the automatic KDCSIGN is to be executed when a connection is being established. The user ID must already feature in the configuration before the LTERM partner is added, or have been created in the same transaction before the LTERM partner. Generally speaking, the following rule applies:
User ID (KC_USER) before LTERM partner (KC_LTERM) |
On BS2000 systems, as a general rule, the following applies:
The property usage_type (D for dialog partner or O for output medium) of the LTERM partner must match the value which you specify in usage when adding the client/printer.
If an LTERM partner is created for a printer which is to be administered by a print control LTERM (CTERM), you must assign the printer control LTERM when adding the LTERM partner. Before adding the LTERM partner, the printer control LTERM must either already be in the configuration of the application (created statically or dynamically) or in the same transaction as the LTERM partner, where it must have been created before the LTERM partner. The following rule applies:
Printer control LTERM (KC_LTERM) before LTERM partner (KC_LTERM) |
TS applications and UPIC Clients
You must assign an LTERM partner when creating TS applications or UPIC clients (APPLI, SOCKET, UPIC-R or UPIC-L type clients). This LTERM partner must be added in the same transaction as the client but before the client itself. In other words, the KC_CREATE_OBJECT call which creates the LTERM partner must be processed in the same transaction and before the KC_CREATE_OBJECT call which creates the client. In this instance, the rule to apply is as follows:
LTERM partner (KC_LTERM) before the TS application/UPIC client (KC_PTERM) |
The assignment of a client to an LTERM partner cannot be cancelled as long as the client remains in the configuration.
For the LTERM partner of a client of this type, openUTM requires a permanently assigned user ID, i.e. the connection user ID.
You can create a connection user ID explicitly, in which case it has to be included in the same transaction as the LTERM partner and the client. However, the user ID must be added to the configuration before the client. When assigning a user ID to an LTERM partner, you must distinguish between the following cases:
You are explicitly creating a user ID with the name of the LTERM partner. In this case, assignment is automatic when you add the LTERM partner.
You are creating a user ID with any name. In this case, you must explicitly enter the name when adding the LTERM partner (field kc_lterm_str.user_gen).
If you do not create the connection user ID explicitly, openUTM implicitly creates a user ID with the name of the LTERM partner.
The connection user ID is always reserved for this client. No other user or client can log on with the application under this user ID.
The user ID is assigned one of the reserved table spaces. If there are no more spare table spaces for this user ID, the LTERM partner and client are not added to the configuration. The KC_CREATE_OBJECT calls are then rejected.
In general terms, the following applies:
In applications with user IDs, you need three reserved table spaces to add a client of type APPLI, SOCKET or UPIC-R/UPIC-L: one for object type PTERM, one for object type LTERM and one for object type USER.
The following sequence must be observed:
User ID (KC_USER) before LTERM partner (KC_LTERM) before |
A connection user ID cannot be administered, i.e. once you have created the user ID, you can no longer modify its properties.
Example of creating a TS application or an UPIC client
A program which creates a TS application or an UPIC client and which explicitly assigns it a connection user ID must have the structure illustrated in the diagram below. The KDCS calls in angle brackets are optional. The individual KC_CREATE_OBJECT calls, in particular, can be located in various different KDCS programs. However, these programs must run in the same transaction (terminate program, for example with PEND PA).
#include <kcadminc.h> /* Record definitions */
INIT /* KDCS call for signing on with */
/* UTM
[MGET] /* KDCS call for reading the */
/* calling TACs and the */
/* passing parameters */
KC_CREATE_OBJECT with obj_type=KC_USER /* KDCADMI call for creating the */
/* user ID */
/* Possible error handling: the following KC_CREATE_OBJECT call should */
/* only be submitted if the previous call was error-free. */
KC_CREATE_OBJECT with /* KDCADMI call for creating the */
obj_type=KC_LTERM /* LTERM partner */
/* Possible error handling */
KC_CREATE_OBJECT with /* KDCADMI call for creating the */
obj_type=KC_PTERM /* client */
/* Possible error handling */
MPUT /* KDCS call for sending a message */
.... /* to the job-submitting service */
PEND FI / RE / SP / FC /* KDCS call to terminate the */
/* transaction */