EPICURE Design Note 25.4<P> <b> EPICURE VMS System Services</b>

EPICURE Design Note 25.4

EPICURE VMS System Services

David M. Kline

A set of user-written system services are provided for the use of EPICURE facilities. The facility name for the EPICURE System Services is ESS so that individual routine names are of the form ESS_name. EPICURE System Services can be called from any VAX language as these services use the same standard VAX procedure calling sequence as the normal VMS system services.

The EPICURE System Services were developed as extensions to the standard VMS system services during the development of EPICURE subsystems which make use of a detached process to coordinate the activities of several EPICURE user application processes. The user interface in these EPICURE subsystems is a set of routines (often referred to as User Task Interface or UTI routines) which provide services by interacting with the detached process; this interface is hidden from the user by the UTI routines. The interfaces between UTI routines and their associated detached process make use of existing standard VMS techniques, such as mailboxes and global sections. The EPICURE System Services evolved as VMS extensions to provide performance or to assure activation of resource recovery routines in event of the failure of a user process.

Additional extensions are provided by the EPICURE System Services to maintain an Image-Rundown-Handler (IRH). An IRH is incorporated into the image rundown procedures and is executed regardless of how the process is terminated. Thus resources acquired by the process during its execution can be released. The IRH services provide the mechanisms which declare and remove an IRH from a process. Consult the section ``Declaring an Image Rundown Handler'' for additional information pertaining to Image-Rundown-Handlers.

Linking with ESSSHR

The EPICURE user-written system services are implemented in the ESSSHR.EXE shareable image and can be found in the directory. Normally, this image is installed as a protected shareable image at system startup. To use any of these services, your program must link to this shared image with an explicit Linker command as shown:

$ link  myprogram,...,sys$input:/options...
sys$share:essshr/shareable
to link myprogram and other object modules with the ESSSHR image.

Trigger an AST in Another Process

The ESS_DXPAST service is an extended form of the SYS$DCLAST system service which declares ( triggers) an AST in the process which calls the system service. ESS_DXPAST permits a suitably privileged process to declare an AST in a separate process. The target process must make the virtual address of the AST routine known to the source process (the process which calls the ESS_DXPAST service) prior to the call to ESS_DXPAST by some other communication path.

No special privileges are needed to use ESS_DXPAST if the source and target processes have the same owner UIC or are in the same job tree. Just like the other VMS system services which involve actions on other processes (such as SYS$WAKE, for example), either GROUP or WORLD privilege is needed to use ESS_DXPAST when the source and target processes are owned by different UIC's. The ESS_DXPAST routine is particularly useful for communicating from an EPICURE detached process (which has the necessary privileges) to the associated UTI routines in a nonprivileged user process.

Image Rundown ASTs

The Image Rundown AST ( IRA) services provide the means for EPICURE detached processes to be notified when a user program exits. This is done by tapping into the VMS image rundown service; unlike exit handlers which can be bypassed and which are not invoked if a process is deleted, the image rundown service is always executed when a program exits. This happens whether the program exits normally or abnormally, with or without the Debugger, in a single-image detached process or under DCL or if the process is deleted with the SYS$DELPRC system service. In this way, the Image Rundown AST services provide the means for detached processes to be notified to recover resources (such as memory in a global section) allocated by a terminated user program.

Declaring an Image Rundown AST

The ESS_DCLIRA service is used by a process to declare its intention to receive Image Rundown ASTs. The process provides the address of such an AST routine for use in validating requests to setup the triggering of an Image Rundown AST by client processes. A process can declare up to 4 separate AST routines as IRA entry points. The validation information, consisting of the process identification and the AST address, are stored in a global section mapped and accessed in kernel mode (thus protected from modification by user code). Since only a single page is mapped, there is a limit of 63 IRAs for the entire system. Neither of these limits (4 IRAs per process and 63 total per system) are thought to be restrictive.

