Sign on to a terminal.

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.