HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

An executive image is an image that is mapped into system space as part of the OpenVMS executive. It contains data, routines, and initialization code specific to an image's functions and features. An executive image is implemented as a form of shareable image. Like any shareable image, it has a global symbol table, image section descriptors, and an image activator fixup section. Unlike a shareable image, however, an executive image does not contain a symbol vector.

Universally available procedures and data cells in system-supplied executive images are accessed through entries provided by the symbol vectors in the system base images SYS$BASE_IMAGE.EXE and SYS$PUBLIC_VECTORS.EXE. References to an executive image are resolved through these symbol vectors, whether from an executive image or from a user executable or shareable image.

Unlike a system-supplied executive image, an executive image that you create cannot provide universally accessible entry points and symbols in this manner. Instead, it must establish its own vector of procedure descriptors for its callable routines and make the address of that vector available systemwide.

The OpenVMS executive loader imposes several requirements on the sections of any executive image. These requirements include the following:

• An executive image can contain at most one image section of the following types and no others:
  • Nonpaged execute section (for code)
  • Nonpaged read/write section (for read-only and writable data, locations containing addresses that must be relocated at image activation, and the linkage section for nonpaged code)
  • Paged execute section (for code)
  • Paged read/write section (for read-only and writable data, locations containing addresses that must be relocated at image activation, and the linkage section for pageable code)
  • Initialization section (for initialization procedures and their associated linkage section and data)
  • Image activator fixup section
  
  The modules of an executive image define program sections (PSECT) with distinct names. The named PSECT is necessary so that the program sections can be collected into clusters, by means of the COLLECT= linker option, during linking. A COLLECT= option specified in the linking of an executive image generates each of the first five image sections.
  The linker creates the image activator fixup section to enable the image activator to finally resolve references to SYS$BASE_IMAGE.EXE and SYS$PUBLIC_VECTORS.EXE with addresses within the loaded executive image. Once the executive image has been initialized, the OpenVMS executive loader deallocates the memory for both the fixup section and the initialization section.
• In your linker options file, you use the COLLECT= option to collect the program sections from the modules comprising the executive image and place them into one of the standard clusters of an executive image, as described above, marked with the appropriate attributes. If the attributes of a PSECT being collected into an image section do not match the attributes of that section, you use the PSECT_ATTR= option to force the attributes to match. All PSECT must have the same attributes so that only one image section is produced from the cluster.
  Note that, on OpenVMS Alpha systems, the execute section cannot contain data. You must collect all data, whether read-only or writable, into one of the read/write sections.
• You link an executive image as a type of shareable image that can be loaded into system space by the executive loader. You may link an executive image in such a way (using the /SECTION_BINDING qualifier to the LINK command) that the executive loader consolidates its image sections into granularity hint regions within memory with similar image sections of the executive. This process yields a tangible performance benefit on OpenVMS Alpha systems. See the OpenVMS Linker Utility Manual for more information about section binding.
  See Section 4.7.2.2 for a template of a LINK command and linker options file used to produce an executive image.

An executive image can contain one or more initialization procedures that are executed when the image is loaded. If the image is listed in SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DAT as created by means of System Management utility (SYSMAN) commands, initialization procedures can be run at various stages of system initialization.

An initialization routine performs a variety of functions, some specific to the features supported by the image and others required by many executive images. An executive image declares an initialization routine by invoking the INITIALIZATION_ROUTINE macro (see Section 4.7.2.1).

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. One method for accomplishing this involves the following procedure:

• Establishing a vector table within the executive image. For instance, the MACRO-32 Compiler for OpenVMS Alpha would compile the following into the address of a vector table consisting of the procedure values of routines residing elsewhere in the image:

  ROUTINE_VECTOR: .ADDRESS ROUTINE_A ;address of routine A .ADDRESS ROUTINE_B ;address of routine B . . . .ADDRESS ROUTINE_M ;address of routine M

