USTRE1 - USTOR User Exit

USTRE1 is a user-written routine called by the USTOR utility program before the execution of any command function requested by the terminal operator. This routine allows you to define security restrictions on the use of the various functions.

Each time the terminal operator issues a new command or presses ENTER, a call is made to USTRE1 before the requested function is serviced. Consequently, the installation may restrict, permit, or eliminate any or all of the USTOR functions.

USTRE1 can issue any Com-plete function in the process of determining the security restrictions to be imposed upon the terminal user. Sample functions include:

  • COLOAD Loads a table containing security information.

  • COLINK Invokes another user-written program.

  • GETCHR Obtains information about the terminal user.

  • WRTC Requests additional information.

  • READ Obtains the requested information.

  • MESGSW Logs a security violation.

Because the USTRE1 module is only loaded once per invocation of USTOR, internal switches can be set and subsequently referred to. Note that each new invocation of USTOR loads a new version of USTRE1, thus causing the switches to be reset.

A dummy USTRE1 is distributed with the Com-plete system as a member of the distribution source library and the distribution load library.

Note:
No additional security exist for USTOR functions unless it is established by you.

This document covers the following topics:

How to Create USTRE1

To create a new USTRE1 exit routine, proceed as follows:

Step 1

Code the desired module using the member USTRE1 in the distribution source library as a guide.

Step 2

Assemble and link the new module into the user load library.

Step 3

Delete the old USTRE1 from the program library.

Step 4

Catalog the new USTRE1 to the program library.

Step 5

Test the new exit by invoking USTOR.

If an error exists in the new USTRE1 exit routine, USTOR may terminate abnormally. It is therefore recommended that precautions be taken to retain a usable copy of USTRE1 in order to ensure continued reliable service.

USTRE1 is loaded once during the initialization of USTOR.

Size restrictions are not imposed on USTRE1. Size is a consideration, however, because not only must the exit fit into the same thread in which USTOR executes, but the cataloged region size of USTOR must also consider the size of USTRE1. Note that if there is insufficient storage to load USTRE1, an error will result.

How to Use USTRE1

Upon entry to USTRE1, a set of parameters is received in the form of fullword addresses pointed to by register 1. Word 1 of the parameter list contains the address of Com-plete's COMREG. Word 2 contains the address of the current UPCB. Word 3 contains the address of the current THCB. Word 4 contains the address of the current TIB. Word 5 contains the address of the USTOR command just provided by the terminal user. Word 6 contains the address of a halfword to be used by USTRE1 to pass a return code back to USTOR.

Security is provided by determining if the current user or TIB is permitted to execute the requested USTOR function and setting the return code accordingly.

USTRE1 Conventions

The following table summarizes the USTRE1 linkage conventions.

Feature Convention
Attributes None required
Size Limited only by the USTOR thread size.
Registers at Entry
Register 1 Address of the parameter list
Register 13 Address of an 18-word save area
Register 14 Return address in USTOR
Register 15 Entry point address in USTRE1
Registers at Return Registers 2 through 13 must be unchanged.
Parameters
Word 1 Address of the COMREG
Word 2 Address of the UPCB
Word 3 Address of the THCB
Word 4 Address of the TIB
Word 5 Address of the USTOR function
Word 6 Address of a return code halfword
Return Codes
0 Allow the request.
4 Disallow the request.
8 Disallow the request, and terminate USTOR.
Considerations Is loaded once per invocation of USTOR.