The NCL authorization exit, NCLEX01, controls access to the following:
Access can be restricted to certain levels, or can be denied altogether. For example, the level of access to a database can be used to restrict users to read only or update without delete.
The exit is invoked automatically the first time an NCL procedure attempts to open a database, using the &FILE OPEN, &EDB, or &NDBOPEN statement, or write a record using the &SMFWRITE statement. The level of access permitted is set by a return code from the exit and is made available to the NCL procedure.
Note: If an exit controls the writing of SMF records in z/OS systems, it needs to provide clearance for a user to use the &SMFWRITE verb.
You can also define other uses for the NCL exit by tailoring the supplied NCLEX01 or writing your own.
To activate the NCL authorization exit, specify the name of the load module to be invoked in the SYSPARMS NCLEX01 operand. To ensure that the exit is always activated during system initialization, place the SYSPARMS command in the INIT initialization member. If no exit is required specify SYSPARMS NCLEX01=NO. If necessary the name of the exit can be changed online and a new module invoked.
Note: For information about the SYSPARM NCLEX01 operand, see the Reference Guide.
Note: If you are using a security product, such as RACF, to control VSAM file access, ensure that your product region itself is authorized for file access.
The exit executes within a subtask and can therefore issue a WAIT or SVC that causes suspension of the task without affecting the primary task.
The exit is passed a parameter list that provides information about the request. Write the exit as a reentrant facility so that multiple concurrent requests are possible.
For performance reasons, calls to NCLEX01 are not generated to the high-usage system files MODS and $PSPOOL.
If an ABEND occurs within the exit, any current request is rejected as though access had been denied. Although this can impact the requesting NCL procedure, other processing is not affected. Subsequent requests to the exit continue without impact.
When the exit is invoked, it is passed a communication area that provides information about the request and the requestor. The $NMNCEX1 macro, as supplied in the macro library, describes this area. The macro is distributed as follows:
Specifies your site-specific data set name prefix.
Specifies your product version prefix.
You can load a single copy of the exit into the region in advance to avoid the overhead of the loading process. To do this, specify the name of the exit in the LOAD MODULE operand.
If the exit is link edited with the RENT (reentrant) attribute, this single copy is shared concurrently among multiple requestors.
Important! It is strongly recommended that you make the NCL exit module reentrant. Failure to do so causes significant additional disk activity and resource consumption in a busy system, and can impact overall performance.
You can provide additional checking for access through the NCL authorization exit. This additional information is specified on the &FILE OPEN statement.
Example:
To have the exit ask for the user's password to confirm access to a particular UDB, the password information should be coded in the exit as follows:
&FILE OPEN ID=MYFILE DATA=&MYPASSWD
&FILE OPEN ID=MYFILE FORMAT=UNMAPPED DATA=&MYPASSWD
The exit will interrogate the password and set an appropriate return code to control the subsequent processing in the NCL procedure.
A maximum of 50 characters of data can be passed. This data is available to the exit in the NEXUDATA field. The length of the data passed is set in the NEXUDLEN field. No validation is performed on passed data.
If you have a partial or full security exit you can correlate access to UDBs by sharing information between your external security exit and the NCL authorization exit.
The NEXCORR field of the communications area in the NCL authorization exit is the standard correlator that can be used by your external security exit. This could, for example, be used to address a control block that contains information associated with that user.
If your external security exit supports a SAF user token, then this is also available in the NEXUTOKN field in the communications area. This user token is the UTOKEN provided by the external security exit when the user logs on, and can be used in a security authorization call to verify the user's access to the UDB.
A sample exit, NCLEX01, is supplied in the SMP target zone library, dsnpref.pvpref.CC2DSAMP where: