AUTH call

An Authorization (AUTH) call verifies each user's security authorization. It determines whether a user is authorized to access the resources specified on the AUTH call.

Format

Read syntax diagramSkip visual syntax diagramAUTHi/o-pcbaibi/o_area
Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
AUTH X   X    

Parameters

i/o pcb
Specifies the I/O PCB, the first PCB address in the list that is passed to the program. This parameter is an input and output parameter.
aib
Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.
The following fields must be initialized in the AIB:
AIBID
Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN
AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1
Resource name. This 8-byte, left-justified field must contain the PCB name IOPCBbbb.
AIBOALEN
I/O area length. This field must contain the length of the I/O area that is specified in the call list.
i/o area
Specifies the I/O area used for the call. This parameter is an input and output parameter.

I/O Area

The following tables show the format of the parameter list in the I/O area before the AUTH call is issued.

I/O area before the AUTH call
Table 1. I/O area before the AUTH call is issued for AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, and PASTDLI interfaces
Field Name Field Length
LL 2
ZZ 2
CLASSNAME 8
RESOURCE 8
USERDATA 8
Table 2. I/O area before the AUTH call is issued for the PLITDLI interface
Field Name Field Length
LLLL 4
ZZ 2
CLASSNAME 8
RESOURCE 8
USERDATA 8
LL or LLLL
specifies a 2-byte field that contains the length of the parameter list, including two bytes for LL. For the PLITDLI interface, use the 4-byte field LLLL. However, if you use the AIBTDLI interface, PL/I programs require only a 2-byte field.
ZZ
specifies a 2-byte field that contains binary zeros.
CLASSNAME
specifies an 8-byte field that contains one of the following values:
  • TRANbbbb
  • DATABASE
  • SEGMENTb
  • FIELDbbb
  • OTHERbbb

All parameters are 8 bytes in length, left-justified, and must be padded to the right with blanks.

The use of a generic class name in the call parameter list eliminates the need for the application to be sensitive to the actual Resource Access Control Facility (RACF®) class names being used. Since transaction authorization must be active, only the RACF class associated with the generic class name identifier for the transaction class must be defined. The generic class name in the call parameter list causes the authorization function to select the proper RACF class and request access checking for that class.

RESOURCE
specifies the 8-byte field that contains the name of the resource to be checked. Except for the generic class TRAN, the resource name can be whatever the application designates because the name has no meaning for IMS TM.

IMS TM performs no validity checking of the resource name.

USERDATA
specifies the 8-byte keyword constant USERDATA is the only value supported. Its presence in the parameter list means that the application program wants any RACF installation data that exists in the RACF accessor environment element (ACEE).

The following tables show the I/O area after the AUTH call.

I/O area after the AUTH call
Table 3. I/O area after the AUTH call is issued for AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, and PASTDLI interfaces
Field Name Field Length
LL 2
ZZ 2
FEEDBACK 2
EXITRC 2
STATUS 2
RESERVED 16
UL 2
USERDATA Variable
Table 4. I/O area after the AUTH call is issued for the PLITDLI interface
Field Name Field Length
LLLL 4
ZZ 2
FEEDBACK 2
EXITRC 2
STATUS 2
RESERVED 16
UL 2
USERDATA Variable
LL or LLLL
A 2-byte field that contains the length of the character string, plus 2 bytes for LL. For the PLITDLI interface, use the 4-byte field LLLL. However, if you use the AIBTDLI interface, PL/I programs require only a 2-byte field.
ZZ
specifies a 2-byte field that contains binary zeros.
FEEDBACK
specifies a 2-byte field that contains one of the following RACF return codes:
0000
User is authorized.
0004
Resource or class not defined.
0008
User is not authorized.
000C
RACF is not active.
0010
Invalid installation exit return code.
EXITRC
specifies a 2-byte field that contains the return code from the user exits if they were used. The EXITRC field contains the return code from the last user exit that was entered. If none of the user exits are present or invoked, the field contains binary zeros. If installation data is returned from the exit, the EXITRC field is set to zero to indicate an authorized return code from the exit.
STATUS
specifies a 2-byte field that contains the hexadecimal status code indicating installation data status:
0000
RACF installation data is present in the I/O area.
0004
Security exit installation data present in then I/O area.
0008
User is not currently signed on.
000C
User is not authorized, so installation data is not made available, or user is authorized, but no installation data has been defined.
0010
User was authorized, but installation data was not requested.
0014
USERDATA exceeds PSBWORK area length.
0018
RACF not active and TRN=N defined.
RESERVED
Binary zeros (reserved)
UL
specifies a 2-byte field that specifies the length of the installation data, including the length of the UL parameter.
USERDATA
specifies a variable-length field that contains installation data from ACEE or a user security exit. The length of the installation data is limited to 1026 bytes, including the length (UL) field. If a security exit returns a value greater than 1026, IMS truncates the installation data and adjusts the length field to represent the amount of installation data actually returned to the application program. If security exit installation data is returned, IMS passes it to the application program even if the parameter list did not contain the USERDATA parameter.

