HIS.SERVSTAT— HISSERV Service Exit

Topics for This Exit Appear as Follows:

Controlling the Exit Routine Through the Dynamic Exits Facility
Replacing the Exit Routine
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
Return Specifications
Coded Example of the Exit Routine

The HIS.SERVSTAT exit will be defined by IBM. Any authorized program that wants to know the state of the HISSERV service can register with the HIS.SERVSTAT dynamic exit. For example, an exit can provide a bootstrap process for potential exploiters of the HISSERV service, as a mechanism to know when a program is able to begin exploiting the service. Exit routines are called for the following reasons:

The HISSERV service has been enabled.
The HISSERV service has started instrumentation data collection.
The HISSERV service has stopped instrumentation data collection.
The HISSERV service had been disabled.

The HISYEXIT macro maps the storage passed to a HIS exit routine that is monitoring the service.

Controlling the Exit Routine Through the Dynamic Exits Facility

The exit routine is defined by registering an exit routine with the HIS.SERVSTAT dynamic exit. Note exit routines registered with the HIS.SERVSTAT dynamic exit do not have the ability to receive instrumentation data, only monitor the state of the service. You can use the CSVDYNEX macro to control the HIS.SERVSTAT dynamic exit and its exit routines.

You can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro to limit the number of times the exit routine abnormally ends before it becomes inactive. An abend is counted when both of the following conditions exist:

The exit routine does not provide recovery, or the exit routine does provide recovery but percolates the error.
The system allows a retry; that is, the recovery routine is entered with bit SDWACLUP off.

By default, the system will disable the exit routine after 3 consecutive abends.

Replacing the Exit Routine

For information about replacing a dynamic exit routine, see Replacing a Dynamic Exit Routine.

Exit Routine Environment

The exit routine receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0 and must return control in same state and key with no locks held.
In AMODE as defined by linkedit of exit routine module and RMODE=ABOVE.
In the HIS address space as H=P=S for any of the events, or in *MASTER* (ASID 1) with H=P=S for the "service has been disabled" call only.
With no locks held in TCB mode.

Exit Recovery

The exit routine should provide its own recovery. If the exit routine abnormally terminates, its recovery routine will get control.

If the exit routine abnormally terminates, and the exit routine does not provide its own recovery, or the error percolates beyond the exit's recovery routine, a system recovery routine will get control. If this occurs 3 consecutive times, the exit routine will be disabled.

Exit Routine Processing

The system invokes the HIS.SERVSTAT exit routine or routines, if they are registered to the dynamic exits facility, anytime the HISSERV service has enabled, started, stopped, or has disabled.

Using the Information in the Parameter List:The system passes the address of a list of parameters to the exit routine. The parameters contain the following information:

Version of this parameter area.
The function code, which indicates why the exit routine was called. For this exit, it would be that the status of the service has changed.
The reason code describing how the HISSERV service has changed.
- (1) - The service has been enabled.
- (2) - The service has been disabled.
- (3) - The service has started profiling the system.
- (4) - The service has stopped profiling the system.

See macro HISYEXIT in z/OS MVS Data Areas, Vol 2 for more details on the interface.

Programming Considerations

Observe the following conventions when coding the HIS.SERVSTAT Exit routine:

The exit routine is allowed to obtain and release any locks it desires in order to handle the exit, however performance degradation should be a concern.
Code the exit routine to be reentrant.
The exit is called whenever an event begins or ends. Therefore, when coding the exit routine, you should be aware that an increased path length will increase processor utilization and may degrade performance.
Make sure that the exit routine does not get affected when new function code support is added.

Macro Instructions and Restrictions: The exit is not allowed to issue a HISSERV REQUEST=PROFILE request, or wait on a resource held by another work unit which might issue a HISSERV REQUEST=PROFILE request.

Be aware that the exit can create performance degradation. Do not perform unnecessary tasks.

Do not code the exit routine to invoke dynamic allocation.

Entry Specifications

The system passes the address of the exit parameter list to the exit routine.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of the exit parameter list
2-12: Not applicable
13: Address to a 216 byte save area
14: Return address
15: Entry point address of the exit routine

Parameter Descriptions: Register 1 contains the address of the exit parameter list, which is mapped by macro HISYEXIT in z/OS MVS Data Areas, Vol 2.

Return Specifications

The interface does not provide any field for a response; the exit does not need to return a valid value.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register: Contents
0-1: Does not need to be preserved
2-13: Restored to contents at entry
14-15: Does not need to be preserved

Coded Example of the Exit Routine

There is no coded example of this exit routine in SYS1.SAMPLIB.