You use the SIGN (sign on) call to
query the status of the sign-on service in the sign-on service or transfer the authorization data to openUTM
change the password for the current user ID
have the authorization data checked
initiate in the program the effect of the commands KDCOFF and KDCOFF BUT.
The SIGN call is only allowed in dialog program units (exception: SIGN CK).
For BS2000 systems, you can additionally use the SIGN CL (Change Locale) call to change the location of the current user ID. This call is described as of "SIGN CL - Change locale of user ID (BS2000 systems)".
Setting the KDCS parameter area (1st parameter)
The table below shows the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCS parameter area | |||
|---|---|---|---|---|
KCOP | KCOM | KCLA | KCUS | |
Query status of the sign-on service | "SIGN" | "ST" | 120 | Binary zero |
Transfer authorization data to openUTM | "SIGN" | "ON" | 16 | User ID |
Change password | "SIGN" | "CP" | 32 | Binary zero |
Check authorization data (without sign-on) | "SIGN" | "CK" | 16 | User ID |
Initiate effect of the KDCOFF command | "SIGN" | "OF" | 0 | Binary zero |
Initiate effect of the KDCOFF BUT command | "SIGN" | "OB" | 0 | Binary zero |
All the fields not used in the KDCS parameter area have to be set to binary zero.
Setting the 2nd parameter
Here you have to supply the address of the message area from which openUTM is to read the data.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"SIGN" | |
"ST"/"ON"/"CP"/"CK"/"OF"/"OB" | |
120/16/32/16/0/0 | |
User ID/binary 0 | |
Data/ - | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_SIGNST/KDCS_SIGNOF/KDCS_SIGNOB | (nb) |
KDCS_SIGNON/KDCS_SIGNCK | (nb,kcla,kcus) |
KDCS_SIGNSTLA/KDCS_SIGNCP | (nb,kcla) |
openUTM return information | |
|---|---|
Field name in the KB return area | Contents |
Sign-on status | |
Additional information | |
Name of user ID | |
Return code | |
Internal return code | |
Format identifier of start format/blanks | |
Validity period of password | |
For the SIGN call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, the SIGN operation code.
KCOM
In the KCOM field
ST: query status of the sign-on service
ON: check authorization data (with sign-on)
CP: change password
CK: check authorization data (without sign-on)
OF: initiate effect of the KDCOFF command
OB: initiate effect of the KDCOFF BUT command.
KCLA
In the KCLA field
120 for KCOM=ST:
This is the length of the message area into which openUTM transfers the information. openUTM provides a data structure for structuring of the message area, see description on "Features of the SIGN call". Specify the version number of the structure in the data structure header.16 for KCOM = ON/CK:
This is the length of the password that is transferred in the message area for this call.32 for KCOM = CP:
This is the length of the old and new password that is transferred in the message area for this call.0 for KCOM = OF/OB
KCUS
In the KCUS field, the user ID if, with KCOM = ON/CK, authorization data is to be transferred to UTM. Enter binary zero for all other variants.
Message area
In the message area you have to enter the data you wish to transfer to openUTM or receive from openUTM.
The password (16 characters) is made available for KCOM = ON/CK, the old and the new password (32 characters) are made available for KCOM = CP.
For KCOM = ST, the following information is exchanged when KCLA > 0 (maximum of 120 characters):
the desired version of the data structure is passed (2 characters)
data for the sign-on service (e.g. validity period of the password) is returned.
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area.
2nd parameter
The address of the message area from which UTM is to read the data. You enter the address of the message area even if you have entered the length 0 in KCLA.
Macro names
The use of C/C++ calls is described in detail in the section "C/C++ macro interface".
openUTM returns:
KCRSIGN1
KCRSIGN2
Additional information in the KCRSIGN1 and KCRSIGN2 fields (nothing is entered unless KCRCCC = 000):
for KCOM = ST, the current status of the sign-on procedure, see table on "Return information of the SIGN ST call in the KCRSIGN1 and KCRSIGN2 fields".
for KCOM = CK, the result of the check, see table on "Return information of the SIGN CK call in the KCRSIGN1 and KCRSIGN2 fields".
KCRUS
in the KCRUS field, the name of the user ID if:
KCRSIGN1=U, i.e. it was not possible to sign-on the user ID successfully, or
KCRSIGN1=I, i.e. sign-on was not terminated successfully, an intermediate dialog must be performed for the user
KCRCCC
in the KCRCCC, the KDCS return code, see "KDCS return codes for the SIGN call".
KCRCDC
in the KCRCDC field: the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).
KCRMF/kcrfn
in the KCRMF/kcrfn field, for KCOM = ST the format identifier of the start format or blanks if no start format was generated. When used with USER and if the sign-on was successful, the identifier of the user-specific start formats is returned. If sign-on has not yet been completed successfully or if the application is generated without USER, then KCRMF/kcrfn contains the identifier of the LTERM-specific start format.
KCRLM
in the KCRLM field, for KCOM = ST:
for KCRCCC < 40Z: KCRLM contains the length of the information actually available in openUTM.
for KCRCCC >= 40Z, 0 is returned.
SIGN ST call return information in the fields KCRSIGN1 and KCRSIGN2
For SIGN ST, openUTM delivers the following information about the current status of the sign-on procedure in fields KCRSIGN1 and KCRSIGN2:
KCRSIGN1 | KCRSIGN2 | Meaning |
|---|---|---|
C | 01 | Connection established (as K002) |
02 | KDCOFF BUT command issued (as K018) | |
03 | KDCOFF BUT issued from program | |
U | 01 | Specified USER not generated (as K004) |
02 | Specified USER locked (as K005) | |
03 | Someone already signed on with this USER (as K007) | |
04 | Specified old password is invalid (as K006) | |
01 | Specified USER not generated (as K004) | |
02 | Specified USER is locked (as K005) | |
03 | Someone already signed on with this USER (as K007) | |
04 | Specified old password is invalid (as K006) | |
05 | Entries for new password unusable | |
06 | The terminal has no card reader (as K030) | |
07 | Card information is invalid (as K031) | |
08 | Sign-on not possible at present because of resource bottleneck or no further users can sign on at present, since the maximum possible number of simultaneous users has been reached, or it was not possible to change the password, since an inverse KDCDEF is currently running. | |
09 | Only on BS2000 systems: Sign-on not possible because of missing Kerberos support (as K110). | |
10 | The current LTERM is not authorized to continue the service (as K123) | |
11 | The period of validity for the password has been exceeded (as K120) | |
12 | The new password does not fulfill the requirements of the complexity level generated (as K097) | |
13 | The new password is too short (as K097) | |
U | 14 | The password transferred by KDCUPD does not fulfill the requirements of the complexity level generated (as K125) |
15 | A transaction restart is required for the specified user ID (as K145) | |
16 | The open service cannot be continued from within this LTERM partner (like K123) | |
17 | The administrator issued a SHUT WARN; | |
18 | The encryption mechanism required for the continuation of the open service is not available in the connection (as K123) | |
19 | The period of validity of the password has been exceeded but the password can still be changed because the application is generated with SIGNON GRACE=YES. | |
20 | Only on BS2000 systems: Error in the Kerberos authentication (as K108) | |
21 | Only on BS2000 systems: Invalid Kerberos principal (as K109) | |
22 | Only on Unix, Linux and Windows systems: The specified USER does not exist in the cluster user file (as K004). | |
23 | Somebody has already signed onto a different node application under this USER (as K007). | |
24 | Only on Unix, Linux and Windows systems: It is currently not possible to sign on because the cluster user file could not be locked in the generated time (CLUSTER statement, parameter FILE-LOCK-TIMER-SEC, parameter FILE-LOCK-RETRY) (as K091). | |
25 | It is not possible to sign on at this node application because the user has a service that is bound to another node application and which may not be terminated (as K189). | |
26 | Sign-on rejected because the user’s open service has a transaction in PTC state but no service restart has been requested. | |
I | 01 | The USER is known but intermediate dialog is required (only for automatic KDCSIGN) |
A | 01 | Sign-on successful because generated without USER (as K001) |
02 | Sign-on successful (as K008) | |
03 | Only on BS2000 systems: Sign-on successful (via distributor) | |
04 | Sign-on successfu l (from the connection user ID, only for TS applications or UPIC client). It is possible to sign on with a "genuine" user ID using the SIGN ON call. | |
05 | Sign-on successful, password changed via intermediate dialog | |
06 | Only on BS2000 systems: Sign-on successful (via distributor), the password was changed via distributor | |
R | 01 | as A01, but after service restart |
02 | as A02, but after service restart | |
03 | as A03, but after service restart (only on BS2000 systems) | |
04 | as A04, but after service restart | |
05 | as A05, but after service restart | |
06 | as A06, but after service restart (only on BS2000 systems) |
KCRSIGN1 provides a rough classification:
C: Connected but not signed on.
Status following connection setup or KDCOFF BUTU: Sign-on Unsuccessful.
A preceding attempt to sign on was rejected.I: Sign-on Incomplete.
Intermediate dialog is required to obtain additional data (password, ID, chipcard)A: Sign-on Accepted.
Without subsequent service restartR: Sign-on accepted + Restart.
With subsequent service restart.
Return information of the SIGN CK call in the KCRSIGN1 and KCRSIGN2 fields
openUTM returns the following information for SIGN CK in the KCRSIGN1 and KCRSIGN2 fields:
KCRSIGN1 | KCRSIGN2 | Meaning |
|---|---|---|
A | 02 | Authorization data is correct and complete |
U | 01 | The specified USER does not exist |
02 | The specified USER is locked | |
04 | The specified old password is incorrect | |
06 | The terminal has no card reader (only on BS2000 systems) | |
07 | The card information is invalid (only on BS2000 systems) | |
09 | No Kerberos support (only on BS2000 systems) | |
11 | The validity period of the password has expired | |
14 | The password transferred by KDCUPD does not satisfy the complexity level requirement or is too short | |
21 | Invalid Kerberos principal (only on BS2000 systems) |
KDCS return codes in the KCRCCC field for the SIGN CK/CP/OB/OF/ON/ST calls
The following codes can be analyzed in the program:
000 | Operation carried out. |
01Z | For SIGN ST: The function was executed, the message area provided is too short, though (the value in KCLA is too small). No information or incomplete information was returned. |
40Z | System cannot perform the operation (generation error or system error). |
41Z | Call is not allowed at this point:
|
42Z | Entry in KCOM is invalid. |
43Z | Length entry in KCLA is negative or invalid. |
44Z | For KCOM=CP: entry for old password incorrect, password not changed |
45Z | For KCOM=CP: entry for new password incorrect, password not changed. The more precise cause provides KCRCDC. |
47Z | Message area missing or cannot be accessed in the specified length. |
48Z | For KCOM=ST: invalid interface version |
49Z | Contents of fields not used in the KDCS parameter area not equal to binary zero. |
An additional return codes can be found in the dump:
71Z | INIT call still missing in the program unit run. |
Features of the SIGN call
Message area for SIGN ST with KCLA > 0:
Field name
COBOLField name
C/C++Length
in bytesDescription
Call information:
KCVER
if_version
2
Version number of the data structure ( 4)
Return information:
KCRPWVAL
rpwval
2
Validity period of the password
KCRPWMIN
rminpw
2
Minimum validity period of the password
KCRUSER
ruser
8
User ID
KCRTAC
rtac
8
Transaction code from the UPIC protocol
KCFILLER
filler
8
KCRPSWRD
rpsword
8
Password from the UPIC protocol
KCLSTSGN
rlstsgn
14
Date/time of the last sign-on
KCDSPMSG
rdispmsg
1
Message present (Y/N)
KCTAPTC
rtainptc
1
Transaction in PTC state (Y/N)
KCCLNODE
rclusternode
64
Only on Unix, Linux and Windows systems: Host name of the node to which the open service is bound
KCRPASSL
rpsword16
16
Password from the UPIC protocol
KCSGRES
reserved
10
Reserved for future extensions
The following mean:
KCVER
Version number of the data structure. The number 4 is to be entered here for this version of openUTM.
KCRPWVAL
If the sign-on was successful (KCRSIGN1 = A/R) or has not yet been successful (KCRSIGN1 = I), then this field contains the number of days that the password for this user is still valid.
The value -1 means that there was no validity period generated for the password.
The value 0 means that the password will become invalid within the next 24 hours.
The value -2 means that validity of the password has run out. The password must be changed if the sign-on service is to terminate successfully. This values can only be returned if grace sign-ons are permitted (SIGNON statement in the generation, parameter
GRACE = YES).In the case of KCRSIGN1 = I, the value -3 means that the complexity level or minimum length of the password has been increased and that the password transferred with the KDCUPD tool may possibly no longer meet the requirements.
Otherwise the value -3 means that the password passed by the KDCUPD tool does not meet the complexity level requirements or is too short. The password must be changed with SIGN CP if the sign-on service is to terminate successfully.
This values can only be returned if grace sign-ons are permitted (SIGNON statement in the generation, parameter GRACE = YES).KCRPWMIN
If the sign-on is successful (KCRSIGN1 = A/R) or has not yet been successful (KCRSIGN1 = I), then this field contains the number of days that the password for this user may not be changed using a SIGN CP call. The value 0 means that the password may be changed.
KCRUSER
After an unsuccessful or not yet completed sign-on (KCRSIGN1 = U/I), this field contains the name of the user that was rejected (KCRSIGN1 = U) or for whom an intermediate dialog must be executed first (KCRSIGN1 = I), otherwise it contains blanks.
KCRTAC
This field contains the name of the transaction code (TP_Name) passed in the UPIC protocol in the sign-on service for the UPIC client, otherwise it contains blanks. openUTM does not check if the transaction code is valid or not.
KCLSTSGN
This field contains the date and time of the last successful sign-on of this user to the application after the user has successfully signed on (KCRSIGN1 = A/R) or has not yet signed on successfully (KCRSIGN1 = I). The date and time are passed in the format
YYYYMMDDHHMMSS. Printable nulls are returned after the first successful sign-on after a regeneration.KCDSPMSG
After the successful sign-on (KCRSIGN1 = A/R) of a user, the field contains the following value:
Y
If there is an open dialog service for the user (KCRSIGN1=R) or a dialog message that can be output with MPUT PM
N
in all other cases
KCTAPTC
When the user has successfully signed on with a subsequent service restart (KCRSIGN1 = R), the field has the following value:
Y
If there is a transaction in the state P(repare) T(o) C(ommit) for the user. In this case, the service restart cannot be prevented.
N
in all other cases.
KCCLNODE
If the sign-on was not successful (KCRSIGN1 = U) due to the existence of a service bound to another node application (KCRSIGN2 = 25), the field contains the host name of the node to which the open service is bound.
KCRPASSL
This field contains the password of a user generated without a password that was passed in the UPIC protocol in the sign-on service for the UPIC client after a successful sign-on (KCRSIGN1 = A/R), otherwise it contains blanks.
Entries in the message area for SIGN ON and SIGN CP
For SIGN ON, write an 16 byte password to the message area. Blanks mean "user ID without password".
For SIGN CP, write the old and new passwords at 16 byte length to the message area as follows:
old password1
new password1
1Blanks mean "user ID without password"
The new password must consist of characters which are allowed in the UTM partner application, see openUTM manual “Generating Applications”, USER statement.
If the call has the correct syntax, then openUTM overwrites the data area with blanks.
You do not need administration authorization for this call.
With SIGN ON openUTM checks whether the user is able to sign on from this client at this time.
With SIGN CK openUTM checks whether the authorization data is adequate for successful sign-on from this client but does not check whether sign-on is possible at this time.
SIGN OF and SIGN OB may only be issued in program units terminated with PEND RE or PEND RE or PEND FI and which issue the dialog message to the terminal, the UPIC client or the transport system application. Otherwise, openUTM aborts the service with PEND ER.
SIGN OB to UPIC clients or transport system applications has the same effect as SIGN OF.
SIGN OF and SIGN OB only take effect at the next input from the terminal. In other words, the user is not signed off until after the next input (SIGN OB), or the connection to the terminal is not cleared until after the first input (SIGN OF). In the case of UPIC clients or transport system applications, the connection cleardown is initiated immediately.SIGN ST and SIGN ON are only allowed in the sign-on service.