The ESS_DCLIRA service automatically maps (or creates) the global section when needed (as does the ESS_SETIRA service). This global section is setup as a system global page file section (backing store is the paging file). The global section is not defined as a permanent global section; when no processes are using the IRA services, no such global section is in existence.

The ESS_DELIRA service permits a previously declared IRA to be withdrawn; no new attempts to set this IRA will succeed and the IRA will not be triggered by any sets existing in client processes. A similar action is taken if the process (which did the ESS_DCLIRA) terminates. When the process has no IRAs declared and no Image Rundown Handlers set, the validation information global section is automatically unmapped.

Setting an Image Rundown AST

The ESS_DCLIRA service permits IRA receiver processes to declare their intent to receive Image Rundown ASTs. This permits the requests of nonprivileged client processes to setup an IRA trigger to be validated. Client processes setup an Image Rundown Handler to trigger the Image Rundown AST by calling the ESS_SETIRA service. The caller must provide the address of a Rundown Handler Block (analogous to the exit handler block used with the SYS$DCLEXH service of VMS). A process can not setup an Image Rundown Handler for an Image Rundown AST declared by the process itself.

The Rundown Handler Block contains 5 longwords, the first two longwords are set by the IRA services themselves:

Before calling the ESS_SETIRA service, the caller places the process identification ( pid) and the address of the AST routine in the Rundown Handler Block. This information is validated against that provided by the target process in the ESS_DCLIRA call; if the target process has not declared an Image Rundown AST with the matching virtual address, an error status will be returned and the Rundown Handler Block will not be linked into the list of active Rundown Handler Blocks.

The Rundown Handler Block is added onto the head of a linked list of Rundown Handler Blocks to be processed at image rundown by the Image Rundown Handler in FILO (First In Last Out) order. Since the Rundown Handler Block is remembered after the call to ESS_SETIRA, it must be stored in static storage and not on the stack. If stored in dynamic memory, the block cannot be released until after ESS_CLRIRA has been called.

The AST parameter may be modified at any time (filled in before the call to ESS_SETIRA or changed afterwards); it only has meaning at the time the Image Rundown AST is triggered in the target process. Frequently, the ESS_SETIRA routine will be called inside a UTI routine and the AST parameter will be used to identify the client process so the detached process can recover any resources allocated to the (now terminated) client program.

The ESS_CLRIRA service provides a means for the client process to retract the Image Rundown AST previously setup. This might be done when the client process exits normally and restores all its allocated resources successfully. In such a case, the Image Rundown AST might be unnecessary and so ESS_CLRIRA is called to eliminate the system overhead in triggering the unnecessary Image Rundown AST.

Declaring an Image Rundown Handler

As part of process termination, the VMS operating system queues a KERNEL mode AST to perform a series a steps that removes resources a process acquired during its existence. The DELETE AST searches for per-process or system-wide executive mode rundown routines to perform image-specific cleanup. If they exist, the DELETE AST queues an executive mode AST to the process and exits, thus allowing it to be delivered. The EXEC_RUNDOWN_AST invokes the per-process and system-wide executive mode rundown routines. In particular, the AST executes the routine specified at CTL$GL_USRUNDWN_EXEC located in process P1 space. Currently, the image-rundown-handler (IRH) routine specified at that location executes an RSB instruction. The ESS_DCLIRH system service replaces the system-declared IRH with a user-declared IRH and allows one parameter to be passed. The EPICURE System Services support one IRH; however, chaining multiple IRHs can be supported in future releases. The user-declared IRH is limited to the system services which it can call. Since the IRH is executing as an executive mode AST, system services which use ASTs to signal completion can not be called. However, a useful feature of IRHs is that they are guaranteed to execute regardless of how the process terminates. Therefore, file buffers can be flushed and other resources can be relinquished. In addition, the user-declared IRH can return a status that is written to the accounting log file. After the user-declared IRH executes, ESSSHR executes the system-declared IRH and places its address back into CTL$GL_USRUNDWN_EXEC. EXEC_RUNDOWN_AST then gains control and requests a Change to Kernel Mode ($CMKRNL) system service. Execution resumes in the DELETE AST and completes process termination. The ESS_CLRIRH system service disables execution of the user-declared IRH and can be called from a user declared exit handler. Furthermore, the caller must have the CMEXEC (change to executive mode) privilege to invoke the ESS_DCLIRH and ESS_CLRIRH system services. Consult the section ``ESS Descriptions and Calling Sequences'' for specific information related to the IRH services.

