# MVS Supervisor Services

The Shadow REXXTOOLS function package includes functions that provide access to MVS control program services. Using these services, you can write programs that:

- Explicitly manage virtual storage.
- Obtain system-wide control of resources before using them.
- Query the system authorization facility about the user's authority to use a resource.
- Write messages to the system log and to the system operator's console.

Environmental Issues | Virtual Storage Management
Resource Control | Security
Operator Communications | Service Descriptions

## Environmental Issues

The MVS supervisor service functions of Shadow REXXTOOLS provide only those services that are available to all problem state programs. Privileged operations (those requiring APF authorization, supervisor state, or key zero) are not supported.

Unless stated otherwise, MVS supervisor services are MVS task-related. Any resources allocated or reserved using the MVS supervisor services functions, but not freed or released, will be automatically cleaned-up by the control program at task termination. No resource clean-up takes place for REXX programs invoked using either the CALL instruction or the function call, since they do not run on a new MVS task level. If you do not explicitly free resources allocated by programs invoked in this way, and if they are repeatedly invoked from the same task, unpredictable abends may occur.

## Virtual Storage Management

Two functions are provided for virtual storage management:

GETMAIN
  a function for requesting an allocation of virtual storage.
FREEMAIN
  a function for relinquishing virtual storage.

When you allocate virtual storage, the storage is assigned to a subpool. You can control which subpool an individual allocation is assigned to using the sp argument. The valid range of subpool numbers is 0 to 127. If you do not specify a subpool, subpool zero is assumed. By grouping related storage allocations into the same subpool, you can release several areas with a single FREEMAIN.

When used with the REXX STORAGE function (or the REXXTOOLS STORAGEX function), virtual storage can be used to communicate between REXX programs and programs written in other languages, such as assembler. For example, by allocating a work area and passing the address of the work area to a called (or linked) program, you can economically pass a large and complex data structure. Moreover, if the called program modifies the data structure, the calling (REXX) program will have access to the changes when control is returned.

## Resource Control

A common programming problem is the synchronization of asynchronous processes for the purpose of sharing a resource. Shadow REXXTOOLS supports two sets of functions that address this problem. The first set permits you to acquire and release control of arbitrary resources. There are two functions that support this function. These are:

ENQ
  a function for acquiring control of a resource before using it. The caller of ENQ can optionally wait for a resource if it is not immediately available.
DEQ
  a function for releasing a previously ENQed resource.

The MVS ENQ/DEQ facility can be thought of as a system-wide resource reservation system. Before you use a resource, you must first make a reservation using the ENQ function. When you are finished with the resource, you "check out" using the DEQ function. Note though, that for arbitrary, user-defined resources, there is nothing in the system to prevent cheaters (i.e., programs that use resources without first reserving them). The ENQ/DEQ mechanism works only as long as all the participating programs "play by the rules."

Note: If you are considering writing multiple user VSAM-based applications, and you want to provide record (control interval) level locking, you will need to use the ENQ and DEQ functions. The details of this process are described in the IBM publication MVS/ESA Using Data sets, SC26-4749.

The second set of synchronization functions are for halting the execution of programs until conditions are such that execution can continue. These are:

WAIT
  a function for halting the execution of a REXX program. A program can wait on a timer to expire or for the completion of an arbitrarily defined event.
POST
  a function for signaling the completion of an arbitrary event.

The non-timer forms of WAIT and POST require the use of a 4 byte control block know as the Event Control Block (ECB). Since the ECB is identified by a storage address, its explicit allocation (either via the GETMAIN function or some other equivalent program) is required.

## Security

The MVS System Authorization Facility (SAF) provides a centralized and generalized mechanism for directing authorization requests to whatever system security package your installation is running (RACF, ACF2, Top Secret, etc.). Authorization requests are implicitly made whenever you use certain system resources, such as data sets. The access methods (like VSAM) invoke the SAF to provide protection for the resources (data sets) that they manage. However, the protection provided by the SAF and your security package is not limited to data sets. Arbitrary resources can be defined and protected using user-supplied programs as the resource managers.

The Shadow REXXTOOLS interface to the SAF is the RACROUTE function. Your REXX programs can protect an arbitrary resource by calling RACROUTE and passing the name of the resource. If your security administrator has defined the resource, and if the user has been authorized to use the resource, the RACROUTE function will return an indication that the access is to be allowed. RACROUTE, itself, does not allow or deny access to a resource. Your program, the resource manager, must do that part.

Notes:

1. The SAF must be active and the router table must be properly configured in order for RACROUTE requests to be propagated to the system security package.
2. Not all RACROUTE functions are supported. Specifically, the parameters requiring APF or key zero, supervisor state authorizations are not supported. This includes the parameter to suppress SMF recording.

## Operator Communication

Four functions are provided for communicating with the system operator and for placing messages in the system log. These are:

WTL
  a function for writing single-line messages to the system log.
WTO
  a function for writing single-line and multi-line messages to the system operator's console and to the system log.
WTOR
  a function for querying the system operator for information. This function prompts the operator for information and returns the information entered by the operator in a REXX variable.
DOM
  a function for removing previously sent messages from the system operator's console.

WARNING: If your program writes large numbers of messages to the operator console, you may impair the ability of system operators to manage the system. In addition, depending on the size of the console buffers, you could cause a console buffer shortage condition.

### Specifying Routing Codes

You can control the console to which the WTO and WTOR functions send messages using route codes. The actual consoles to which the messages will be sent depends upon how the consoles have been defined. If, for example, you are sending a message using a route code of 3 (tape pool), but there is no console that is "listening" for route code 3 messages, the message will not appear anywhere (except the system log). The following table gives the first 16 routing codes. These codes are the ones most commonly used.

1
  Master console action
2
  Master console information
3
  Tape pool
4
  Direct access pool
5
  Tape library
6
  Disk library
7
  Unit record pool
8
  Teleprocessing control
9
  System security
10
  System error/maintenance
11
  Programmer information
12
  Emulators
13
  Customer defined
14
  Customer defined
15
  Customer defined
16
  Customer defined

### Specifying Descriptor Codes

By specifying descriptor codes you can control how your messages appear (i.e., color, intensity, scrollability).18 The actual appearance of a message is dependent on definitions supplied by your systems programmer. The following table gives the first 16 descriptor codes. These codes are the ones most commonly used.

1
  System failure
2
  Immediate action required
3
  Eventual action required
4
  System status
5
  Immediate command response
6
  Job status
7
  Application program
8
  Out-of-line message
9
  Operator request
10
  Dynamic status display
11
  Critical eventual action
12
  reserved
13
  reserved
14
  reserved
15
  reserved
16
  reserved

## Service Descriptions

The sections that follow describe the syntax and operation of the MVS supervisor services-related functions.

DEQ

DOM

ENQ

FREEMAIN

GETMAIN

POST

RACROUTE

WAIT

WTL

WTO

WTOR

© Copyright 1998 by Open Software Technologies, Inc.