Subsystem SVC screening

After you write an SVC routine and insert it into the system, the routine is generally available unless you take steps to regulate access to the routine. Subsystem SVC screening allows a system routine to define those SVCs that a specific task can validly issue. When SVC screening is active for a task, the system determines, for each SVC issued by that task, whether the task can request that SVC function. If the SVC request is invalid, control is given to a special error subroutine supplied by the routine that activated the screening function.

The subsystem, executing under PSW key zero, activates SVC screening by setting two fields in each TCB for which screening is desired. The two fields consist of a screen flag bit and a one-word field containing the address of the subsystem screen table, which provides the interface between the SVC FLIH and the subsystem subroutine. In addition to these fields, the subsystem may optionally set the TCBSVCSP bit to indicate that ATTACH processing is to pass the SVC screening information to the attached task. The important SVC screening fields in the TCB are:

TCBSVCS - A flag bit. When set to one, it indicates that screening is in effect for this task.
TCBSVCA2 - Address of the subsystem screen table.
TCBSVCSP - Propagation bit. When set to one, it indicates that ATTACH processing should pass the SVC screening information in these three fields to the attached task.

When the screening facility detects an invalid SVC, it gives control to the specified error routine. The error routine receives control as an SVC and is subject to the same restrictions as SVC routines. Before giving control to the subroutine, the SVC FLIH provides the setup for the subroutine as defined by the subsystem SVC entry (SSTSVCN) in the subsystem screen table. This setup includes:

Initializing the SVRB if the subroutine is to execute as a type 2, 3, or 4 SVC.
Obtaining the LOCAL lock if the subroutine is to execute as a type 1 SVC.
Acquiring all locks necessary for the subroutine's execution.

The subsystem that needs SVC screening obtains storage via GETMAIN for an area called the subsystem screen table. For non-extended SVC screening, the subsystem screen table is 264 bytes in size. For extended SVC screening, the subsystem screen table is 1288 bytes in size. To prevent a page fault, this area must come from the LSQA (subpool 253-255), the SQA (subpool 245), or must be in fixed storage. If the subsystem screen table is in fixed storage, the subsystem must ensure that the storage is protected from user modification. The subsystem screen table contains two areas as follows:

1) SSTSVCN -- Subsystem SVC entry (8 bytes)

Byte	Bit	Contents
0-3	0	One of the following: 0 - Indicates 24-bit addressing mode 1 - Indicates 31-bit addressing mode
	1-31	Entry point address of the subsystem subroutine that will get control whenever a task has issued an SVC against which there is a screening restriction.
Byte 4		X'00' The subroutine is to run as a Type 1 SVC X'08' The subroutine may be used only by a program that is APF authorized X'80' The subroutine is to execute as a Type 2 SVC X'C0' The subroutine is to execute as a Type 3 or Type 4 SVC X'20' The subroutine is to execute as a Type 6 SVC
Byte 5		One of the following: Bit 0 is used to indicate if the SVC may be issued in AR mode. Set bit 0 to 1 to indicate that the SVC may be issued in AR mode. Bit 7 is used to screen individual extended SVCs. Set bit 7 to 1 to screen individual extended SVCs. When screening extended SVCs, the SVC screening mask must be 1280 bytes in size instead of 256 bytes.
Bytes 6-7		Locks to be held on entry to the subroutine. If the appropriate lock bit is one, the lock will be acquired by the SVC FLIH. The lock bits are: Bit Lock 0 LOCAL 1 CMS Bits 2–15 are always zero (off).

2) SSTMASK -- SVC screening mask (256 bytes or 1280 bytes)

If you are not screening extended SVCs (bit 7 of byte 6 of the SSTSVCN is zero), then SSTMASK will be 256 bytes long. If you are screening extended SVCs (bit 7 of byte 6 of the SSTSVCN is one), then SSTMASK must be 1280 bytes long.

Bytes: Content
8-263: Each byte corresponds to an SVC number in ascending order in the range 0-255. When the high order bit in a byte is one, the task may validly issue the respective SVC; when the bit is zero, there is a screening restriction that prohibits the task from issuing the SVC.
264-519: Each byte corresponds to an SVC routing number in ascending order in the range 0-255 for SVC 109.
520-775: Each byte corresponds to an SVC routing number in ascending order in the range 0-255 for SVC 116.
776-1031: Each byte corresponds to an SVC routing number in ascending order in the range 0-255 for SVC 122.
1032-1287: Each byte corresponds to an SVC routing number in ascending order in the range 0-255 for SVC 137.

Note: Each SVC's data must be 256 bytes long, even though the system only supports all 256 routing codes for extended SVC 109.

When you use SVC screening with the ESR function, and a program issues an extended SVC, the system ignores the screening information provided for the SVC number itself (for example, 109). Instead, it looks only at the screening information provided for the particular routing code. See SVCUPDTE in z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for more information about specifying the ESR parameter.

Note: Before terminating, the subsystem must clear the TCBSVCS bit, in all of the effected TCBs, before freeing the storage used for the screening table. Failure to turn off SVC screening by clearing the TCBSVCS bit can result in the loss of one or more systems. It is also recommended that the TCBSVCA2 screening table pointer be zeroed, and that the TCBSVCSP bit be cleared.