SIGNON

Sign on to a terminal.

SIGNON

Conditions: INVREQ, LENGERR, NOTAUTH, USERIDERR

This command is threadsafe.

Description

The SIGNON command enables your application to associate a new user ID with the current terminal. When you use the SIGNON command, the following rules apply:

The sign-on operation is terminal related only. Sign-on has no meaning if the transaction does not have a terminal as its principal facility.
When you issue an EXEC CICS SIGNON command, CICS® modifies the state of the terminal that is the principal facility of the transaction that issues the command.
Sign-on does not affect the user ID and security capabilities currently in effect for the transaction issuing the command. This is because:
- A transaction's user ID and security capabilities are established at transaction-attach time. It is not possible to modify these subsequently during the life of the transaction.
- All actions performed by a transaction (whether to a local or remote resource, or to a connected system) take place in the security context established at the time the transaction was attached.
If authorization is required, you can sign on with either a valid password or a valid password phrase. However, you cannot set a new password phrase using a password for authentication, nor can you set a new password using a password phrase for authentication.

If you supply an incorrect password on the SIGNON request, the invalid attempt count is increased for the user ID. If you supply multiple incorrect passwords on successive SIGNON requests, the user ID may be revoked by the external security manager (ESM). CICS issues message DFHXS1201 when you supply an incorrect password on a SIGNON request. When you supply a correct password following one or more invalid attempts, CICS issues message DFHXS1206, which includes a count of the invalid attempts.

There is no implied sign-off with the SIGNON command. If your application program attempts to associate a new user with a terminal that already has a signed-on user ID, CICS returns an INVREQ (Resp2=9) error response. Note that there is no default value for the USERID option.

PASSWORD is used as a parameter which means that if CICS has a memory dump, the password may be visible. You should therefore clear the PASSWORD field as soon as possible after using it in a SIGNON command.

For more information on how CICS uses the USERID and GROUPID, see Verifying CICS users.

Options

If an optional input field contains all blanks, it is ignored.

ESMREASON(data-area)

Returns the reason code, in a fullword binary field, that CICS receives from the ESM.

If the ESM is RACF®, this field is the RACF reason code.

ESMRESP(data-area)

Returns the response code, in a fullword binary field, that CICS receives from the ESM.

If the ESM is RACF, this field is the RACF return code.

GROUPID(data-value)

Assigns, to a RACF user group, the user that is being signed on. This overrides, for this session only, the default group name specified for the user in the RACF database.

LANGUAGECODE(data-value)

Specifies the national language that the user being signed on wants CICS to use. You specify the language as a standard 3-character IBM® code. This is an alternative to the 1-character code that you specify on the NATLANG option.

See National language codes for possible values of the code.

Note: CICS messages are supported only in UK English, Simplified Chinese, and Japanese. If any other language other than those three is specified, English is used by default.

LANGINUSE(data-area)

Allows an application program to receive the national language chosen by the sign-on process. The language is identified as a standard three-character IBM code, instead of the one-character code used by NATLANGINUSE. It is an alternative to the existing NATLANGINUSE option.

See National language codes for possible values of the code.

NATLANG(data-value)

Specifies a 1-character code identifying the national language the user wants to use during the signed-on session.

See National language codes for possible values of the code.

Note: CICS messages are supported only in UK English, Simplified Chinese, and Japanese. If any other language other than those three is specified, English is used by default.

NATLANGINUSE(data-area)

Specifies a 1-character code representing the national language used during the signed-on session. The current implementation always returns the character E (U.S. English), which corresponds to the language supplied in the NATLANG option. NATLANGINUSE corresponds to the following (in order of decreasing priority):

The language supplied in the NATLANG option of the SIGNON command.
The language associated with the user. This is specified in the ESM language segment.
The language associated with the definition of the terminal.
The language associated with the default USERID for the CICS region.
The default language specified in the system initialization parameters.

See National language codes for possible values of the code.

NEWPASSWORD(data-value)

Specifies an optional 8-byte field defining a new password. This option is valid only if PASSWORD is also specified. You cannot enter a password phrase in this field.

If this field is blank then it is ignored.

If the ESM does not allow mixed case passwords, the password is converted to uppercase.

NEWPHRASE(data-area)

Specifies an optional 1- to 8-character new password or a 9- to 100-character new password phrase required by the ESM. This option is valid only if PHRASE is also specified.

If this field is blank then it is ignored.

If the ESM does not allow mixed case passwords, the 1- to 8-character password is converted to uppercase.

NEWPHRASELEN(data-value)

Specifies the length of the new password phrase as a fullword binary value. This option is valid only if NEWPHRASE is also specified.

If NEWPHRASELEN is 0 then NEWPHRASE is ignored.

OIDCARD(data-value)

Specifies an optional 65-byte field containing further security data from a magnetic strip reader (MSR) on 32xx devices.

PASSWORD(data-value)

Specifies an 8-byte password required by the ESM.

If the ESM does not allow mixed case passwords, the password is converted to uppercase.

PHRASE(data-area)

Specifies an optional 1- to 8-character password or a 9- to 100-character password phrase required by the ESM.

If the ESM does not allow mixed case passwords, the 1- to 8-character password is converted to uppercase.

PHRASELEN(data-value)

Specifies the length of the password phrase as a fullword binary value. This option is valid only if PHRASE is also specified.

USERID(data-value)

Specifies the 8-byte sign-on user ID.

The user ID supplied is converted to uppercase.

Conditions

16 INVREQ

RESP2 values:

2: A password cannot be used to change a password phrase or a password phrase cannot be used to change a password.
9: The terminal is already signed on.
10: No terminal is associated with this task.
11: This task's terminal has preset security.
12: The response from CICS security modules is unrecognized.
13: There is an unknown return code in ESMRESP from the ESM; or the ESM is not active or has failed in an unexpected way.
14: The required national language is not available.
15: Sign-on was attempted using transaction routing without using the CRTE transaction.
18: The CICS ESM interface is not initialized (SEC=NO specified as a system initialization parameter).
25: The terminal is of an invalid type.
26: An error occurred during SNSCOPE checking. The limit of MVS™ ENQ requests was reached.
27: The ESM is not active.
28: The required national language is invalid.
29: The user is already signed on. This relates to the sign-on scope checking.
200: Command not allowed for a distributed program link server program.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

1: PHRASELEN was out-of-range .
2: NEWPHRASELEN was out-of-range .

70 NOTAUTH

RESP2 values:

1: A password or password phrase is required.
2: The supplied password or password phrase is wrong.
3: A new password or password phrase is required.
4: The new password or password phrase is not acceptable.
5: An OIDCARD is required.
6: The supplied OIDCARD is wrong.
16: The USERID is not authorized to use this terminal.
17: The USERID is not authorized to use the application.
19: The USERID is revoked.
20: The USERID's access to the specified group has been revoked.
21: The sign-on failed during SECLABEL checking.
22: The sign-on failed because the ESM is not currently accepting sign-on.
23: The GROUPID is not known to the ESM.
24: The USERID is not contained in the GROUPID.

Default action: terminate the task abnormally.

69 USERIDERR

RESP2 values:

8: The USERID is not known to the ESM.
30: The USERID is all blanks or nulls.

Default action: terminate the task abnormally.