PMDF System Manager's Guide

A substitution of the form $[image,routine,argument] is handled specially. The image,routine,argument part is used to find and call a customer-supplied routine. At run-time on OpenVMS, PMDF uses LIB$FIND_IMAGE_SYMBOL to dynamically load and link to the routine routine from the shareable image image; at run-time on UNIX, PMDF uses dlopen and dlsym to dynamically load and call the routine routine from the shared library image. The routine routine is then called as a function with the following argument list:
status = routine (argument, arglength, result, reslength) argument and result are 252 byte long character string buffers. On OpenVMS argument and result are passed by descriptor (a class S descriptor is used to insure maximum compatibility); on UNIX and Windows, argument and result are passed as a pointer to a character string, (e.g., in C, as char*). arglength and reslength are signed, long integers passed by reference. On input, argument contains the argument string from the rewrite rule template, and arglength the length of that string. On return, the resultant string should be placed in result and its length in reslength. This resultant string will then replace the "$[image,routine,argument]" in the rewrite rule template. The routine routine should return 0 if the rewrite rule should fail and -1 if the rewrite rule should succeed.

This mechanism allows PMDF's rewriting process to be extended in all sorts of complex ways. For example, a call to some type of name service could be performed and the result used to alter the address in some fashion. For instance, directory service lookups for forward pointing addresses (e.g., To: addresses) to the host example.com might be performed as follows with the following rewrite rule (the $F, described in Section 2.2.6.12 causes this rule to only be used for forward pointing addresses):

example.com $F$[LOOKUP_IMAGE,LOOKUP,$U]

A forward pointing address jdoe@example.com will, when it matches this rewrite rule, cause LOOKUP_IMAGE (which is a shareable image on OpenVMS and a shared library on UNIX) to be loaded into memory, and then cause the routine LOOKUP called with "jdoe" as the argument parameter. The routine LOOKUP might then return a different address, say, John.Doe%vax.example.com in the result parameter and the value -1 to indicate that the rewrite rule succeeded. The percent sign in the result string causes, as descibed in Section 2.2.5.2 the rewriting process to start over again using John.Doe@vax.example.com as the address to be rewritten.
On OpenVMS systems, since LIB$FIND_IMAGE_SYMBOL is used to dynamically load the site-supplied image image, then image must be a logical name pointing to the actual shareable image. Moreover, as this mechanism will be invoked by PMDF in a variety of contexts, the logical must be an executive mode logical, any logicals it references must also be executive mode logicals, and the image itself must be world readable and installed as a known image.

On UNIX systems, the site-supplied shared library image image should be world readable.