Change the password or password phrase recorded by an external security manager (ESM) for a specified user ID.
CHANGE PHRASE >>-CHANGE PHRASE(data-area)--PHRASELEN(data-value)--------------> >--NEWPHRASE(data-area)--NEWPHRASELEN(data-value)---------------> >--USERID(data-value)--+----------------------+-----------------> '-ESMREASON(data-area)-' >--+--------------------+-------------------------------------->< '-ESMRESP(data-area)-'
Conditions: INVREQ, LENGERR, NOTAUTH, USERIDERR
This command is threadsafe.
Description
A user ID can have both a password and a password phrase. If PHRASELEN is between 1 and 8 characters, the phrase is treated as a password. If the length is between 9 and 100 characters, it is treated as a password phrase. You cannot use a 1- to 8-character password to change a password phrase. Similarly, you cannot use a 9- to 100-character password phrase to change a 1- to 8-character password.
Unlike the SIGNON command, CHANGE PHRASE does not depend upon the principal facility, therefore it can be issued in non-terminal environments such as Web applications and APPC sessions.
Attention: To ensure that passwords are not revealed in system or transaction dumps, clear the password or password phrase fields on the EXEC CICS commands that have a password or password phrase option as soon as possible after use.
Options
Options ESMRESP and ESMREASON return the response and reason codes, if any, from the external security manager.
- 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.
- 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. The password is changed only if the current password is correctly specified. The password
phrase is changed only if the current password phrase is correctly specified.
If the ESM does not allow mixed case passwords, the 1- to 8-character password is converted to uppercase.
- NEWPHRASELEN(data-area)
- specifies the length, as a fullword binary value, of the new password or password phrase.
- PHRASE(data-area)
- specifies the
current password or password phrase of the specified user ID.
If the ESM does not allow mixed case passwords, the 1- to 8-character password is converted to uppercase.
- PHRASELEN(data-area)
- specifies the length, as a fullword binary value, of the current password or password phrase.
- USERID(data-value)
- specifies the
user ID of the user whose password or password phrase is being changed.
The user ID supplied is converted to uppercase.
Conditions
- 16 INVREQ
- RESP2
values:
- 2
- You cannot use a password to change a password phrase or a password phrase to change a password.
- 13
- The external security manager has issued an unknown return code in ESMRESP.
- 18
- The CICS external security manager interface is not initialized.
- 29
- The external security manager is not responding.
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:
- 2
- The supplied password or password phrase is wrong. If the external security manager is RACF , the revoke count maintained by RACF is incremented.
- 4
- The new password or password phrase is not acceptable.
- 19
- The user ID is revoked.
- 20
- The connection to the user's default group has been revoked.
- 22
- The change password request failed during SECLABEL processing.
- 31
- The user is revoked in the connection to the default group.
Default action: terminate the task abnormally.
- 69 USERIDERR
- RESP2
values:
- 8
- The USERID is not known to the external security manager.
Default action: terminate the task abnormally.
