Writing an execlet or how a simple question
can lead to some serious system programming.

Note that the PIO$GT_DDSTRING denotes a counted string, so the first byte contains the length.

This approach seemed satisfactory, but implied that the user needed the CMKRNL privilege, or that the shareable image was installed with the CMKRNL privilege.

I wasn’t going to bother with this, since I had to figure out how to find the equivalence name of the logical name "SYS$DISK" for another process. This logical name is defined in the process private logical name table LNM$PROCESS_TABLE.

I decided to have a look at how the command CLUE PROCESS/LOGICAL within ANALYZE/SYSTEM works. Unfortunately, the method used by ANALYZE/SYSTEM to display the logical names for a process, couldn’t readily be used in QDDDS. So, I had to think of something else.

But, first things first, I had to get rid of the SYS$CMKRNL call in the shareable image. This proved to be easy by creating a privileged shareable image, containing so-called user-written system services.

System services

Since I already had some experience in writing system services for OpenVMS VAX, it seemed not that difficult to do the same for OpenVMS Alpha or OpenVMS I64.

I started with the privileged library vector block. The definition on OpenVMS Alpha was quite different from what it was on OpenVMS VAX.

struct _plv {
   unsigned int plv$l_type;
   unsigned int plv$l_version;
   unsigned int plv$l_kernel_routine_count;
   unsigned int plv$l_exec_routine_count;
   void *plv$ps_kernel_routine_list;
   void *plv$ps_exec_routine_list;
   int (*plv$ps_kernel_rundown_handler)();
   int (*plv$ps_exec_rundown_handler)();
   int (*plv$ps_rms_dispatcher)();
   int *plv$ps_kernel_routine_flags;
   int *plv$ps_exec_routine_flags;
};

Fortunately, the necessity of having specific dispatcher code completely disappeared.

In order to be somewhat flexible, I decided to have eight kernel mode services, and eight executive mode services. And, since I started from existing OpenVMS VAX code, the definition of the privileged library vector is the only thing written in Macro.

The first system service (_qext_getddir) didn’t require much effort. A simple revamping of the routine of the same name I already mentioned above, sufficed.

The second one (_qext_trnlnm) proved to be quite a different cup of tea. My investigation into ANALYZE/SYSTEM was unsuccessful; as was my initial search on the web.

The idea of searching for the data structures defining the LNM$PROCESS_TABLE of the target process, and then finding the equivalence name for SYS$DISK, I discarded.

The only solution seemed to force the target process to translate SYS$DISK and to make that translation somehow available to the process executing the QDDDS utility.

In the good old days of the VAX, when I took the course VAX/VMS System Programming, we wrote code that was meant to execute in the context of another process. During my professional life as a system manager, I hadn’t had the need of writing such code on OpenVMS VAX, let alone on OpenVMS Alpha or OpenVMS I64. But could it be done?

The information I found in the OpenVMS Programming Concepts Manual was not very promising:

• "On OpenVMS VAX systems, a system programmer must sometimes develop code that performs various actions (such as performance monitoring) on behalf of a given process, executing in that process's context. To do so, a programmer typically creates a routine consisting of position-independent code and data, allocates sufficient space in nonpaged pool, and copies the routine to it. On OpenVMS VAX systems, such a routine can execute correctly no matter where it is loaded into memory.
• On OpenVMS Alpha systems, the practice of moving code in memory is more difficult and complex. It is not enough to simply copy code from one memory location to another. On OpenVMS Alpha systems, you must relocate both the routine and its linkage section, being careful to maintain the relative distance between them, and then apply all appropriate fixups to the linkage section.

The OpenVMS Alpha system provides two mechanisms to enable one process to access the context of another:

• Code that must read from or write to another process's registers or address space can use the EXE$READ_PROCESS and EXE$WRITE_PROCESS system routines, as described in Section 4.7.1.
• Code that must perform other operations in another process's context (for instance, to execute a system service to raise a target process's quotas) can be written as an OpenVMS Alpha executive image, as described in Section 4.7.2."
• Mechanism 1 (the EXE$READ_PROCESS path) I already used for the default directory specification, but I could not use that for the translation of SYS$DISK. So, the only way to go was to develop an executive image, aka an execlet.

The execlet

