SIGNON

Sign on to a terminal.

Read syntax diagramSkip visual syntax diagram
SIGNON

>>-SIGNON--USERID(data-value)--+----------------------+--------->
                               '-ESMREASON(data-area)-'   

>--+--------------------+--+---------------------+-------------->
   '-ESMRESP(data-area)-'  '-GROUPID(data-value)-'   

>--+--------------------------+--+----------------------+------->
   +-LANGUAGECODE(data-value)-+  '-LANGINUSE(data-area)-'   
   '-NATLANG(data-value)------'                             

>--+-------------------------+--+----------------------+-------->
   '-NATLANGINUSE(data-area)-'  '-PASSWORD(data-value)-'   

>--+-------------------------+--+---------------------+--------><
   '-NEWPASSWORD(data-value)-'  '-OIDCARD(data-value)-'   

Conditions: INVREQ, NOTAUTH, USERIDERR

 

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 signon operation is terminal related only. Signon 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.
  • Signon 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.

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 takes a 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 CICS RACF® Security Guide.

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 external security manager.

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 external security manager.

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.

LANGINUSE(data-area)
the LANGINUSE option 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 field identifying the national language the user wants to use during the signed-on session.

See National language codes for possible values of the code.

NATLANGINUSE(data-area)
specifies a one character 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 only valid if PASSWORD is also specified.
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 external security manager (ESM).
USERID(data-value)
specifies the 8-byte sign-on USERID.

Conditions

INVREQ
RESP2 values:
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 external security manager; or the external security manager (ESM) is not active, or has failed in an unexpected way.
14
The required national language is not available.
15
Signon 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 external security manager (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.

NOTAUTH
RESP2 values:
1
A password is required.
2
The supplied password is wrong.
3
A new password is required.
4
The new password 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.

USERIDERR
RESP2 values:
8
The USERID is not known to the external security manager.
30
The USERID is all blanks or nulls.

Default action: terminate the task abnormally.