QUERY SECURITY

To query the security authorization of the user.

QUERY SECURITY

Conditions: INVREQ, LENGERR, NOTFND, QIDERR

This command is threadsafe.

Description

The QUERY SECURITY command allows the application to determine whether the user has access to resources defined in the external security manager (ESM). These resources can be:

In CICS® resource classes
In user-defined resource classes

The user in this context is the user invoking the transaction that contains the QUERY SECURITY command.

For more information on the use of the QUERY SECURITY command, see Security checking using the Query Security command.

Options

ALTER(cvda)

Query whether the user has ALTER authority for the named resource. The cvda values returned by CICS are ALTERABLE and NOTALTERABLE.

CONTROL(cvda)

Query whether the user has CONTROL authority for the named resource. The cvda values returned by CICS are CTRLABLE and NOTCTRLABLE.

LOGMESSAGE(cvda)

Inhibit security violation messages. The values passed to CICS are LOG (the default value), or, to inhibit messages, NOLOG.

READ(cvda)

Query whether the user has READ authority command for the named resource. The cvda values returned by CICS are READABLE and NOTREADABLE. READ access authority usually permits nondestructive use of a resource as, for example, in the case of READ and INQUIRE commands.

RESCLASS(data-value)

Specifies an 8-character field identifying the name of a valid resource class, that could be non-CICS, in the ESM. The class name identified by RESCLASS is treated literally with no translation.

If the ESM is RACF®, the class can be CICS-supplied or user-defined. RESCLASS enables you to define more narrowly the authorization to be queried; for example, you can query at the record or field level.

The responses returned by the command reflect the definition of the RESID resource as defined in the specified RESCLASS.

RESID(data-value)

Specifies the name of the CICS or user-defined resource that you want to query the users access to. The value is a character string (1-12 characters for a CICS resource, and 1-246 characters for a user-defined resource, unless you are using the COBOL3 translator option in which case the maximum length is 160 characters).

Note: RESID refers to a CICS-defined resource only when RESTYPE('SPCOMMAND') is specified, otherwise it refers to a user-defined resource. For a list of the CICS RESID values that you can use when RESTYPE('SPCOMMAND') is specified, see RESID values.

Note that the actual resource checked depends on whether RESCLASS or RESTYPE is specified in the command and whether prefixing is active (SECPRFX=YES or SECPRFX=prefix specified as a system initialization parameter).

If RESCLASS is specified, the resource checked is always the actual RESID data-value, whether or not prefixing is on or off. IF RESTYPE is specified and SECPRFX=NO, the resource checked is the RESID data-value as specified. Otherwise the resource checked is the RESID data-value prefixed with either the CICS region userid (if SECPRFX=YES), or another prefix (if SECPRFX=prefix).

RESIDLENGTH(data-value)

Specifies the length, as a fullword binary, of the resource identifier in RESID. You only use this parameter when specifying the RESCLASS option.

RESTYPE(data-value)

Specifies the type of resource (1–12 characters) you want to query the user's access to.

The responses returned by the command reflect the results that would be obtained if an actual attempt was made to access the specified CICS resource. The value you specify for RESTYPE must be one of the following resource types:

Table 1. QUERY SECURITY RESTYPE values
RESTYPE value	Xname parameter
ATOMSERVICE	XRES
BUNDLE	XRES
DB2ENTRY	XDB2
DOCTEMPLATE	XRES
EPADAPTER	XRES
EPADAPTERSET	XRES
EVENTBINDING	XRES
FILE	XFCT
JOURNALNAME	XJCT
JOURNALNUM 1	XJCT
JVMSERVER	XRES
PROGRAM	XPPT
PSB	XPSB
SPCOMMAND 2	XCMD
TDQUEUE	XDCT
TRANSACTION	XPCT
TRANSATTACH	XTRAN
TSQUEUE	XTST
TSQNAME	XTST
XMLTRANSFORM	XRES

Supported for compatibility with earlier releases.
SPCOMMAND is a resource type that you can use to specify a RESID for a command.

The XHFS system initialization parameter controls resource security for zFS files and does not have a corresponding RESTYPE value on the QUERY SECURITY command. Access controls for zFS files follow the system of permissions used by z/OS® UNIX System Services, so they operate in a different way.

With dynamic transaction routing, you do not have to install transaction definitions in terminal owning regions. A QUERY SECURITY command with a RESTYPE of TRANSATTACH returns the NOTFND condition if the transaction is not installed. Application developers must be aware that the transaction might be routed dynamically.

UPDATE(cvda)

Query whether the user has UPDATE authority for the named resource. The CVDA values returned by CICS are UPDATABLE and NOTUPDATABLE. UPDATE access authority usually permits destructive use of a resource as, for example, in the case of WRITE, DELETE, or UPDATE commands.

Conditions

16 INVREQ

RESP2 values:

7: The cvda value is not valid for the LOGMESSAGE.
9: The RESID is invalid or filled with blanks.
10: The external security manager (ESM) is inactive or not present.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

6: The RESIDLENGTH value is not valid, that is, not in the range 1 through 246.

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

1

The RESID is not valid.

2

The RESTYPE is not valid.

3

The RESID value for RESTYPE (SPCOMMAND) is not valid.

5

The RESCLASS is not defined to the external security manager (ESM).

8

The resource is not protected. This is only returned when QUERY SECURITY is used with the RESCLASS option (and never occurs with RESTYPE).

Possible causes include:

RESCLASS not active.
No profile found.
ESM not active.

Default action: terminate the task abnormally.

44 QIDERR

RESP2 values:

1: An indirect queue name associated with the given RESID is not found.

Default action: terminate the task abnormally.