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)-' |
'-PHRASE(data-area)-PHRASELEN(data-value)-+-----------------------------------------------+-'
'-NEWPHRASE(data-area)-NEWPHRASELEN(data-value)-'
>--+---------------------+-------------------------------------><
'-OIDCARD(data-value)-'
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.
- 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.
- 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.
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 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 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.
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)
- 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.
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 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 valid only if
PASSWORD is also specified. You cannot enter a password phrase in
this field.
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 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.
- 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).
If
the ESM does not allow mixed case passwords, the password is converted to uppercase.
- PHRASE(data-area)
- specifies a 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 USERID.
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 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.
- 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 external security manager.
- 30
- The USERID is all blanks or nulls.
Default action: terminate the task abnormally.