I must admit that reading through the section 4.7.2 of the OpenVMS Programming Concepts Manual did not help me much. I needed an example.

In search of examples

Google is your friend, as was AltaVista in the second half of the 1990s.

Searching for "execlet", I found a .PDF-file ("portable document format", not "product description file") containing what seemed to be a presentation by John R. Covert, he had given at an "IT Symposium" probably organised by Decus Germany. It contained some snippets of code related to "Execlets in C geschrieben".

Searching for "vms execlet", I found on the old stale "HP OpenVMS Ask the Wizard" site, an interesting answer to the exact same question I had: "How can I force another process to execute a particular routine?" (http://h71000.www7.hp.com/wizard/swdev/execlet.html), probably written by Stephen Hoffman ("Hoff"). So, it seemed that the SCH$QAST routine was not made obsolete on OpenVMS Alpha after all.

In the group comp.os.vms, I found a thread started by Brian Schenkenberger ("am I the only one hacking VMS on Itanium?"), where in the answer of Ian Miller, I found a link to Ian’s "MBMON" package.

Studying Ian’s code, I felt compelled to taking his approach:

• Writing a control program to load or unload the execlet (instead of using SYSMAN);
• Using the mandatory initialization routine to set up and initialize a data structure;
• Using the (undocumented) routine LDR$REF_INFO to obtain the necessary code entry points (through the previously initialized data structure);
• And finally, writing a routine that forced the target process to translate a logical name and send the result back.

Control program

After reading up on executive loadable images in the comments of the examples I already downloaded from the net, I realised I definitely needed a program to load and unload the execlet, thus avoiding the use of SYSMAN, and many reboots of my AlphaStation.

Starting with the source code of the loader program Ian had provided with his "MBMON" package, I soon realised I had to devise the control program from scratch. I decided to write a command line utility akin to SYSMAN, that recognized and processed the commands LOAD and UNLOAD.

I incorporated (a modified version of) the command line parsing code from QDDDS into this control program that I named QEXTCP. In contrast with QDDDS, the QEXTCP program should also support being invoked by the RUN command. Furthermore, it should prompt the user should no command be given directly. Therefore, if no command is given, the QEXTCP utility forces itself into a loop around calls to CLI$DCL_PARSE and CLI$DISPATCH. The latter routine will transfer control to the appropriate subroutine within QEXTCP if a command is recognized.

while ( vl_sts != RMS$_EOF )
{
    vl_sts = cli$dcl_parse (
      &vl_cmd_d, &QEXTCP_CLD
      , lib$get_input, lib$get_input
      , &vl_prmt_d
    );
   if ( vl_sts & 1 )
   {
       vl_sts = cli$dispatch ();
   }
}

Note that (the address of) LIB$GET_INPUT is specified for both the "parameter" routine and the "prompt" routine.

Loading the execlet

According to the OpenVMS Programming Concepts Manual (dated June 2002),

• "An executive image can contain one or more initialization procedures that are executed when the image is loaded."

and

• "Because an initialization routine is executed when the executive image is loaded, it serves as an ideal mechanism for locating the callable routines of an executive image in memory."

Then some guidelines are given on how this can be achieved.

This information has been omitted from the HP OpenVMS Programming Concepts Manual (dated January 2005).

So, the execlet needed an initialization routine.

Based on Ian’s code, I wrote a simple function (__qext_init) that initialized a data block, and returned through its arguments the necessary data to its caller.

I also wrote a third system service that I used to invoke the LDR$LOAD_IMAGE routine. By doing so, I could not only make sure that the execlet was loaded, but also obtain the necessary information about it.

The LDR$LOAD_IMAGE routine expects three or four arguments, depending on the value of its second argument. The first argument is the name of the executive image for which I specified a logical name, thus avoiding the need of putting the file in SYS$LOADABLE_IMAGES. The second argument is a bit vector. I made sure that LDR$V_UNL and LDR$V_USER_BUF were set, indicating that the image may be removed from memory, and that (the address of) the user buffer (the fourth argument) should be passed to the executive image's initialization routine.

The third argument to LDR$LOAD_IMAGE is the address of a reference handle, a three-longword buffer that, upon successful completion of the routine, contains the address of the loaded image in the first longword, the address of a loaded image data block (LDRIMG) in the second longword, and a sequence number in the third longword.

struct _qx_vec {
   unsigned int qv_vrsn_min;
   unsigned int qv_vrsn_maj;
   unsigned int qv_cnt;
   unsigned int qv_filler_0;
   unsigned int (*qv_rtn_00) ( void * );
};
typedef struct _qx_vec t_qx_vec;

unsigned int vl_refhdl[3];
LDRIMG vl_ldrimg_r;
t_qx_vec vl_usrbuf;
unsigned int vl_flags = LDR$M_UNL | LDR$M_USER_BUF;

/*...*/

vl_sts = ldr$load_image (
      &vl_fn_d, vl_flags, &vl_refhdl[0], &vl_usrbuf    );
if ( vl_sts & 1 )
{
/*...*/
}

The call to LDR$LOAD_IMAGE triggers the initialization routine of the execlet, and there the necessary initialization is done to tell where the callable routines are located.

t_qx_vec *vl_vec_p;

vl_vec_p = &v_QX_Vec;
vl_vec_p->qv_vrsn_min = QXLT_MINOR_ID;
vl_vec_p->qv_vrsn_maj = QXLT_MAJOR_ID;
vl_vec_p->qv_cnt = 1;
vl_vec_p->qv_filler_0 = 0;
vl_vec_p->qv_rtn_00 = __qext_dispatcher;


*a_vp = vl_vec_p;

To complete the first version of the control program, I had to code the unload functionality. The information about the LDR-routines in the HP OPENVMS PROGRAMMING CONCEPTS MANUAL, specifically about LDR$UNLOAD_IMAGE, left me puzzled.

On the one hand, the LDR$LOAD_IMAGE returns through its argument "ref_handle" the necessary info about the execlet. On the other hand the LDR$UNLOAD_IMAGE expects this information to perform the unload operation. So, in between calling the routines, I had to keep the information stored in the "ref_handle" safe.

Fortunately, Ian’s code showed that there was no need for safekeeping that information. It could be obtained through an undocumented LDR-routine namely LDR$REF_INFO. That routine was documented in the article I found on the "HP OpenVMS Ask the Wizard" site.

vl_sts = ldr$ref_info ( &vl_fn_d, &vl_refhdl[0] );
if ( vl_sts & 1 )
{
   );vl_sts = ldr$unload_image ( &vl_fn_d, &vl_refhdl[0] );
}