• Declaring an initialization procedure using the INITIALIZATION_ROUTINE macro.
• Loading the image by calling LDR$LOAD_IMAGE as described in Section 4.7.2.4, with LDR$V_USER_BUF set in the flags longword that is the second argument to LDR$LOAD_IMAGE and with the address of a user buffer in the third argument. The dynamic loader passes the address of the user buffer to the initialization procedure.
  Alternatively, you can use the System Management utility (SYSMAN) to load the executive image. Using a SYSMAN command to update the OpenVMS system images file (SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA) allows the image to be loaded and initialized at various phases of system initialization (see Section 4.7.2.3).
• Inserting code in the initialization routine that locates the vector table and stores it in a place accessible to users of routines in the executive image.
  An initialization routine can accomplish this by returning the address of the vector table to the caller of LDR$LOAD_IMAGE in the specified user buffer. The caller of LDR$LOAD_IMAGE can take whatever steps necessary to make the routines accessible to potential callers. One such mechanism is to call the Create Logical Name ($CRELNM) system service to establish a systemwide logical name whose equivalence name is the address of the vector table.

The following describes the invocation format of the INITIALIZATION_ROUTINE macro. An equivalent macro, $INITIALIZATION_ROUTINE is provided for BLISS programmers. For C programmers, INIT_RTN_SETUP.H in SYS$LIB_C.TLB is available.

Declares a routine to be an initialization routine.

Format

INITIALIZATION_ROUTINE name [,system_rtn=0] [,unload=0] [,priority=0]

Parameters

name

Name of the initialization routine.

[system_rtn=0]

Indicates whether the initialization routine is external to the module invoking the macro. The default value of 0, indicating that the initialization routine is part of the current module, is the only option supported on OpenVMS Alpha systems.

[unload=0]

Indicates whether the name argument specifies an unload routine. The default value of 0, indicating that the argument specifies an initialization routine, is the only option supported on OpenVMS Alpha systems.

[priority=0]

Indicates the PSECT in which the entry for this initialization routine should be placed. Routines that specify the priority argument as 0 are placed in the first PSECT (EXEC$INIT_000); those that specify a value of 1 are placed in the second (EXEC$INIT_001). The routines in the first PSECT are called before those in the second.

Description

The INITIALIZATION_ROUTINE macro declares a routine to be an initialization routine. It enters a vector for the routine in the initialization routine vector table, guaranteeing that this routine is called when the image is loaded by the OpenVMS loader.

4.7.2.2 Linking an Executive Image (Alpha Only)

! Replace 'execlet' with your image name

$ LINK/ALPHA/USERLIB=LNK$LIBRARY/NATIVE_ONLY/BPAGES=14 -
 /REPLACE/SECTION/NOTRACEBACK-
 /SHARE=EXE$:execlet-
 /MAP=MAP$:execlet /FULL /CROSS -
 /SYMBOL=EXE$:execlet -
 SYS$INPUT/OPTION, -
!
SYMBOL_TABLE=GLOBALS
! Creates .STB for System Dump Analyzer
CLUSTER=execlet,,,- (1)
ALPHA$LIBRARY:STARLET/INCLUDE:(SYS$DOINIT) - (2)
! Insert executive object code here
ALPHA$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE/SHAREABLE/SELECTIVE
PSECT_ATTR=EXEC$INIT_LINKAGE,PIC,USR,CON,REL,GBL,NOSHR,EXE,RD,WRT,NOVEC  (3)
!
COLLECT=NONPAGED_READONLY_PSECTS/ATTRIBUTES=RESIDENT,-  (4)
 nonpaged_code
COLLECT=NONPAGED_READWRITE_PSECTS/ATTRIBUTES=RESIDENT,-
 nonpaged_data,-
 nonpaged_linkage
COLLECT=PAGED_READONLY_PSECTS,-
 paged_code,-
 $CODE$
COLLECT=PAGED_READWRITE_PSECTS,-
 paged_data,-
 paged_linkage,-
 $LINK$,-
 $PLIT$,-
 $INITIAL$,-
 $LITERAL$,-
 $GLOBAL$,-
 $OWN$,-
 $DATA$
