HP OpenVMS Systems

One use of a user-supplied executive image is for one process to force another process to execute a particular piece of code.The sample provided here will do just that.

In this example, a process registers itself by running an image which executes the user-supplied executive image's routine set_value.Since the registration involves modifying a datum in the user-supplied executive image (which can only be done from kernel mode), this call goes through a user-written system service which will run the user-supplied executive image's routine in kernel mode.

Any process can find the internal PID of the process that is currently registered by running the get_value routine in the user-supplied executive image.This involves reading a datum in the user-supplied executive image, which can be done from any mode.Consequently the use of a user-written system service is not required to perform this operation.

The final piece of functionality offered by the user-supplied executive image is to cause the registered process to execute the print_it function.This involves calling the internal routine SCH$QAST which requires execution from an elevated mode.

Here is the code for the user-supplied executive image:
» MY_EXECLET.MAR
Here is the code for the User-Written System Service:
»  MY_UWSS.MAR
Here is the code for the executable test harness:
» CALL_MY_EXECLET.C
Here are the commands to build and install the pieces:
»  BUILD_IT.COM

Assuming that is done, here is a stylized log of a session using these routines.

Process A Process B
---------------------------------------------------------------------------
$ MCR call_my_execlet s |
|$ MCR call_my_execlet g
|value is 10034
|$ MCR call_my_execlet p
|%SYSTEM-F-NOPRIV, insufficient privilege or object protection violation
|$ SET PROCESS/PRIVILEGES=CMKRNL
|$ MCR call_my_execlet p
Process with PID 00000134 |
Executing routine PRINT_IT with a PD of 817B22F0|
First instruction is at 84B76130|

Other useful information: As provided, this user-supplied executive image is loaded as boot time via SYSMAN.It could also be loaded on a running system with the ability to be unloaded and reloaded (the reload feature is not available if loaded at boot time).

If this were done, users of the user-supplied executive image should also make references to the image so that the unload code would not unload the user-supplied executive image while it is in use by another image.Information on calling these undocumented routines is provided later in this FAQ.

The routines to load and unload a user-supplied executive image, LDR$LOAD_IMAGE and LDR$UNLOAD_IMAGE, are documented in the OpenVMS Programming Concepts Manual. Following is a description of routines which retrieve information about user-supplied executive images and which make and remove references to them.

More information on user-supplied executive images may be found in the OpenVMS Programming Concepts Manual in the section titled "Accessing Another Process's Context."

As a final note, it may be useful for a user-supplied executive image to know its name.The initialization routine receives the address of the loaded image data block (defined by ldrimgdef.sdl) as the first parameter.This structure contains the name of the user-supplied executive image.

LDR$REF_INFO
 ;+
 ; Functional Description:
 ;
 ; This routine is called to return reference information for an unloadable
 ; exec image. The image must be fully loaded with a valid loaded
 ; image block.
 ;
 ; Environment:
 ;
 ; mode - kernel, ipl-0
 ;
 ; Input Parameters:
 ;
 ; - reference information handle (see SYS$MAKE_REF or
 ; SYS$REMOVE_REF)
 ; - filename descriptor
 ;
 ; Output Parameters:
 ;
 ; R0 - 1, if valid, unloadable exec image and reference
 ;information duly filled in.
 ; R0 - LBC otherwise.
 ;-

SYS$MAKE_REF
 ;+
 ;
 ; This system service grants access toan unloadable exec image.
 ; Unloadable exec images may choose to adopt the system loader's
 ; mechanism for tracking references.
 ; An application must call $make_ref for each access of the exec
 ; image. If the exec image is marked 'unload-pending', access is
 ; denied (by returning error status in R0).
 ; Each $make_ref must be followed by $remove_ref to avoid nasty
 ; consequences.
 ;
 ; Inputs:
 ;
 ; 4(AP) = Address of reference information handle.
 ;
 ; The reference information handle has three longwords.
 ; It has the following format.
 ;
 ; +-------------------------------------------+
 ; | base address of image |
 ; +-------------------------------------------+
 ; | address of loaded image block |
 ; +-------------------------------------------+
 ; | sequence number |
 ; +-------------------------------------------+
 ;
 ; The reference information handle is filled by ldr$load_image.
 ; Alternatively, the contents may be obtained by calling
 ; ldr$ref_info
 ;
 ; Output:
 ;
 ; R0 = ss$_normal or
 ;loader$_unl_pen or
 ;loader$_not_unl
 ;
 ; Side Effects:
 ;
 ; If the exec image is not marked for unload, the reference count
 ; is incremented.
 ;-

SYS$REMOVE_REF
 ;+
 ;
 ; This system service marks the end of reference for an unloadable exec image.
 ; Unloadable exec images may choose to adopt the system loader's
 ; mechanism for tracking references by using sys$make_ref and sys$remove_ref
 ; before and after each access.
 ; Each $make_ref must be followed by $remove_ref to avoid nasty
 ; consequences
 ; It is the responsibility of the application to ensure that all accesses
 ; are preceded and succeeded by $make_ref and $remove_ref respectively.
 ;
 ;
 ; Inputs:
 ;
 ; 4(AP) = Address of reference information handle.
 ;
 ; The reference information handle has three longwords.
 ; It has the following format.
 ;
 ; +-------------------------------------------+
 ; | base address of image |
 ; +-------------------------------------------+
 ; | address of loaded image block |
 ; +-------------------------------------------+
 ; | sequence number |
 ; +-------------------------------------------+
 ;
 ; The reference information handle is filled by ldr$load_image.
 ; Alternatively, the contents may be obtained by calling
 ; ldr$ref_info
 ;
 ; Output:
 ;
 ; R0 = ss$_normal or
 ; ss$_badparam, ss$_accvio, loader$_badrefcnt
 ;
 ; Side Effects:
 ;
 ; If the exec image is not marked for unload, the reference count is
 ; decremented.If the image is marked for unload and this reference has
 ; caused the reference count to go down from 1 to 0, this process traverses
 ; system space for a while.
 ;-