obj_type=KC_USER

To create a new user ID you must place the data structure kc_user_str in the data area.

A permanent queue is available to every user ID. This queue is addressed using the name of the user ID. The access of other users to this USER queue is controlled by means of the values in the q_read_acl and q_write_acl fields. The maximum number of messages that can be buffered and the response of UTM when this value is reached is determined by the values in the qlev and q_mode fields.

The table below shows you how to supply the fields of the data structure with data.

	Field name 1	Meaning
m	us_name[8]	Name of the user ID. It can be up to 8 characters long. If the name of the user ID matches the name of an LTERM partner to which a UPIC client or TS application, but no user ID, has been assigned, then no user may sign on to the UTM application using this user ID. UTM then assigns this user ID exclusively to the client. See section "Format and uniqueness of object names" for more information on the format and uniqueness of the name. Names of objects of the same name class that have been tagged for delayed delete with KC_DELAY cannot be used.
o	kset[8]	Key set of the user ID. The key set must have been created dynamically beforehand or generated statically. The key set determines the access privileges of the user/client that signs on to the application using this user ID.
o	state	Specifies if the user ID is to be disabled or not. No user/client can sign on to the application using a disabled user ID. The user ID must be released (enabled) explicitly by the administrator.
		'Y': The user ID is not to be disabled (ON). 'N': The user ID is to be disabled (OFF).
o	card_position[3] card_string_lth[3] card_string_type card_string[200]	Only on BS2000 systems: These fields are only relevant if access to the application for this user ID is only possible using a magnetic stripe card. The fields specify which subfield of the identification information on the magnetic stripe is to be checked and what information must be contained therein. Specifying card... excludes the possibility of specifying principal.
		You must specify the following information in these fields:
		card_position Number of the byte on the magnetic stripe card where the information to be checked begins. card_string_lth Length of the identification information to be checked in bytes. Maximum value: '100', Minimum value: '1'
		card_position and card_string_lth must define a section of the field of identification information within the area defined by the MAX CARDLTH generation parameter.
		card_string_type Encoding format of the identification information to be checked:
		'X'	The identification information is passed as a hexadecimal string.
		'C'	The identification information is passed as a character string.
		card_string Character string that must be contained in the section to be checked on the magnetic stripe card. Only the length of the contents specified in card_string_lth is relevant if card_string_type = 'C'. For card_string_type = 'X', the length of the relevant data is equal to 2 ∗card_string_lth.
		The union kc_string is provided for passing identification information (see "kc_user_str, kc_user_fix_str, kc_user_dyn1_str and kc_user_dyn2_str user IDs").
o	password16	Password for this user ID. The password can be up to 16 characters long. The password specified must correspond to the complexity level specified in protect_pw_compl and protect_pw16_lth. You must also specify how UTM is to interpret the data in password using the password_type field. The password must consist of characters which are permitted in the UTM application, see the openUTM manual “Generating Applications”, USER statement. On BS2000 system, specifying password16 excludes the possibility of specifying principal.
		The union kc_pw16 is provided for passing the password.
		union kc_pw16 char x[32]; /* for X'...' */ char c[16]; /* for C'...' */
		In UTM applications on BS2000 systems you can specify the password either as a character string or as a hexadecimal string. For a hexadecimal password (password_type='X'), each half byte is displayed as a character. If you specify a password containing less than 16 characters, then you must pad password16 to the right with spaces (password_type= 'C'), or with the hexadecimal value for a space (password_type='X').
		In UTM applications running on Unix, Linux or Windows systems you must always pass the password as a character string (field password16.c). If you specify a password containing less than 16 characters, then you must pad password16.c to the right with blanks.
		You must specify password16 if password_type ='C' or 'X'. You may not specify password16 if password_type = 'R' or 'N'.
		If a user ID is to be created without a password, then you cannot specify anything in password16 and password_type. For protect_pw_compl, you must set it to '0' and for protect_pw16_lth to '00' (default).
o	password_type	In password_type you must specify how the password in password is to be interpreted. The following entries are possible:
		'C'	The password in password is interpreted as a character string.
		'X'	The password in password is interpreted as a hexadecimal password. Only allowed for user IDs in a UTM application on a BS2000 system.
		'N'	No password may be specified i0n password.
		'R'	The password generated is a random password. Before the user thus generated can sign on, the administrator must explicitly reset the password.
o	password_dark	Specifies if a password is to be hidden when entered at a terminal.
		'Y'	After KDCSIGN, UTM requests the user in an interim dialog to enter the password in a darkened field.
		'N'	The user conveys the password directly at KDCSIGN. The password is visible on the screen during sign-on (default value).
		You can also set password_dark='Y' if you have not specified a password. If the user ID is assigned a password later (with KC_MODIFY_OBJECT, for example), the password entry will be darkened.
		Note In applications running on Unix, Linux or Windows systems, password entry is never darkened.
o	format_attr format_name[7]	Only on BS2000 systems: With the aid of this field you can assign the user ID a user-specific start string. You must specify format_name and format_attr.
		A requirement for assigning a start format is that a formatting system must have been generated (KDCDEF command FORMSYS). If the start format is a #Format, then a sign-on service must also have been generated.
		In format_attr you specify the format key of the start format:
		'A' 'N' 'E'	for the format attribute ATTR (+Format). for the format attribute NOATTR (*Format). for the format attribute EXTEND (#Format).
		See "kc_user_str, kc_user_fix_str, kc_user_dyn1_str and kc_user_dyn2_str user IDs" (format_attr, format_name) for the meaning of the format attributes.
		In format_name you specify the name of the start format. The name can be up to 7 characters long and may only contain alphanumeric characters.
o	locale_lang_id[2] locale_terr_id[2] locale_ccsname[8]	Only on BS2000 systems: Language environment (locale) of the user ID. The language environment is relevant if messages and notifications from the application are to be output in different languages. See the openUTM manual “Generating Applications” for details of multilingual operation.
		In locale_lang_id you specify the language code of the language in which messages and notifications are to be passed. The code is a maximum of 2 bytes long.
		In locale_terr_id you specify the territorial code. It specifies territorial particularities of the language. It is a maximum of 2 bytes long.
		In locale_ccsname you specify the CCS name of the expanded character set (coded character set) to be used for outputting data. The CSS name can be up to 8 characters long and must belong to a EBCDIC character set defined on the BS2000 system (see also the XHCS User Manual).
o	protect_pw16_lth	Specifies the minimum number of characters a password must contain to be accepted as such by UTM (minimum length of the password). The password for a user ID can only be deleted if protect_pw16_lth ='00'.
		Maximum value: '16', The minimum length is dependent on the complexity level specified in protect_pw_compl. The minimum value for protect_pw16_lth is: '0' for protect_pw_compl = '0' '1' for protect_pw_compl = '1' '2' for protect_pw_compl = '2' '3' for protect_pw_compl = '3'
o	protect_pw_compl	Specifies the complexity level that the password for the user ID must meet.
		'0'	(NONE) Any character string may be entered as the password.
		'1'	(MIN) A maximum of 2 characters in a row may be identical in a password. The minimum length of a password is one character.
		'2'	(MEDIUM) A maximum of 2 characters in a row may be identical in a password. The password must contain at least one letter and one number and be at least two characters long.
		'3'	(MAX) A maximum of 2 characters in a row may be identical in a password. The password must contain at least one letter, one number and one special character. The minimum length is 3 characters. Special characters are all characters not between a-z, A-Z, 0-9. The space key is not a special character.
o	protect_pw_time[3]	Specifies the maximum number of days for which the password remains valid (period of validity). If protect_pw_time = '0' is specified, then the password is valid for an unlimited amount of time.
		Minimum value: '0', Maximum value: '180'
o	restart	Specifies whether UTM saves service data for the user ID so that a service restart is possible on the next sign-on using this user ID.
		'Y':UTM saves service data 'N': UTM does not save any service data.
o	permit	Specifies the administration privileges for the user ID.
		'A'	(ADMIN) The user ID is to be able to execute administration functions in the local application.
		'N'	(NONE) The user ID is not have any administration privileges. In UTM applications on BS2000 systems, no UTM SAT administration functions may be executed under this user ID.
		'B'	(BOTH) Only on BS2000 systems: Both administration and UTM SAT administration functions may be executed under this user ID.
		'S'	(SAT) Only on BS2000 systems: The user ID has UTM SAT administration privileges. Preselection functions may be executed.
o	satsel	Only on BS2000 systems: Specifies the type of SAT logging for the user ID.
		'B'	Both successful and unsuccessful events are to be logged (BOTH).
		'S'	Only successful events are to be logged (SUCC).
		'F'	Only unsuccessful events are to be logged (FAIL).
		'N'	No user-specific SAT logging is defined (NONE).
		Logging can only take place if SAT logging is activated for the application. (See the openUTM manual “Generating Applications” and openUTM manual “Using UTM Applications” for more information on SAT logging.)
o	protect_pw_min_time[3]	Specifies the minimum term of validity in days for the password.
		After changing the password, the user must not change it again before the minimum term of validity is expired. If a minimum term of 1 day is specified, the password cannot be changed again before 00.00 hrs of the following day (local time of generation).
		If the password is changed by the administrator or following a regeneration, the user can always change the password, regardless of whether the minimum term of validity is expired or not.
		protect_pw_min_time must not be larger than protect_pw_time (maximum term of validity).
		Minimum value: '0' Maximum value: '180'
o	qlev[5]	Specifies the maximum number of messages that can be stored temporarily in the user’s message queue. If the threshold value is exceeded, what happens depends on the value in the q_mode field. When qlev=0, no messages can be stored temporarily in the queue. When qlev=32767, there is no limit on the length of the queue. Minimum value: 0, maximum value: 32767
o	q_read_acl[8]	Specifies the rights (name of a key set) that another user requires in order to be able to read and delete messages from this USER queue. Another user only has read access to this USER queue if the key set of the user’s user ID and the key set of the logical terminal via which the user is signed on each contain at least one key code that is also contained in the specified key set. If q_read_acl does not contain a value, all users can read and delete messages from this queue.
o	q_write_acl[8]	Specifies the rights (name of a key set) that another user requires in order to be able to write messages to this USER queue. Another user only has write access to this queue if the key set of the user ID and the key set of the logical terminal via which the user is signed on each contain at least one key code that is also contained in the specified key set. If q_write_acl does not contain a value, all users can write messages to this queue.
o	q_mode	Specifies how UTM responds when the maximum number of not yet executed jobs in the user’s queue is reached. The possible values are:
		'S'	UTM rejects any further jobs (default).
		'W'	UTM accepts further messages but deletes the oldest messages in the queue.
o	principal[100]	Only on BS2000 systems: Specifies that the user is to be authenticated via Kerberos. Specifying principal excludes the possibility of specifying card and password. principal must be specified as an alphanumeric string in the form windowsaccount@NT-DNS-REALM-NAME. windowsaccount: Domain account of the user NT-DNS-REALM-NAME: DNS name of the Active Directory domain

1

All fields in the data structure kc_user_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_user_str, kc_user_fix_str, kc_user_dyn1_str and kc_user_dyn2_str user IDs".