Data Set Authorization Exits Support › Writing a Data Set Access Authorization Exit

Writing a Data Set Access Authorization Exit

The authorization exit is attached and operates as a subtask. Therefore, complex processing, WAITs, or SVCs do not impact overall performance.

Review the source code for the sample data set access authorization exit NMDSNCHK and use it as a guide to writing your own exit.

Registers on Entry to the Exit

When the exit is invoked, Register 1 contains the address of a communication area containing various parameters. This communication area can be mapped using the macro $NMDSNCK, supplied in the distribution libraries. This macro provides a DSECT expansion to perform the mapping, and detailed information on the content of each field.

Standard linkage conventions apply. On entry, the exit must save the contents of all registers (Register 13 contains the address of a save area), and on exit all registers must be restored to their content on entry, with the exception of Register 15 which should contain a return code.

Parameters Passed to the Exit

The data set access authorization exit is provided so that the installation can determine whether access to a data set is to be permitted.

• When invoked as a result of an ALLOCATE command, a communication area containing the following information is passed to the exit:
  • Data set name
  • User ID of requestor
• When invoked as a result of a CA SOLVE:FTS operation, a communication area containing the following information is passed to the exit:
  • Data set names
  • DD statement names
  • Class of transmission
  • Type of access required (READ at the sending end, READ/WRITE at the receiving end)
  • Whether this request is a SYSTEM or PRIVATE request
  • Type of data set allocation (NEW, SHR, and so on)
  • CA SOLVE:FTS ID
  • Transmission Definition password
  • CA SOLVE:FTS user ID of requestor
  • Space allocation and volume information, if this is a NEW data set

The format of this area is mapped by the supplied $NMDSNCK DSECT.

Calls Made to the Exit

Whenever you use the ALLOCATE command to allocate a data set, a call is made to the authorization exit. A call is also made to the authorization exit when CA SOLVE:FTS identifies the data set that is to be transmitted or received. Calls are therefore made both at the transmitting and at the receiving end of a transmission operation.

On return from the initial call, the exit may set indicator flags (see the DSNCFLG field in the $NMDSNCK DSECT) that determine which subsequent calls CA SOLVE:FTS is to make to the exit during the progress of the transmission operation.

The following additional calls are made as requested by the exit:

• Preallocation call—made before the target data set is dynamically allocated
• Pre-open call—made just before the target data set is opened
• Pre-deallocation call—made just before the target data set is dynamically deallocated

Identifying the Type of Call

The type of call being made to the exit is identified by the DSNSTYPE field in the exit communication area. This field is set as follows:

• F'0'

  Indicates a call for CA SOLVE:FTS access authorization.

• F'4'

  Indicates a call for the CA SOLVE:FTS allocation subtask.

• F'8'

  Indicates a call for the CA SOLVE:FTS open subtask or file.

• F'12'

  Indicates a call for the CA SOLVE:FTS deallocation subtask.

• F'16'

  Indicates a call for an ALLOCATE command.

If your installation uses RACF security software, the exit can make a call to RACF to associate the allocation with the requesting user ID rather than with your product region.

Modifying Transmission Information

Note: This section only applies to CA SOLVE:FTS.

In the initial access authorization call to NMDSNCHK, at the receiving end of a transmission, you can use the exit to overwrite some of the values passed to it in $NMDSNCK, and use these new values for the transmission, thereby enforcing your organization's security, naming, and allocation standards on incoming transmissions.

You can overwrite the following fields:

• DSNCDSN

  The receiving data set name

For new data sets only, you can overwrite the following fields:

• DSNCVOL

  The volume on which the data set is to be allocated

• DSNCDEVT

  The device type on which the data set is to be allocated

• DSNCSPCE

  The space allocation units to be used (CYLS, BLKS, or TRKS)

• DSNCPRIM

  The primary allocation amount

• DSNCSECN

  The secondary allocation amount

• DSNCDIR

  The directory blocks to be allocated

If you change any of these fields, you must set the DSNMODR flag to indicate that the changed values are to be substituted for the defined values for this transmission. If invalid values are returned in any field, the transmission will be terminated.

Note: You can only change these fields on the initial call for incoming transmissions. If the above fields are modified or the DSNMODR bit set at any other time, the modifications will be ignored.

Return Codes From the Exit

A return code is set in Register 15 on return from all calls to the exit, indicating the action that should be taken:

• 0

  Indicates that access is permitted. Allocation can proceed.

• 4

  Indicates that access is denied. An error message can be placed in the field DSNCTMSG, and its length in the field DSNCLMSG, in the communication area.

If the authorization exit is called by CA SOLVE:FTS and elects to receive the calls subsequent to the initial authorization call, return code 4, set in register 15 on return from any of those calls, will cause termination of the transmission at that point. The exit indicates which, if any, of the subsequent calls are required.

The additional calls to the exit allow greater control over the significant data set-specific operations that are involved in a transmission, letting the exit perform ENQ/DEQ functions to prevent duplicate access to data sets.

For RACF security software, the exit may call RACF at these times to associate the security responsibility for the action against the requesting user ID, rather than against CA SOLVE:FTS itself.