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:
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.
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.
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' | |
| 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 |
The following table summarizes the ULSRSEC linkage conventions.
| Feature | Convention | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Attributes | Reentrant. | ||||||||||||||||||||||||||||||||
| Type | Nucleus. | ||||||||||||||||||||||||||||||||
| Size | No restriction. | ||||||||||||||||||||||||||||||||
| Registers at Entry |
|
||||||||||||||||||||||||||||||||
| Registers at Return | Registers must be restored, except register 15, which must contain a return code. | ||||||||||||||||||||||||||||||||
| Return Codes |
|
||||||||||||||||||||||||||||||||
| Considerations |
|
* Not for the INIT call.