USER - define a user ID

The USER control statement allows you to define user IDs for the UTM application. These are then used by users and client programs to sign on to the application. The following can be defined for user IDs:

• the authentication procedure (password, magnetic strip card on BS2000 systems and Unix)

• complexity level and period of validity of password

• access rights (lock/key code or access list concept)

• administration authorization

• the user status

• properties of the USER queue that belongs to the user ID

• the start format

• UTM SAT administration authorization (BS2000 systems)

• the user-specific language environment (BS2000 systems).

• Method and type of authentication (BS2000 systems: password, magnetic strip card, Kerberos principal)

At least one user ID must be assigned administration authorization in order to manage the application. Administration authorization can be granted to several user IDs, thereby enabling several users to simultaneously call administration functions under the respective user ID. On BS2000 systems the same is true for the UTM SAT administration authorization and calling SAT preselection functions.

An application can also be generated without user IDs. In this case, users are not required to identify themselves, and openUTM uses the name of the respective client internally as the user ID. All users can thus issue administration commands and on BS2000 systems UTM SAT administration commands. If you work without user IDs, openUTM will not be able to use some data protection functions.

USER

username [ ,KSET=keysetname ] [ ,PASS={ ( password,DARK) |            ( *RANDOM,DARK ) |             password       |             *RANDOM } ] [ ,KSET=keysetname ] [ ,PERMIT={ NONE |ADMIN | SATADM1  | ( ADMIN,SATADM)1  } ] [ ,PROTECT-PW=( [ length ]                ,[ { NONE | MIN | MED | MAX } ]                ,[ maxtime ]                 ,[ mintime ] ) ]2 [ ,QLEV5=queue_level_number ] [ ,QMODE = { STD | WRAP-AROUND } ] [ ,Q-READ-ACL=read-keysetname ] [ ,Q-WRITE-ACL=write-keysetname ] [ ,RESTART={  YES | NO } ] [ ,STATUS={ ON | OFF } ] additional operands on BS2000 systems [ ,CARD=( position,characterstring ) ] [ ,FORMAT= { + | * | # }formatname ] [ ,LOCALE=( [ lang_id ][,[ terr_id ][ ,ccsname ] ] ) ] [ ,PRINCIPAL=characterstring ] [ ,SATSEL={ NONE | BOTH | SUCC | FAIL } ]

¹ only on BS2000 systems

² Commas at the end can be omitted, i.e. you can specify (8,NONE) instead of (8,NONE,,).

username	UTM user ID specified by the user when signing on to the application, or by a client when opening a conversation with the application. username can be up to eight characters in length. (See also the operand USER=username in the LTERM statement starting in section  "LTERM - define an LTERM partner for a client or printer"). The specified name must be unique and must not be assigned to any other object in name class 2. See also section "Uniqueness of names and addresses". If username is identical to the name of an LTERM that is assigned to a PTERM with PTYPE=APPLI, SOCKET or UPIC-R, you must bear in mind the notes detailed under LTERM.
CARD=	This operand is supported on BS2000 systems only. specifies whether a magnetic strip card is to be checked when signing on to the application under this user ID, and defines the ID card information to be verified. Enter a subfield of the information stored on the magnetic strip card, which is to be checked by openUTM. The following must apply for this parameter: pos + length(string) -1 <= MAX CARDLTH Otherwise the parameter is ignored. You cannot specify PRINCIPAL= if you have specified CARD=.
position	Start position of the ID card information to be checked: position = 1 corresponds to the first byte, etc.
characterstring	When signing on to the application, openUTM checks whether the ID card information starting at the defined position begins with this character string. characterstring can be specified in the following format: as a hexadecimal character string; hexadecimal characters always occur in pairs, e.g. X’DDEF’ as an alphanumeric character string, e.g. FRIDOLIN or C’@FRIEDEL’. Special characters must be entered in the format C’...’ or X’...’. Default: No ID card check performed when signing on to the application Maximum length: 100 bytes (see also MAX ...,CARDLTH=)
FORMAT=	This operand is supported on BS2000 systems only. Format identifier for a user-specific start format. This start format is automatically output after each successful attempt to sign on to the application, provided an open service does not exist for this user. However, if an open service exists for the user (USER) following a successful sign-on check, the start format is not displayed, rather the last dialog screen appears (service restart). If you use your own sign-on procedure, the name of the user-specific start format may be queried in the second part of the sign-on procedure using the SIGN ST call. The format identifier composes 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 identifier at the KDCS interface is thus +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 in the KDCS message area, i.e. the field properties cannot be modified by the program unit. The format identifier at the KDCS interface is thus *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 identifier at the KDCS interface is thus #formatname. Default: No start format
KSET=	keysetname Name of the key set assigned to the user ID. The key set is defined with the KSET statement. A maximum of one key set can be assigned per USER. The key set defines the access permissions for this user ID with respect to using the services of the application and remote services (LTACs) generated in this application. This user ID 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 user ID and the key set of the LTERM partner under which sign-on using this user ID 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 both described in detail in the openUTM manual “Concepts und Functions”. An introduction to data access control can be found as of "Data access control". Services whose service TACs are not secured with codes can be called by the user or the client program without restriction. Further information on the lock/key code concept can be found in the openUTM manual “Concepts und Functions”. Default: No key set, i.e. the user can only access clients and LTERM partners that have not been secured with lock codes.
LOCALE=	(lang_id,terr_id,ccsname) This operand is supported on BS2000 systems only. Language environment of the user
lang_id	Freely selectable language identifier for the UTM user ID, 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 by the program units to the user ID in the user’s language.
terr_id	Freely selectable territorial identifier for the UTM user ID, up to two characters in length. The territorial identifier may be queried by the program units of the application, so that any special territorial features of the user’s language can be taken into consideration in messages to the user.
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"). During generation, openUTM cannot check the validity of the CCS name under the BS2000 system. The character set with the specified CCS name is used for outputting dialog messages, provided the user is signed on to an 8-bit terminal and another CCS name is not explicitly selected using an edit profile or a format. The character set must be compatible with an extended ISO character set supported by the terminal. During generation, openUTM cannot check this compatibility condition, i.e. incorrect entries cannot be intercepted by KDCDEF. Default: Locale of the application defined in the MAX statement is used if USER ...,LOCALE is not specified.
PASS=	Password up to 16 characters in length which must be specified by the user during the sign-on check. This password must comply with the level of complexity defined in the PROTECT-PW= operand. PASS= may not be specified together with PRINCIPAL=. If you enter *RANDOM here, a secret random password is generated for the user ID. A valid password must then be transferred to the user ID using the KDCUPD tool or by means of administration. Passwords created in this way are not subject to the conditions set in PROTECT-PW=. Make sure that at least one user ID is configured with administration authorization by the startup time at the latest. This user ID must not be assigned a password created using *RANDOM, as otherwise the application cannot be administered. BS2000 systems: password can be entered in the following format: hexadecimal, e.g. X’DDFF’ as a constant, e.g. C’@LKE’ as a printable alphanumeric character string, e.g. NORBERT. Unix, Linux and Windows systems: The password can be entered in the form of a printable alphanumeric character string, e.g. UTM4EVER or C’UTM_ever’. Default: 16 blanks (i.e. no password) The parameters have the following effects on the signon procedure:
password     *RANDOM	BS2000 systems: Standard sign-on dialog: The user must enter ’KDCSIGN username,password’ to sign on to the application. Sign-on procedure: The user ID and password must be transferred to openUTM using the SIGN ON call. Unix, Linux and Windows systems: Standard sign-on dialog: To sign on to the application, the user first enters username. openUTM then prompts the user to enter the password. Sign-on procedure: In an intermediate dialog, openUTM prompts the user to enter the password as in the standard sign-on procedure.
(password, DARK)     (*RANDOM,DARK)	BS2000 systems: Standard sign-on dialog: To sign on to the application the user first enters ’KDCSIGN username’. openUTM then prompts the user to enter the password in a blanked-out field on the screen. Sign-on procedure: In an intermediate dialog, openUTM prompts the user to enter the password in a blanked-out field. Unix, Linux and Windows systems: Standard sign-on dialog: To sign on to the application, the user first enters username. openUTM then prompts the user to enter the password. Sign-on procedure: In an intermediate dialog, openUTM prompts the user to enter the password as in the standard sign-on procedure.
PERMIT=	Administration authorization level of the user within the local application
ADMIN	The user can execute administration functions under this user ID.
NONE	The user must not execute any administration functions. Default: NONE On BS2000 systems the user also must not execute any SAT preselection functions.
SATADM	The user can execute SAT preselection functions (UTM SAT administration).
(ADMIN,SATADM)	The user can execute administration and SAT preselection functions.
PRINCIPAL=	characterstring This operand is supported on BS2000 systems only. Authentication of the user is to be performed using Kerberos. It is only possible to authenticate users using Kerberos if the user signs in directly (not via OMNIS) at a terminal that supports Kerberos. openUTM stores the Kerberos information in the maximum of the lengths generated for MAX PRINCIPAL-LTH and MAX CARDLTH. If the Kerberos information is longer, it is truncated and stored in this length. The KDCS call INFO (KCOM=CD) enables a program unit to read this information as long as the user is signed in on this client. Specifying PRINCIPAL excludes the possibility of specifying the parameters CARD and PASS. characterstring must be specified as follows as an alphanumeric string enclosed in single quotes: C'windowsaccount@NT-DNS-REALM-NAME' windowsaccount: Domain account of the user NT-DNS-REALM-NAME: DNS name of the Active Directory domain. This name is a fixed value for every Active Directory domain and was assigned when the Kerberos key was set up. The length of the character string passed must not be greater than the value specified for MAX PRINCIPAL-LTH. Otherwise the parameter is ignored. openUTM stores the Kerberos information in the length resulting from the maximum length 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 as long as the user is signed in on this client. Maximum length: The value generated with MAX ...,PRINCIPAL-LTH. See "MAX - define UTM application parameters". Default: No Kerberos authentication
PROTECT-PW=	Specifies the minimum length, level of complexity, and minimum and maximum validity period of the user password. The values defined for PROTECT-PW must be taken into consideration when specifying the password in the PASS= operand. They are checked by openUTM when the password is changed by the administrator (KDCUSER administration command, see the openUTM manual “Administering Applications”) or by a program unit (SIGN CP call).
length	Minimum number of characters that must be contained in the password. The administrator can only delete the user password if the value 0 is specified for length. Default: 0 Minimum value: 0 for NONE or if a level of complexity is not defined 1 for MIN 2 for MED 3 for MAX Maximum value: 16
NONE/MIN/MED/MAX
	Level of complexity of the password
NONE	The password can be any character string. Default: NONE
MIN	In the password, up to two consecutive characters may be identical. The minimum length of the password is one character.
MED	In the password, up to two consecutive characters may be identical. The password must contain at least one letter and one number. The minimum length of the password is two characters.
MAX	In the password, up to two consecutive characters may be identical. The password must contain at least one letter, one number, and one special character. The minimum length of the password is three characters. Special characters are all characters other than a-z, A-Z, 0-9, and blanks.
maxtime	Maximum validity period: maxtime specifies the maximum number of days for which the password is valid. If a validity period is specified, then the validity of the password expires at the end of the last day of the specified validity period. For instance, if the validity period is one day, the password ceases to be valid at 24:00 hours on the following day. If the application is generated with SIGNON GRACE=YES, when the application is regenerated the password is set to “expired”, the user must then assign a new password the first time they sign on. If the password expires, then the next action taken depends on how the UTM application is generated: With grace sign-ons (SIGNON GRACE= YES) The user can and must change the password the next time the they sign on, as long as the sign-on service of the application offers them this opportunity. If this is not the case, the password must be modified by administration otherwise the user will no longer be able to sign on under this user ID. This may occur, for example, with users that sign on via TS applications and UPIC clients without sign on services or via an OSI-TP partner. Without grace sign-ons (SIGNON GRACE= NO) openUTM rejects a sign-on attempt with message K120. The administrator must then change the password. With maxtime = 0 the validity period of the password is not restricted. Default: 0 (validity period not restricted) Maximum value: 180 Minimum value: 0
mintime	Minimum validity period: You specify the minimum validity period of the password in days in mintime. Once the user has changed the password, the user may only change the password again after the minimum validity period has expired. By specifying mintime > 0 you can prevent a user whose password has expired from changing his or her password twice in a row to set the password back to the original (= expired) password. If a minimum validity period of one day is specified, then the password may be changed no earlier that at 12.00 midnight of the following day (local time of the generation). The user can always change the password after the administrator has changed the password and after a new generation, regardless of whether the minimum validity period has expired or not. mintime must not be larger than maxtime (maximum validity period). If mintime=0 is specified, then the minimum validity period of the password is not restricted. Default: 0 (no limit) Minimum value: 0 Maximum value: 180
QLEV=	queue_level_number (queue level) Specifies the maximum number of asynchronous messages that may be buffered in the message queue of the user (= USER queue). QLEV can be used to make sure that the page pool is not overloaded with messages for this USER. openUTM only takes asynchronous jobs into account at the end of the transaction. It is thus possible that the maximum number of messages for a message queue as specified in QLEV may be exceeded if several messages are created for this queue during a single transaction. If the threshold value has been exceeded, then the behavior will depend on the value set in the operand QMODE=, see below. With QLEV=0 no messages may be saved in the queue and with QLEV=32767 the queue length is not restricted. Default: 32767 Minimum value: 0 Maximum value: 32767 If a value is specified that is greater than the maximum, this is set back to the default in the KDCDEF run. No message is issued.
QMODE =	(Queue Mode) Determines the behavior of openUTM in the event that the maximum permitted number of messages that may be saved in the USER queue has been reached and thus the queue level (QLEV= operand) has also been reached.
STD	When the queue level is reached openUTM rejects all additional messages for the queue with negative return code (40Z for DPUT).
WRAP-AROUND	openUTM continues to accept messages for the queue, even if the queue level has been reached. When a new message is written to the queue, openUTM deletes the oldest message in the queue and replaces it with the new one. Default: STD
Q-READ-ACL=	read-keysetname Specifies the read and delete rights for external users in the USER queue. In read-keysetname you must enter a key set that has been generated using a KSET statement. If you enter Q-READ-ACL=, an external user (!= username) is only permitted read access to the queue if both the key set of their user ID and the key set of the LTERM partner via which the user is signed on contain at least one of the key codes contained in the key set read-keysetname. The owner (username) of the USER queue always has read and delete rights to their queue, even if the rights are restricted using Q-READ-ACL. If you do not specify Q-READ-ACL=, all users have both read and delete rights in the queue. Default: no key set
Q-WRITE-ACL=	write-keysetname Specifies the write rights for external users in the USER queue. In write-keysetname you must enter a key set that has been generated using a KSET statement. If you enter Q-WRITE-ACL=, an external user (!= username) is only permitted write access to the queue if both the key set of their user ID and the key set of the LTERM partner via which the user is signed on contain at least one of the key codes contained in the key set write-keysetname. The owner (username) of the USER queue always has the write rights to their queue, even if the rights are restricted using Q-WRITE-ACL. If you do not specify Q-WRITE-ACL= all users have both write rights in the queue. Default: no key set
RESTART=	This specifies whether openUTM is to save the service data for a user ID so that a service restart will be possible on the next sign-on under this user ID.
YES	The service context belonging to this user ID is saved. This means that a service restart can be performed for users who sign on using this user ID if an open service exists for the user ID. With a service restart, the type of the client and possibly the generated sign on service may play a role. Additional information can be found in section "Generating a restart" and in the openUTM manual “Using UTM Applications”. Default: YES
NO	The service context belonging to this user ID is not saved, no service restart is possible, If the connection is shut down during operation 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 UTM user is terminated without calling the event exit VORGANG. Following connection setup, KDCDISP/KDCLAST behaves in the same way as after regeneration. If RESTART=NO is specified together with SIGNON MULTI-SIGNON=YES, several users can sign on simultaneously to openUTM under this user ID, but only one user can sign on to the terminal. Conversely, it is possible for any number of client programs can sign on simultaneously. Explicitly generated connection user IDs to UPIC clients are always generated with RESTART=NO (without any message) .
SATSEL=	This operand is supported on BS2000 systems only. SAT logging mode for this user If SAT logging is activated (MAX SAT=YES), all events triggered by this user are logged as defined in this operand. The SATSEL control statement is used to define the general SAT logging mode for all TACs and users. This can be supplemented by the SATSEL operand of the USER statement, which allows you to define user-specific logging. If the logging of an event class is prohibited in the SATSEL statement, events of this class are not logged. (For information on the link between the EVENT-, TAC- and USER-specific log settings, see the openUTM manual “Using UTM Applications on BS2000 Systems”.) SATSEL can be generated even if SAT logging is deactivated (MAX statement with SECLEV=NO and SAT=OFF). In this case, the statements are not effective when the application is started, but SAT logging is predefined. When required, SAT logging can then be activated during operation (UTM SAT administration command KDCMSAT, see the openUTM manual “Using UTM Applications on BS2000 Systems”).
NONE	A user-specific SAT logging mode is not defined. Default: NONE
BOTH	Both successful and unsuccessful events are logged.
SUCC	Only successful events are logged.
FAIL	Only unsuccessful events are logged.
STATUS=	Status (locked or unlocked) of the user ID when the application is started.
ON	The user ID is unlocked. Default: ON
OFF	The user ID is locked. It cannot be used by a user or client to sign on to the application until it has been released by the administrator. User IDs that are implicitly or explicitly assigned to an UPIC client or a client of a TS application via an LTERM statement (LTERM ...,USER=) are always locked. They cannot be authorized by the UTM administrator. These user IDs are called connection user IDs.