Any available installation data is returned if the return code from RACF indicates that the user is authorized to the resource named in the call parameter list. No installation data is returned if the user who originated the transaction is no longer signed on to the terminal associated with the transaction. Installation data might or might not be provided by the security exits when they are involved in the security decision. However, when either of the exits returns installation data, IMS passes it on to the application program.

If provided, installation data is returned from a security exit to the application even when the call parameter list does not specify the USERDATA parameter. In that case, the STATUS field of the I/O area contains the code X'0004' indicating the presence of the installation data.

Usage

The AUTH call determines whether a user is authorized to access the resources specified on the AUTH call. AUTH is issued with an I/O PCB and its function depends on the application program. Authorization checking depends on the dependent region type and whether a GU call has been issued. The call functions are as follows:

  • In BMPs, AUTH uses the user ID of the IMS control region or installation specific user exits to determine the status of the call.
  • For BMPs that have issued a successful GU call to the I/O PCB, AUTH functions as it does in an MPP.
  • In MPPs, AUTH verifies user authorization with RACF for the specified resource classes of those resources used by the application program.

Because the call can request RACF user data to be passed back in the I/O area as installation data, the processing of the call always results in changes to the STATUS field in the I/O area. This STATUS field notifies the application of the status of installation data in the I/O area: available or not available. It might not be available because the installation data is not defined or the originating user is no longer signed on to the IMS system.

Either of the supported security exits for transaction authorization (DFSCTRN0 or DFSCTSE0) can present installation data upon return to IMS. If an exit returns installation data, the data is returned to the application even if the parameter list did not contain the USERDATA parameter. The STATUS field is set to indicate the origination of the installation data. The STATUS field indicates the presence of either RACF installation data or security exit installation data.

The application program also receives notification of the actual RACF return code. This return code, presented as FEEDBACK in the I/O area, can be used by the application program to detect inconsistent operational modes and take alternate action. Examples of inconsistent operational modes are the proper RACF classes not being defined or the requested resource not properly defined to RACF.

By checking the FEEDBACK, EXITRC, and STATUS in the I/O area, the application program can be sensitive to issues such as the proper RACF definitions and resources not being defined. If RACF is being used, and the AUTH call references any resources that are not defined, the PCB status code is set to blanks and the FEEDBACK field of the I/O area is set to indicate that the resource is not protected.

Because the value for EXITRC is provided by a user security exit, use of this field must be made with an understanding of exit operation and the knowledge that any changes to the exit can result in application errors. If due to operational errors, the proper resources are not protected, the application can deal with the error in any way. This feedback can make operational control simpler and give the application more flexibility.

Related reading: RACF terms and concepts are discussed in more detail in other information units. For additional information, see IMS Version 15.4 System Administration and IMS Version 15.4 Exit Routines.

Restrictions

The AUTH call must not be issued before a successful GU call to the I/O PCB.