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 Digital UNIX and Solaris,
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 acme.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):
acme.com $[LOOKUP_IMAGE,LOOKUP,$U]$FA forward pointing address jdoe@acme.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%acmevax.acme.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@acmevax.acme.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.
Note:
This facility is not designed for use by casual users; it is intended to be used to extend PMDF's capabilities system-wide.