ULSRSEC - User-Written Service Routine

#### Search Results

Search

# ULSRSEC - User-Written Service Routine

Note
Because security afforded by this service routine is system-wide in scope, thorough design and analysis are recommended before implementation in order to ensure minimal impact upon performance.

This module is to be used as a single routine to service file access related security check requests in utility programs.

This section is to be used as a guide to modifying the ULSRSEC member in the distribution source library. It also refers to the security control area that is described in detail in the distribution source member CMSCA.

This document covers the following topics:

- Initialization Overview

- Initialization Processing

- How to Use ULSRSEC

- ULSRSEC Conventions

## Initialization Overview

When Com-plete is initially installed, a dummy ULSRSEC module exists in the distribution source library to serve as a guide. This routine must be coded, assembled, and link edited. The initial Com-plete control program contains a ULSRSEC routine that enforces standard z/OS password protection for the UPDS, UED, UMAP, UEDIT, UDS, and ULIB utility programs.

Since ULSRSEC executes as a service routine of Com-plete, it is dispatched in supervisor state and in the key of Com-plete. Consequently, if an abend occurs while ULSRSEC is executing, Com-plete terminates abnormally.

Because ULSRSEC is entered frequently, any required tables should be loaded during initialization. The work area passed to ULSRSEC can be expanded if more space is needed.

## Initialization Processing

ULSRSEC is given control once during Com-plete initialization, so this portion of ULSRSEC need not be reentrant. If a large routine is required, it could be coded in a routine called by ULSRSEC.

Suggested uses for the initialization routine are:

- To set the value of the CSEWORK field in the Com-plete communication region. This HW field contains a value from 0 to 8000; this is the amount of work space to be obtained by calling routines as a work area for this module. Refer to the label DWORK in the ULSRSEC example.

- To load security tables.

- To set up interfaces with security packages.*

* This applies only to security packages which do not support the SAF interface. Com-plete provides data set protection via this facility as standard. See section Software Interfaces for more information.

The register conventions for the initialization functions are as documented for security checks, and the SCAFUNC field is set to INIT.

A mainline routine is provided to process security check requests. Note that this routine must be reentrant. A save area is provided and already pointed to by register 13. Work areas can be appended to the SCA, but the CSEWORK field must have been set to the proper value. Refer to label DWORK in the ULSRSEC example. Note also that any SVC can be issued, but no MCALL functions are allowed.

## How to Use ULSRSEC

Refer to member CMSCA in the distributed source library for the format and field names of the SCA referred to in this section. The SCA is used to pass the description of user requests to ULSRSEC from the Com-plete nucleus and utility programs. The SCAFUNC field describes the type of request. The SCARDESC field describes the type of resource, and the SCARRES field actually names the resource (DSN, PGMNAME, etc.). Note that for the current version of Com-plete, only the values DSN, ULIB, and USR are passed to ULSRSEC in the SCARDESC field.

By examining the SCA, access can be limited to any described resource by setting a return code before returning control to Com-plete.

The following tables summarize the SCA field values upon entry to ULSRSEC by utility or file I/O operation. Note that the SCAFUNC value INIT is not documented in the tables, because it does not relate to any particular utility.

SCA Field | Value | UDS Utility Command
SCARDESC | 'DSN' | -
SCARDSN | File Name | -
SCARVOL | Volume Serial Number | -
SCAFUNC | 'INQ' | LIST
SCAFUNC | 'READ' | DISPLAY
SCAFUNC | 'READ' | PRINT
SCAFUNC | 'READ' | COPY
SCAFUNC | 'WRIT' | SCRATCH
SCAFUNC | 'WRIT' | RENAME
SCAFUNC | 'WRIT' | ALIAS
SCAFUNC | 'WRIT' | ZAP

SCA Field | Value | UPDS Utility Command
SCARDESC | 'DSN' | -
SCARDSN | File Name | -
SCARVOL | Volser | -
SCAFUNC | 'INQ' | DISPLAY
SCAFUNC | 'INQ' | FIND
SCAFUNC | 'INQ' | LIST
SCAFUNC | 'CATL' | RECATLOG
SCAFUNC | 'CATL' | CATALOG
SCAFUNC | 'CATL' | UNCATALOG
SCAFUNC | 'CATL' | RENAME
SCAFUNC | 'ALLO' | PURGE
SCAFUNC | 'ALLO' | SCRATCH
SCAFUNC | 'ALLO' | ALLOCATE

SCA Field | Value | UMAP Utility Command
SCARDESC | 'DSN' | -
SCARDSN | File Name | -
SCARVOL | Volser | -
SCAFUNC | 'WRIT' | Any effort to SAVE the map in the load library
SCAFUNC | 'READ' | All operations on temporary maps in the SDfile

SCA Field | Value | UEDIT/UED Utility Command
SCARDESC | 'DSN' | -
SCARDSN | File Name | -
SCARVOL | Volser | -
SCAFUNC | 'WRIT' | Any SAVE, RSAVE, or FILE that writes to the library
SCAFUNC | 'READ' | Any operation other than SAVE, RSAVE, and FILE that does not write to the library

SCA Field | Value | ULIB Utility Command
SCARDESC | 'ULIB' | -
SCARDSN | - | -
SCARVOL | - | -
SCARULTP | 'PGM' | -
SCAFUNC | 'WRIT' | CAT
SCAFUNC | 'WRIT' | DEL
SCAFUNC | 'INQ' | DISPLAY

SCA Field | Value | User VSAM/BDAM/ISAM Requests Utility Command
SCARDESC | 'DSN' | -
SCARDSN | File Name | -
SCAFUNC | 'READ' | READ
SCAFUNC | 'WRIT' | WRITE
SCAFUNC | 'WRIT' | UPDATE

## ULSRSEC Conventions

The following table summarizes the ULSRSEC linkage conventions.

Feature | Convention
--- | ---
Attributes | Reentrant.
Type | Nucleus.
Size | No restriction.
Registers at Entry |
Register 0 | Available
Register 1 | Available
Register 2 | Com-plete Communications Region (COMREG)
Register 3 | User Program Control Block (UPCB)*
Register 4 | Thread Control Block (THCB)
Register 5 | Terminal Information Block (TIB)*
Register 6 | Reserved for future expansion
Register 7 | Available
Register 8 | Available
Register 9 | Available
Register A | Available
Register B | Base 2
Register C | Base 1
Register D | Save area and SCA address
Register E | Available
Register F | Available
Registers at Return | Registers must be restored, except register 15, which must contain a return code.
Return Codes |
0 | Security passed.
4 | Security check failed due to lack of or incorrect information. The SCARC field must be set to the following values :
0 | password failed
4 | unexpired file
8 to 16 | reserved
8 | Security failed.
12 | SCA invalid.
Considerations |
a | Referenced tables must be loaded during initialization.
b | Registers must be saved and restored.
c | The module must be reentrant, except for the initialization routine.
d | The module runs as a portion of the Com-plete nucleus; it is therefore advisable to maintain a backup copy of this module or a backup of the entire Com-plete control program.
e | Called in Com-plete's key
f | All control blocks and areas passed for the use of the exit will be in Com-plete's key.
g | Active thread will generally be in a different key to Com-plete's key.

* Not for the INIT call.

### On this page

- Initialization Overview
- Initialization Processing
- How to Use ULSRSEC
- ULSRSEC Conventions