ESS Definitions Header File

There is a header file for the EPICURE System Services stored in the EPICURE_SYS_INC: area. The file can be included in your C program with the statement:

#include  "epicure_sys_inc:ess$routines.h"
The ess$routines.h file defines the calling sequences of the ESS routines as function prototypes. It also defines a structure named RHBlk for the Rundown Handler Block for use with the ess_setira and ess_clrira services. The RHBlk definition from ess$routines is:
struct RHBlk {
    struct RHBlk *link;
    unsigned long rhast_descr;
    unsigned long tgt_pid;
    void (*tgt_ast)();
    unsigned long tgt_param;
    };

ESS Descriptions and Calling Sequences

This section provides detailed descriptions of the individual EPICURE System Services and their calling sequences.

ESS_CLRIRA status = ESS_CLRIRA( rhbadr ) A previous declared rundown handler AST (see ESS_SETIRA) is to be removed from the list of rundown handler ASTs. rhbadr address of Rundown Handler Block (described above). Passed by reference. status returns a VMS condition code: SS$_WASSET success, block was removed from list SS$_WASCLR success, block was not found on list

ESS_DCLIRA status = ESS_DCLIRA( iraadr ) Declare an Image Rundown AST to be handled by the current process upon image exit in client processes. iraadr address of Image Rundown AST triggerable by client processes. Passed by reference. status returns a VMS condition code: SS$_WASCLR success, AST was not declared as IRA SS$_WASSET success, AST is already declared as IRA SS$_ACCVIO access violation (cannot access the AST routine) SS$_EXGBLPAGFIL exceeded system-wide limit on global page-file pages SS$_EXQUOTA exceeded paging file quota SS$_GPTFULL no more room in system global page table SS$_GSDFULL no more room in system space allocated to maintain information for global sections SS$_INSFWSL process's working set limit is not large enough to accommodate increase in the address space SS$_LCKPAGFUL system-defined maximum limit on the number of pages that can be locked in memory has been reached SS$_NOHANDLER no AST address provided SS$_SECTBLFUL no entries are available in the system global section table SS$_VASFULL process's virtual address space is full; no space is available in the page tables for the pages created to contain the mapped global section ESS__IRALSTFUL image rundown AST list for process is full ESS__RADSECFUL rundown AST descriptor list for system is full

ESS_DELIRA status = ESS_DELIRA( iraadr ) A previously declared Image Rundown AST (see ESS_DCLIRA) is to be removed from the set of Image Rundown ASTs provided by this process. iraadr address of Image Rundown AST to be discontinued. Passed by reference. status returns a VMS condition code: SS$_WASSET success, AST was removed from set SS$_WASCLR success, AST was already removed others from internal problems in call to $DELTVA