This hurdle taken, up to the next.

Invocation

Now that I was able to load and unload the execlet, I could concentrate on writing code that actually called routines hidden in the execlet.

Inside the routine calling LDR$LOAD_IMAGE, I had all information I wanted since (the initialization code of) the execlet passed the address of the "dispatch"-routine through the "user buffer" argument. How to obtain that same information, once the execlet well and truly loaded?

I still had some uncharted territory to explore, and from one of the slides of John’s presentation I learned that the "ref_handle" argument could be interpreted as much more than a three-longword buffer.

The "ref_handle" is also returned by LDR$REF_INFO, so I started investigating.

According to the OpenVMS Programming Concepts Manual, the second longword of the "ref_handle" argument to LDR$LOAD_IMAGE is

• "Address of loaded image data block (LDRIMG). See the $LDRIMGDEF macro definition in SYS$LIBRARY:LIB.MLB and VMS FOR ALPHA PLATFORMS INTERNALS AND DATA STRUCTURES for a description of the LDRIMG structure."

After extracting the module LDRIMGDEF from SYS$LIBRARY:SYS$LIB_C.TLB, and studying both the "struct _ldrimg" and Ian’s code in MBMON, I noticed that via the item "ldrimg$l_nonpag_w_base" the exact same data structure, that the initialization routine passed to the loader code, could be found.

Once that figured out, it wasn’t difficult to write some code that sort of mapped (references to) the execlet.

struct _ldr_refhdl {
   void *lr_addr;
   LDRIMG *lr_lid;
   long lr_seqnum;
};
typedef struct _ldr_refhdl t_ldr_refhdl;

t_qx_vec *vl_vec_p;
t_ldr_refhdl vl_rh;

vl_sts = ldr$ref_info ( &vl_fn_d, &vl_rh );
if ( vl_sts & 1 )
{
   vl_vec_p = (t_qx_vec *) vl_rh.lr_lid->ldrimg$l_nonpag_w_base;

   /*...*/
}