



FAQ on creating an OpenVMS shareable image 

------------------------------------------------------------------------


A Cookbook Approach

revision: 15-Dec-1995
Please forward suggestions and corrections to the author:

	Stephen Hoffman 
	OpenVMS Engineering 
	Digital Equipment Corporation 
	shoffman@star.enet.dec.com 

Abstract:

	This document provides a cookbook approach to shareable image creation, 
	and includes some associated information. 

Official Documentation:

	The official shareable image documentation is located in the OpenVMS 
	version V5 LINKER reference manual (starting on pages 1-9 and 4-19), the 
	V5 DCL Concepts manual (starting on page 2-1; handling of CTRL/Y and 
	DEBUG on various types of images) and the INSTALL utility reference 
	manual. Under OpenVMS V6, similar documentation is present in the LINKER 
	manual and in the OpenVMS User's Manual. 

Image Name Terminology:

	Shareable Image
	This is essentially a library of routines and data that have already 
	been linked. Shareable images DO NOT GRANT PRIVILEGES. The primary 
	purposes of sharable images are the reduction in memory when mutiple 
	copies of the code are active, to reduce the amount of time required to 
	link images, to allow easy and selective replacement of libraries of 
	code, to allow development of chunks of code within an entire system, 
	and to ease the upgrade or addition of code to a system. Shareable 
	images are the only images supported by the LIB$FIND_IMAGE_SYMBOL 
	routine -- this routine allows a process to perform a variant of 
	`dynamic linking', this call allows an image to access code in a 
	shareable image `on-the-fly'. Shareable images are created from ordinary 
	objects and object libraries by following the steps outlined in this 
	cookbook. 
	Executable image
	This is the parent or top level image, and is the only image that can be 
	RUN. (This image is the only type of image that has a transfer address.) 
	Executable images are the only type of image that should be used with, 
	and the only type that can be granted extra privileges by, the 
	/PRIVILEGED qualifier on an INSTALL CREATE or REPLACE command. 
	Executable images are also the only type of images that can grant an 
	identifier via a subsystem identifer access control list entry (ACE). 
	See the comments on INSTALL, below. 
	User-written system service (UWSS)
	This image is sometimes confusingly called a `privileged shareable 
	image'. This image is quite different from the typical shareable image 
	and involves a completely different scheme of dispatching control within 
	the image. A UWSS involves a different build procedure, and while it can 
	grant privileges to unprivileged callers, it can do so implicitly, due 
	to the implicit SETPRV privilege granted to code execution in kernel or 
	executive mode (two highly privileged processor modes), and by the 
	INSTALL /PROTECT qualifier. 

The Cookbook:

	Here is a Cookbook approach to (ordinary) shareable image creation. 
	Differences between OpenVMS VAX and OpenVMS Alpha are called out. 
	1.Determine the names of all symbols that are to be visible outside the 
	shareable image. (These are typically the symbolic names of the various 
	entry points that you want callers of the shareable image to be able to 
	see and use.) These externally visible symbols do not necessarily have 
	to be subroutines, they could also be constants or variables that are 
	intended to be externally visible. 
	Also determine what external symbols (the addresses of data and/or 
	subroutines) that the shareable image will itself reference. (This is 
	code and/or data that the shareable itself is based on.) These are known 
	as external references. 
	ALL external references must be resolved when an image -- be it a 
	shareable or an executable image -- is linked. In the case of a link of 
	a shareable image, all external symbols referenced by code in the 
	shareable must be resolved when the shareable is linked. 
		Note that routines located in a shareable image *can* reference data 
		and/or subroutines in a calling image -- but the shareable image can 
		only access this code (or data) by virtual address. (Otherwise, the 
		linker would complain long and loud about unresolved symbols during the 
		link of the shareable image.) The address of the external code and/or 
		data must be passed into the shareable image routine(s) via some means 
		other than the linker. One method typically used is passing the address 
		into the shareable image via an argument list somewhere -- in some call 
		to a function in the shareable image -- but the address of the code/data 
		could be passed in to the code in the shareable image by method as 
		esoteric as a mailbox. (Typical shareable image applications will *not* 
		reference data and/or code in a calling image. In most cases, the code 
		needed by the shareable and by the parent image will be relocated into 
		the shareable image, or into a second `lower-level' shareable image 
		located `beneath' both the shareable image under development, and 
		obviously underneath the parent executable image.) 

	Shareable images are sensitive to the external models used by the 
	particular compiler(s) in use. This document assumes the VAX C external 
	model, and will cover the use of OpenVMS VAX transfer vectors or OpenVMS 
	Alpha SYMBOL_VECTOR linker options. 
		NOTE: Building shareable images with the DEC C compiler may require the 
		specification of the (non-default) /SHARE_GLOBAL qualifier. This 
		qualifier causes externs to be promoted and to thus become visible 
		outside the image being built. 
		If using OpenVMS VAX transfer vectors or the OpenVMS Alpha SYMBOL_VECTOR 
		linker option, /SHARE_GLOBAL need not be specified. 
		The /SHARE_GLOBAL qualifier is not required under VAX C. 
		Further information on transfer vectors and on SYMBOL_VECTOR linker 
		options is included below. 

	2.(OpenVMS VAX) Create a set of transfer vectors for the symbols. 
	The transfer vectors are located at a known position within the 
	shareable image -- typically at the front -- and the various offsets are 
	used to dispatch the run-time calls into the actual code position(s) 
	within the shareable image. Use of consistent offsets means callers do 
	not need to relink the calling image(s) when the shareable image is 
	modified. 
	An example transfer vector -- XFRVEC.MAR -- looks like this: 

	    .title	$$$XFRVEC facnam_SHR Transfer Vectors
	    .ident	/facnam_SHR V1.0-0/
	    ; create a program section to hold just the vectors
	    ; keep all transfer vectors quadword aligned.
	    .psect	$$$XFRVEC,exe,shr,nowrt,rd,pic,quad

	    ; For routines entered via a CALLS or CALLG instruction:
	    .macro      XFRVEC_CALL     entry_point,entry_point_int
	    .align      QUAD
	    .transfer   entry_point
	    .External   entry_point_int
	    .mask       entry_point_int
	    JMP         l^entry_point_int+2
	    entry_point::	; allows .transfer to work.
	    .endm

	    ; define a macro to simplify creating a transfer vector
	    ; to a routine located in the shareable image.
	    .macro	XFRVEC	entry_point
	    .align	QUAD
	    .transfer	entry_point
	    .mask	entry_point
	    JMP		l^entry_point+2
	    .endm

	    ; define a macro that places a longword constant directly
	    ; into the transfer vector array.
	    .macro	XFRCON	constant
	    .align	QUAD
	    .long	constant
	    .endm

	    ; and start defining the transfer vectors...
	    XFRCON	42
	    XFRVEC	entry_point_name1,entry__point_name1
	    XFRVEC	entry_point_name2,entry__point_name2
	    
	    .End
	    

	Use the above template for building a set of transfer vectors. You will 
	need to substitute the externally visible symbols -- those symbols that 
	you found based on step 1 -- in place of the dummy entry point names 
	(entry_point_name1 or entry_point_name2) used in the template. 
	You do not need to change the symbol names of any externally visible 
	symbols. You can (and probably should) use the same name in the transfer 
	vectors (the transfer vectors are the .TRANSFER-created stuff in the 
	MACRO32 file) as you have used in the code or data in the object 
	file(s). The symbol used in the transfer vector will be the one visible 
	to the callers of the shareable image. The linker knows that a TRANSFER 
	may duplicate another internal symbol. (The linker uses the value from 
	the transfer directive when it builds the externally-visible shareable 
	image symbol table -- sharable and executable images that link against 
	the shareable image never realize there is a second (internal) symbol of 
	the same name, since it is not included in the externally-visible 
	shareable image symbol table.) (Note that this means all calls to an 
	external entry point that are made from within a shareable image DO NOT 
	use the shareable image transfer vector; calls are made directly to the 
	internal routine.) 
		NOTE: The OpenVMS Alpha systems include a change in the handling of 
		symbols in the transfer vector -- on OpenVMS Alpha systems, symbols are 
		not logically duplicated. On OpenVMS Alpha systems, references to the 
		particular symbol *always* pass through the symbol vectors. (On OpenVMS 
		VAX systems, references from within the shareable image are resolved 
		directly to the internal incarnation of the symbol and do not involve 
		the transfer vectors.) 
		[Consider recoding the above-listed transfer vector to use a different 
		name for the internally- and the externally-visible symbols.] 

	Put in as many occurences of XFRVEC as you need. Always add new transfer 
	vectors to the end of the list. Never reorder the list. Do not remove 
	any existing vectors. (Jump to a dummy routine that returns a failure 
	status, if you must.) (Reordering the list of vectors or removing 
	individual vectors will break existing applications.) 
	If you really must change the order or remove a vector -- you have 
	decided you must make an incompatible change -- see the info on the 
	GSMATCH option in step 6, below. 
	3.(OpenVMS Alpha) Create a set of transfer vectors in the LINKER options 
	file for the symbols: 

	    SYMBOL_VECTOR = ( entry_point_name1 = PROCEDURE,-
	                      entry_point_name2 = PROCEDURE )
	    

	The OpenVMS Alpha LINKER implements the transfer vectors in the image 
	symbol table, not at a specific point in the image. (The design of the 
	Alpha Alpha pipelining and branch prediction makes the VAX transfer 
	vector scheme rather expensive.) The shareable image support is 
	otherwise the same, though OpenVMS VAX restrictions, such as reordering 
	the vectors, are not an issue on OpenVMS Alpha. Rephrased: a Macro (the 
	language) file containing transfer vectors is *not* required on OpenVMS 
	Alpha. It's all done in the LINKER options file... 
	For declaring a transfer vector for data, use the following lines in the 
	OpenVMS Alpha LINKER options file: 

	    SYMBOL_VECTOR = ( variable1 = DATA,-
	                      variable2 = DATA )
	    

	4.(Both VAX and Alpha) 
	It is quite possible to create a small command procedure that produces 
	either a linker options file or a transfer vector array, based on the 
	contents of a list of entry points -- this procedure would allow 
	maintenance of one source file for both varieties (VAX and Alpha) of 
	transfer vector. 
	5.(VAX) Adapt the following procedure for your environment and files, 
	etc. 

	    $!  LINK.COM
	    $!
	    $!  Turn an object library into a shareable image....
	    $!
	    $!  First, assemble the transfer vectors (the file is built
	    $!	as part of step 2.)
	    $!
	    $   Macro xfrvec.mar /Object=Sys$Scratch:$$$XFRVEC
	    $!
	    $!  Create the link options file on the fly...
	    $!  (CLUSTER and COLLECT are present to pull the transfer
	    $!  versions to the very front of the shareable image.)
	    $!  (This example includes support for VAXC.)
	    $!
	    $   If F$Logical("LNKOPT") .nes. "" then close LNKOPT
	    $   Open/Write LNKOPT Sys$Scratch:$$$xfrvec.opt
	    $   Write LNKOPT  "Cluster=$$$XFRVEC"
	    $   Write LNKOPT  "Collect=$$$XFRVEC,$$$XFRVEC"
	    $   Write LNKOPT  "Sys$Share:VAXCRTL/Share"
	    $   Write LNKOPT  "GSMATCH=LEQUAL,19,88"
	    $   Write LNKOPT  "IDENTIFICATION=""facnam V1.0"" "
	    $   Close LNKOPT
	    $!
	    $!  Put everything together...
	    $!
	    $   Link/Share -
		    /Symbol=facnam_SHR.Stb -
	            /Map=facnam_SHR.Map -
		    /Exec=facnam_SHR.EXE -
	            /NODEBUG /NOTRACEBACK -
		    Sys$Scratch:$$$XFRVEC.Obj, -
		    Sys$Scratch:$$$XFRVEC.Opt/Option, -
		    facnam_SHR.OLB/Lib
	    $!
	    $!  And clean up
	    $!
	    $   Delete Sys$Scratch:$$$XFRVEC.Obj.*
	    $   Delete Sys$Scratch:$$$XFRVEC.Opt.*
	    $!
	    

	6.(Alpha) OpenVMS Alpha does not require transfer vectors; it does not 
	require a transfer vector file. 
	7.Look through the image /MAP produced by the image LINK. In particular, 
	locate ANY variables that have both the PSECT (program section) 
	attribute of "SHR" (shareable) and "WRT" (writeable). Make these 
	variables NOSHR (not shareable) or NOWRT (not writeable) -- how to do 
	this is further discussed later in this section. 
	If you fail to make all shareable PSECTS non-writable, you will have 
	writeable variables shared between processes, and this typically leads 
	to undesirable consequences. If both "WRT" and "SHR" are desired, you 
	will have to INSTALL the shareable with the /WRITEABLE option before 
	anyone can use it. Using this qualifier also restricts installation to a 
	single node in a VMScluster. 
	Also make certain that all code in the shareable is position independent 
	code (PIC). (All Digital VAX high level languages typically produce 
	position independent code -- watch out for code written in MACRO32, 
	however. It is quite possible to write position dependent code in 
	MACRO32.) 
		VAX C has several documented "quirks" involving "extern", "globalref", 
		"globaldef" and "globalvalue" declarations. Each "extern" creates a 
		seperate PSECT. The "global*" declarations typically all get placed in 
		the same PSECT. Also that C extern variables are visible to callers of 
		the shareable image -- the LINKER effectively translates them into 
		UNIVERSAL or TRANSFER type symbols. (As a matter of preference, some 
		folks tend to avoid using extern and global* symbols as much as is 
		possible -- for reasons of personal preference, flexibility and 
		modularity. If one cannot avoid extern or global* symbols, or that a 
		particular situation is made easier by using them, consider using one or 
		two extern structures -- which allows as many variables as needed, 
		without creating a volume of external symbols. And as is to be expected, 
		one should ALWAYS use unique facility prefixes on any extern or global* 
		symbols. This helps avoid symbol name collisions.) 
		DEC C supports various external model pragmas, and these provide better 
		control of the external declarations. 

	Should you wind up with a PSECT marked SHR and you want it NOSHR, you 
	can copy the other PSECT attributes and a NOSHR onto a PSECT_ATTR 
	directive in the LINKER options file. (This is a `brute force' method -- 
	fixing the problem(s) by adding a language keyword (eg: "noshare" in VAX 
	C) in the source is a better long term solution.) The following command 
	procedure can be used to scan the LINK map looking for the WRT, SHR 
	attribute combination. 

	    $!  PSECT_SCAN.COM - This procedure uses $SEARCH to find any
	    $!  PSECTs marked both SHR and WRT.  Any such lines lines
	    $!  lines must be redefined as NOSHR,WRT with a PSECT_ATTR
	    $!  line in the linker or by using a language-specific
	    $!  directive such as the VAX C "noshare" storage modifier.
	    $!
	    $!  
	    $
	    $ search facnam_SHR.map " SHR,"," WRT,"/MATCH=AND -
	        /output=SYS$SCRATCH:facnam_SHR_SHR-WRT.tmp
	    $ save_status = $status
	    $ If save_status .eqs. "%X00000001"
	    $ Then
	    $   ! Successful status means a bad PSECT combination was detected.
	    $   Write Sys$Output "Invalid PSECT attributes have been detected."
	    $   Write Sys$Output "The PSECT(s) requiring adjustment(s) are:"
	    $   Type SYS$SCRATCH:facnam_SHR_SHR-WRT.tmp
	    $   Exit 9
	    $ Endif
	    $ If save_status .eqs. "%X08D78053"
	    $ Then
	    $   ! "no strings matched" means you have *no* problem.
	    $   Write Sys$Output "Successful PSECT_SCAN completion."
	    $   Write Sys$Output "No invalid PSECT attributes have been detected."
	    $   Delete SYS$SCRATCH:facnam_SHR_SHR-WRT.tmp;*
	    $   Exit 1
	    $ Endif
	    $ Exit 1
	    

	8.Adapt the LINK.COM command procedure to allow /TRACEBACK and/or /DEBUG 
	during testing and development. (But by all means, do *not* ship the 
	shareable image with those options....) 
	The debugger "SET IMAGE" command allows you to access and debug 
	shareable image. 
	The INSTALL utility, to prevent security problems, is explicitly coded 
	to refuse installation of any images linked with /TRACEBACK or with 
	/DEBUG. See the comments on INSTALL, below. 
	9.Update the minor version of the GSMATCH line (`88' in the above 
	LINK.COM command procedure) whenever making upward-compatable changes. 
	Update the major version (`19' in the example) when making incompatable 
	changes. 
	Updating the minor version means programs linked against a new shareable 
	will fail when an attempt is made to run the image against an older 
	shareable. Updating the major version forces all images linked against 
	the shareable to be relinked. 
	Programs linked against an older shareable image will work with a newer 
	shareable image. (Assuming both have the same major version number.) 
	A few examples of incompatable changes: 
	  o	re-ordered or removed transfer vectors... 
	  o	routines of the same name that no longer return the same status 
		values... 
	  o	routines that change the documented behaviour of the shareable image in 
		undocumented ways. 

	A few examples of upward compatable changes: 
	  o	new entry points are added at the end of the transfer vectors. 
	  o	a bug is fixed in a routine 
	  o	a new argument is added in an existing routine and the routine knowns 
		how to deal with calls with different numbers of arguments. 

	10.Update the IDENTIFICATION option (in the linker options file; this 
	file is dynamically created by the example command procedure shown 
	above) whenever making releases so that it's obvious what product the 
	shareable is part of. (And what the version number of the shareable is.) 

	The DIGITAL Software Engineering Standards requires that all DIGITAL 
	products place their registered product name and version in this field. 
	(And even if one is not developing a "real" product, this is still 
	considered polite programming practice.) 
	11.Errors and Resolutions: 
	%LINK-E-OUTSIMG 
		Sometimes you will see LINK-E-OUTSIMG errors. These errors are often due 
		to an attempt to write data into a shareable image you are trying to 
		link against. (This error can obviously occur during an attempt to 
		initialize an external symbol.) 
		This error can also occur as a result of a bug in the image section 
		processing in the LINKER utility -- if the address is above 64K pages 
		(hex 02000000), this error can be generated. (Work with the options file 
		to reduce the size of the image section below 64K pages.) This bug is 
		present in the LINKER in OpenVMS V5.5-2, and possibly in later versions. 

What Is An OpenVMS VAX Transfer Vector? 
	The OpenVMS VAX transfer vector construct is little more than a small 
	amount of memory space located at a fixed location, usually at the front 
	of the shareable image. This memory space can contain executable 
	instructions, data, or pointers to either. 
	OpenVMS VAX transfer vectors are typically aligned at longword, quadword 
	or octaword boundaries. Correct alignment facilitates easy replacement 
	of an individual entry without affecting the other entries in the 
	shareable image transfer vector table, and without requiring error-prone 
	padding offset calculations. [For example, the ".mask"/"JMP nn+2" pair 
	might be replaced with a "MOVL SS$_NORMAL,R0"/"RET" pair should a 
	routine no longer be required.] To maintain upward compatibility, the 
	size of the replacement instruction(s) must not alter the alignment (the 
	offset from the base of the image) of other vectors in the table. 
	In the typical case, a vector that references a CALLS/CALLG routine 
	entry point, each entry in the transfer vector contains the contents of 
	the "real" (word-length) CALLS/CALLG entry mask, and a (self-relative 
	and position independent, also known as PC-relative) jump to the first 
	instruction of the "real" routine. (The word-length entry mask [per the 
	VAX Calling Standard] is the two bytes that are located at the entry 
	point, thus the "JMP real_routine_offset_address+2" must skip over 
	them.) 
	Logically, a constant value can be imbedded in the transfer vector as is 
	demonstrated in the XFRCON macro, or as implemented in the ".mask" of 
	the XFRVEC macro. (The former value is a longword value, the latter case 
	is obviously a word.) XFRCON does not attempt to provide a symbolic name 
	for the constant, so any images calling the shareable will have to do 
	some pointer arithmetic to locate the constant value. Your application 
	might want to use a symbol -- use a MACRO32 external_symbol:: (the 
	double colon notation is important), or you might be able to get the 
	.TRANSFER directive to work for you. 
	OpenVMS Alpha does not use the OpenVMS VAX Transfer Vector construct. 

Based Shareable Image Caveats 
	All Digital compilers produce position independent code. Typically, 
	based shareable images result from non-position independent MACRO32 
	code. 
	Based shareable images should be avoided ("like the plague") whenever 
	possible. Based images result in address space conflicts when other 
	shareable images increase in size; thus cause a requirement for frequent 
	image relinks. 
	If the linker reports the shareable image will be based, review the 
	code, locate the offending instruction(s), and rework the path. (The 
	MACRO32 manual contains instructions on position independent design.) 
	If you are taking the time to write a shareable, and the result is a 
	based shareable image -- you've wasted considerable effort for a rather 
	small gain. 

User-Written System Service Caveats (OpenVMS VAX) 
	User-Written System Services, often (confusingly) refered to as 
	"Privileged System Services", are *not* shareable images installed with 
	/PRIVILEGED. User-Written system services are one of the two types of 
	images (the other is an executable image) that can be installed to grant 
	enhanced privileges to a caller. 
	The design and coding required for a user-written system service is 
	documented in the appendix of the system services manual and in the 
	examples in SYS$EXAMPLES:USS*.*. To grant the caller the enhanced 
	privileges, the user-written system service must be installed with the 
	/PROTECT qualifier, *not* with the /PRIVILEGED qualifier. (The INSTALL 
	/PRIVILEGED qualifier should be specified only on an executable image, 
	the qualifier does not have the desired effect of granting privileges on 
	an oridinary shareable image. Specification of /PRIVILEGED does, 
	however, have some potentially interesting, unintended and likely 
	undesireable side effects; it should not be specified on an ordinary 
	shareable image. The same prohibition on specification of the 
	/PRIVILEGED qualifier holds for user-written system services.) 
	User-written system services gain enhanced privileges by the implicit 
	SETPRV privilege that is granted all routines running in executive or 
	kernel mode. See the appendix of the system services reference manual, 
	and the examples in SYS$EXAMPLES:USS*.*, for more information. 
	Failure to specify the INSTALL qualifiers correctly for the specific 
	type of image involved (executable, shareable or privileged system 
	service) leads to confusing error messages, failure to receive enhanced 
	privileges and overzealous treatment as a privileged image. (in the case 
	of an ordinary shareable image installed /PRIVILEGED, no enhanced 
	privileges are granted, but image rundown treatment is that of of a 
	privileged image -- no CTRL/Y DEBUG is allowed. User-written system 
	services should not be installed with /PRIVILEGED, only with /PROTECT. 
	An example of a Digital image that uses the user-written system service 
	interface is the OpenVMS V5.3 (and later) image SYS$SHARE:SECURESHRP.EXE 

	User-written system services, as the routines execute in elevated 
	processor modes and the routines are located in program sections placed 
	on virtual memory pages owned by elevated processor modes, should be 
	debugged with the XDELTA debugger. [One known bug in XDELTA: program 
	sections (psects) in the process or control regions (P0/P1 address 
	space) may need to be marked writeable ("WRT") for the duration of the 
	debugging. Obviously, this problem directly affects user-written system 
	services. XDELTA currently has occassional problems inserting 
	breakpoints in P0/P1 space marked as NOWRT. This typically manifests 
	itself on the XDELTA "B" and "O" commands.] 
	Do not use VAX DEBUG or DECset DEBUG to debug executive or kernel mode 
	code -- if you somehow manage to get the privileged-mode code going in 
	DEBUG, the mechanism by which the debugger implements breakpoints will 
	likely cause a system crash when the breakpoint is hit -- the system 
	will likely crash soon. Use the XDELTA (or for code that will not be 
	running at elevated IPL, DELTA) debugger instead. 

User-Written System Service Caveats (OpenVMS Alpha) 
	OpenVMS Alpha UWSS information will be included in a future update of 
	this document. 
	OpenVMS Alpha UWSS examples are located in SYS$EXAMPLES:UWSS*.*. 

UWSS System Service Alternative: 
	As code in a UWSS gains privileges by execution in a privileged 
	processor mode -- executive or kernel mode -- it can be potentially 
	difficult to perform various operations normally performed only from 
	user-mode code. And as code effectively becomes fully privileged -- 
	implicit SETPRV is granted to code executing in privileged processor 
	modes -- great care must be taken to control the access intentionally 
	and unintentially granted to the user and to the programmer via the UWSS 
	code. 
	If the system is running OpenVMS V6.0 or later, consider using a 
	subsystem access control list entry (ACE) to allow finely-grained 
	control over access, and to avoid the need for executive or kernel mode 
	code -- the subsystem ACE allows the system or application manager to 
	"grant" one or more identifiers to the user for the duration of the 
	execution of an image, via a subsystem ACE on the image(s), and via a 
	standard identifer ACE on the target object. (An "object" can be a file, 
	mailbox, global section, etc.) And unlike an OpenVMS privilege, the 
	access granted (or denied) by a specific identifier can be directly and 
	easily controlled. 
	For information on the subsystem ACE, see the Guide to OpenVMS System 
	Security. 
	Note that there exists a patch for images that use the subsystem ACE and 
	are also installed /SHARED -- this combination causes the image to 
	erroneously exit with the "SUBTRACED" (SS$_SUBTRACED) error. This patch 
	is needed for OpenVMS V6.0 and V6.1 systems -- this problem was 
	corrected in OpenVMS V6.2. 

UWSS SECURITY NOTE: 
	Great care should be used in the design and the implementation of 
	user-written system services (privileged shareable images). User-Written 
	system services are one of the `targets of choice' of system crackers. 
	The user-written system service images are typically rather easy to 
	locate on a system, and an incorrectly designed or coded image -- an 
	insecure image -- will often grant a system cracker enhanced privileges. 
	*Expect* that attempts to breach system security will be made against 
	*all* user-written system service images. 
	Avoid an attempt to implement security checks within a UWSS image if it 
	is possible to perform the necessary security check(s) via a call to the 
	SYS$CHKPRO or SYS$CHECK_ACCESS system service. 

INSTALL, RUN, LIB$FIND_IMAGE_SYMBOL (and the Image Activator) NOTES: 
	The following points discuss some general features and some general 
	restrictions of the OpenVMS image image activation system services -- 
	there are a number of clients of the image activator system services. 
	  o	If an executable image is installed, it can cause the image activator to 
		require that all component shareable images also be installed. This 
		behaviour is intentional and prevents a nefarious user from redirecting 
		a shareable image activation to an "evil twin" shareable image. 
	  o	Installing an image can also require that all logical names used to 
		redirect shareable images during an image activation be defined in 
		executive mode. 
	  o	At most, one image file can be installed /SHARE under a single file 
		name. (The image activator uses only the file name -- and it does not 
		consider the device nor the directory -- when it creates names for 
		sections.) This restriction has been removed in OpenVMS V6.2 and later. 
	  o	To bypass the known image activation search logic in the image 
		activator, specify the file version number on the RUN command. 
	  o	Do not base applications on the section names chosen for an INSTALLed 
		image -- these are the names are displayed by the INSTALL LIST/GLOBAL 
		command. Do not attempt to mix sections created by INSTALL and any 
		global section system services. (This erroneous programming technique is 
		occasionally seen with the COMMON construct.) 
	  o	The LIB$FIND_IMAGE_SYMBOL routine performs a "merged image activation" 
		-- it dynamically merges a shareable image into the address space 
		accessable to the currently executing image, and it returns a pointer to 
		a symbol in the shareable image. (This symbol allows the executable or 
		shareable image that performed the merge to resolve the addresses within 
		the merged image -- these addresses are necessary in order to access and 
		use the code and/or data present in the merged image. 
		Note that there is no way to "unmerge" a specific image, short of the 
		execution of an image (or process) rundown. 
	  o	Shareable images are the only images that are supported by the 
		LIB$FIND_IMAGE_SYMBOL routine. (Other image types might work under 
		certain circumstances; possibly restricted to a particular operating 
		system version or operating system hardware platforms -- but 
		LIB$FIND_IMAGE_SYMBOL merged image activations of these other image 
		types are not supported.) 


Legal
 Digital Equipment Corporation, 1996. The DIGITAL logo is a trademark 
of Digital Equipment Corporation. All other trademarks are the property 
of their respective owners.


Powered by Digital Alpha
Page last updated: "Jun 20 1996"