ESS_DXPAST status = ESS_DXPAST( pidadr, [obsolete], astadr, [astprm], [acmode] ) This service is an extension of the SYS$DCLAST() system service which permits a process to declare an AST. DXPAST extends this capability to permit a suitably privileged process to trigger an AST routine in another process. Prior communication from the AST destination process is needed to pass the AST address to the process which is calling ESS_DXPAST. No privilege is required to use ESS_DXPAST if the target and source processes have the same owner; either GROUP or WORLD privileges are required to use DXPAST when the target and source processes are owned by different UIC's (just like any VMS system service which controls or accesses other processes). pidadr longword with process identification of the destination process. Passed by reference. obsolete this argument is ignored. astadr virtual address of the AST routine in the destination process' address space. The address is passed by value. Note that prior communication between the current and destination processes is required to make the AST virtual address available to the current process. astprm parameter for the AST routine. Passed by value. Remember that virtual addresses used as the AST parameter will refer to virtual addresses in the context of the destination process. acmode access mode at which the AST is to be run. Passed by value. Maximized with respect to the caller's access mode. status returns as VMS condition code: SS$_NORMAL success SS$_ACCVIO access violation SS$_EXASTLM AST quota limit of destination process exceeded (if either source or target process has EXQUOTA privilege, then the AST quota limit of the destination process is bypassed) SS$_INSFMEM insufficient dynamic memory SS$_NONEXPR target process does not exist SS$_NOPRIV insufficient privilege (GROUP/WORLD) for requested operation

ESS_SETIRA status = ESS_SETIRA( rhbadr ) Setup an image rundown handler to send an AST to a target process (see ESS_DXPAST). In analogy with the $DCLEXH system service, the caller provides the address of a Rundown Handler Block with the following structure (the caller fills in the target process identification, AST address and AST parameter). This block must be writable: +--------------------------------------------------+ | Link to next Rundown Handler Block | +--------------------------------------------------+ | Pointer to Rundown AST Descriptor | +--------------------------------------------------+ | Process identification of target process | +--------------------------------------------------+ | Address of AST in the target process | +--------------------------------------------------+ | AST parameter | +--------------------------------------------------+ verbatim The target process must exist at the time the ESS_SETIRA service is called and the AST address must be non-zero. The AST address must match with the address of an Image Rundown AST declared by the target process using the ESS_DCLIRA service. When the current image exits (or the current process is deleted), a user mode AST will be triggered in the target process in a manner similar to the ESS_DXPAST service. Unlike exit handlers, the image rundown handler cannot be bypassed in any way (including using $DELPRC to delete the process). The ESS_CLRIRA service will undo the actions of the ESS_SETIRA service. rhbadr address of Rundown Handler Block (described above). Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_ACCVIO access violation (possibly the Rundown Handler Block is not writable) SS$_EXGBLPAGFIL exceeded system-wide limit on global page-file pages SS$_EXQUOTA exceeded paging file quota SS$_GPTFULL no more room in system global page table SS$_GSDFULL no more room in system space allocated to maintain information for global sections SS$_INSFWSL process' working set limit is not large enough to accommodate increase in the address space SS$_LCKPAGFUL system-defined maximum limit on the number of pages that can be locked in memory has been reached SS$_NOHANDLER no AST address in Rundown Handler Block SS$_NONEXPR target process does not exist SS$_SECTBLFUL no entries are available in the system global section table SS$_VASFULL process' virtual address space is full; no space is available in the page tables for the pages created to contain the mapped global section ESS__NOSELFIRA image rundown AST target process cannot be current process ESS__NOSUCHIRA no matching AST declared by the target process

ESS_CLRIRH status = ESS_CLRIRH( irhadr ) The image rundown handler declared (see ESS_DCLIRH) is removed. The CMEXEC privilege is required to execute this routine. irhadr address of Image Rundown Handler (IRH). Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad parameter value SS$_NOPRIV fatal, no privilege for attempted operation ESS__NOSUCHIRH fatal, no such image rundown handler declared

ESS_DCLIRH status = ESS_DCLIRH( irhadr, [irhprm] ) Declares an image rundown handler for a process. The CMEXEC privilege is required to execute this routine. irhadr address of Image Rundown Handler (IRH). Passed by reference. irhprm optional integer parameter to be passed to the Image Rundown Handler (IRH). Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for attempted operation SS$_BADPARAM fatal, bad parameter value ESS__DCLIRH fatal, process's IRH already declared

Keywords: VMS, system, services

Distribution: normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov