This package illustrates how to implement privileged shareable images, with
user-written system services in C and other high-level languages.  

Any user-written system service that executes in a privileged mode requires a
change mode dispatcher.  While there is such a program in
sys$examples:ussdisp.mar, it is a template.  I basically got tired of
re-editing it over and over again for each privileged shareable image, so I 
created a macro library containing everything in the example dispatcher.  Thus
with a few macro calls, you can build everything necessary for privileged
shareable images.  Additionally, the generic dispatcher will permit the actual
routines to be in different modules.  This means that the kernel mode routines
don't have to be in macro, but can be in any high-level language that supports
the calling standard.

Look at the comments in the individual modules for more details.

Files in this package:


dispatcher.txt				this file
dispatch_readme.txt			readme file
dispmacs.mar				dispatcher macros
sample_dispatcher.h			sample dispatcher header file
sample_dispatcher.mar			sample dispatcher source file
sample_dispatcher_build.com		build procedure
sample_dispatcher_test.c		test program to call services
sample_dispatcher_test.com		run the test program
sample_dispatcher_test.lnk		link file for test program
sample_dispatcher_test.opt		options file for test program
sample_priv_c_services.c		privileged system services in c (pssic)
sample_priv_c_services.h		header file for pssic
sample_priv_share.lnk			link file for pssic
sample_priv_share.opt			options file for pssic
sample_unpriv_c_services.c		user mode system services in c (umssic)
sample_unpriv_c_services.h		header file for umssic
sample_unpriv_share.lnk			link file for umssic
sample_unpriv_share.opt			options file for umssic
sample_user_mode_vector.mar		transfer vector for umssic


The build and run procedures assume all the files in the package are in the
same directory.  It doesn't matter what directory you use.  Both procedures
will take the directory in which the command procedure resides and define the
logical names based on that.

Simply enter the commands:

         $ @disk:[dir]sample_dispatcher_build
         $ @disk:[dir]sample_dispatcher_test

where disk and dir represent the actual disk and directory.  Or you can just
set default to that, of course, and use a bare "@".  Submit is always an
option, too.


WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!

As always when dealing with privileged code executing in kernel mode, it is
possible to crash the entire system.  This code has been tested on a VAX 4000
VLC under VMS 5.5-1 with no ill effects.  It should work okay on any VMS
system, but there are no quarantees, *especially* once you begin modifying it
for your own purposes.  (That is the whole point of examples, after all.)


==============================================================================
Wayne Sewell                            |INET: wayne@tachyon.lonestar.org
Tachyon Software Consulting             |UUCP: uupsi!uupsi6!tachyon!wayne
P. O. Box 550937, Dallas TX  75355-0937 |Voice: (214)-553-9760, Fax: -553-0077
==============================================================================