COLLECT=INITIALIZATION_PSECTS/ATTRIBUTES=INITIALIZATION_CODE,-
 EXEC$INIT_CODE,-
 EXEC$INIT_LINKAGE,-
 EXEC$INIT_000,-
 EXEC$INIT_001,-
 EXEC$INIT_002,-
 EXEC$INIT_SSTBL_000,-
 EXEC$INIT_SSTBL_001,-
 EXEC$INIT_SSTBL_002

1. The CLUSTER= option creates the named cluster execlet, specifying the order in which the linker processes the listed modules.
2. The object module SYS$DOINIT (in STARLET.OLB) is explicitly linked into an executive image. This module declares the initialization routine table and provides routines to drive the actual initialization of an executive image.
3. The image sections in an executive image are generated according to the attributes assigned to program sections within source modules by the compilers and linker. Because an executive image can consist only of a certain number and type of image section, the options file contains PSECT_ATTR= options to coerce the attributes of various program sections contributing to the image so that the linker produces only one image section from the cluster. Correspondingly, the options file consists of a set of COLLECT= options clauses to collect these program sections into each permitted image section.
4. This series of COLLECT= options is required to create and assign image section attributes (RESIDENT or INITIALIZATION_CODE) to the NONPAGED_READONLY_PSECTS, NONPAGED_READWRITE_PSECTS, and INITIALIZATION_PSECTS image sections of an executive image. Each COLLECT= option collects a set of program sections with similar attributes into a cluster that the linker uses to produce one of the permitted image sections for an executive image.

There are two methods of loading an executive image:

• Calling LDR$LOAD_IMAGE to load the executive image at run time. This method lets you pass the address of a buffer to the image's initialization routine by which the caller and the initialization routine can exchange data. Section 4.7.2.4 describes LDR$LOAD_IMAGE. Note that you must link the code that calls LDR$LOAD_IMAGE against the system base image, using the /SYSEXE qualifier to the LINK command.
• Using the SYSMAN SYS_LOADABLE ADD command and updating the OpenVMS system images file (SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA). This method causes the executive image to be loaded and initialized during the phases of system initialization. (See VMS for Alpha Platforms Internals and Data Structures for information about how an executive image's initialization routine is invoked during system initialization.)

To load an executive image with the System Management utility (SYSMAN), perform the following tasks:

1. Copy the executive image to SYS$LOADABLE_IMAGES.
2. Add an entry for the executive image in the data file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX, as follows:

   SYSMAN SYS_LOADABLE ADD _LOCAL_ executive-image - /LOAD_STEP = SYSINIT - /SEVERITY = WARNING - /MESSAGE = "failure to load executive-image"

3. Invoke the SYS$UPDATE:VMS$SYSTEM_IMAGES.COM command procedure to generate a new system image data file (file name SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA). During the bootstrap, the system uses this data file to load the appropriate images.
4. Reboot the system. This causes the new executive image to be loaded into the system.

The following is a description of the callable interface to LDR$LOAD_IMAGE.

Loads an OpenVMS executive image into the system.

SYSLDR_DYN

Format

LDR$LOAD_IMAGE filename ,flags ,ref_handle ,user_buf

Arguments

filename

OpenVMS usage	character string
type	character string
access	read only
mechanism	by descriptor

The longword address of a character string descriptor containing the file name of the executive image to be loaded. The file name can include a directory specification and image name, but no device name. If you omit the directory specification, LDR$LOAD_IMAGE supplies SYS$LOADABLE_IMAGES as the default.

flags

OpenVMS usage	flags
type	longword (unsigned)
access	read only
mechanism	value

A flags longword, containing the following bit fields. (Symbolic names for these bit fields are defined by the $LDRDEF macro in SYS$LIBRARY:LIB.MLB.)

Bit Field	Description
LDR$V_PAG	When set, indicates that the image should be loaded with its pageable sections resident. The flag is generally based on the value of the bit 0 in the S0_PAGING system parameter.
LDR$V_UNL	When set, indicates that the image may be removed from memory.
LDR$V_OVR	When set, indicates that the image's read-only sections should not be overwritten during bugcheck processing. This flag is not used on OpenVMS Alpha systems.
LDR$V_USER_BUF	When set, indicates that the caller has passed the address of a buffer that should be passed to the initialization routine.
LDR$V_NO_SLICE	When set, indicates that the image's sections should not be loaded into a granularity hint region.

ref_handle

OpenVMS usage	address
type	longword (signed)
access	write only
mechanism	by reference

The longword address of a reference handle, a three-longword buffer to be filled by LDR$LOAD_IMAGE as follows:

+00	Address of loaded image or zero if image was loaded sliced.
+04	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.
+08	Loaded image sequence number.

user_buf

OpenVMS usage	address
type	longword (signed)
access	read only
mechanism	by reference

The longword address of a user buffer passed to executive image's initialization routine if LDR$V_USER_BUF is set in the flags longword.

LDR$LOAD_IMAGE must be called in executive mode.

RETURNS

OpenVMS usage	cond_value
type	longword (unsigned)
access	write only
mechanism	by value

Status indicating the success or failure of the operation.

Return Values

SS$_ACCVIO	Unable to read the character string descriptor containing the file name of the executive image to be loaded or to write the reference handle.
LOADER$_BAD_GSD	An executive image was loaded containing a global symbol that is not vectored through either the SYS$BASE_IMAGE or the SYS$PUBLIC_VECTORS image.
SS$_BADIMGHDR	Image header is larger than two blocks or was built with a version of the linker that is incompatible with LDR$LOAD_IMAGE.
LOADER$_BADIMGOFF	During a sliced image load request, a relocation or fixup operation was attempted on an image offset that has no resultant address within the image.
LOADER$_DZRO_ISD	A load request was made for an executive image that illegally contains demand zero sections.
SS$_INSFARG	Fewer than three arguments were passed to LDR$LOAD_IMAGE, or, with LDR$V_USER_BUF set in the flags longword, fewer than four arguments.
SS$_INSFMEM	Insufficient nonpaged pool for the LDRIMG structure or insufficient physical memory to load nonpageable portion of an executive image (that is, an image loaded as nonsliced).
SS$_INSFSPTS	Insufficient system page table entries (SPTEs) to describe the address space required for the executive image to be loaded as nonsliced.
LOADER$_MULTIPLE_ISDS	A load request was made for an image that was not linked correctly because it contains more than one each of the following types of sections: fixup initialization nonpaged code nonpaged data paged code paged data
LOADER$_NO_PAGED_ISDS	SYSBOOT failed to load the executive image because it contains either paged code or paged data sections.
SS$_NOPRIV	LDR$LOAD_IMAGE was called from user or supervisor mode.
LOADER$_NO_SUCH_IMAGE	A load request was made for an executive image that was linked against a shareable image that is not loaded. The only legal shareable images for executive images are SYS$BASE_IMAGE and SYS$PUBLIC_VECTORS.
SS$_NORMAL	Normal, successful completion.
LOADER$_PAGED_GST_TOBIG	An executive image has more global symbols in the fixup data than can fit in the loader's internal tables.
LOADER$_PSB_FIXUPS	A load request was made for an executive image that contains LPPSB fixup because it was linked /NONATIVE_ONLY. Executive images must be linked /NATIVE_ONLY.
LOADER$_SPF_TOBIG	The loader's internal tables cannot accommodate all of the executive image fixups that must be postponed to later in the bootstrap operation.
SS$_SYSVERDIF	Image was linked with versions of executive categories incompatible with those of the running system.
LOADER$_VEC_TOBIG	An attempt to load an executive image failed because the image's symbol vector updates for SYS$BASE_IMAGE and SYS$PUBLC_VECTORS exceed the size of the loader's internal tables.
Other	Any RMS error status returned from $OPEN failures. Any I/O error status returned from $QIO failures.

Description

LDR$LOAD_IMAGE loads an executive image into system space and calls its initialization routine. Optionally, LDR$LOAD_IMAGE returns information about the loaded image to its caller.

The initialization routine is passed by two or three longword arguments, depending upon the setting of LDR$V_USER_BUF:

• Address of loaded image data block (LDRIMG)
• The flags longword
• The longword address of a user buffer passed to the executive image's initialization routine (if LDR$V_USER_BUF is set in the flags longword)