Updated: 11 December 1998

OpenVMS Programming Concepts Manual

Status indicating the success or failure of the operation.

Return Values

SS$_ACCVIO	Unable to write to the location indicated by local_address or ast_counter_address.
SS$_ILLSER	Routine was called with IPL greater than 0, or an illegal target_address_type was specified. If target_address_type is EACB$K_GENERAL_REGISTER, this status can indicate that the values of buffer_size and target_address would cause a target process read extending beyond R31 (the last available register).
SS$_INSFMEM	Insufficient memory available for specified buffer.
SS$_NONEXPR	The ipid argument does not correspond to an existing process.
SS$_NORMAL	The interprocess read finished successfully.
SS$_TIMEOUT	The read operation did not finish within a few seconds.

Description

EXE$READ_PROCESS reads data from a target process's address space and writes it to a buffer in the local process's address space.

EXE$READ_PROCESS allocates nonpaged pool for an AST control block (ACB), an ACB extension, and a buffer of the specified size. It initializes the extended ACB with information describing the data transfer and then delivers an AST to the target process to perform the operation. The data is read in the context of the target process from its address space or registers into nonpaged pool. An AST is then queued to the requesting process to complete the read operation by copying the data from pool to the process's buffer.

EXE$READ_PROCESS does not return to its caller until the read is completed, an error is encountered, or it has timed out. (The current timeout value is 3 seconds.)

Reads data from the local process's address space and writes it to a target process's registers or a buffer in a target process's address space.

Format

status = EXE$WRITE_PROCESS (ipid, buffer_size, local_address, target_address, target_address_type, ast_counter_address)

Arguments

ipid

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

Internal process ID of the target process.

buffer_size

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

Number of bytes to transfer. If target_address_type is EACB$K_GENERAL_REGISTER, the values of target_address and buffer_size together determine how many 64-bit registers are written, in numeric order, from the buffer. A partial register is written for any value that is not a multiple of 8.

If you specify buffer_size to be larger than 8, more than one register is written from the buffer. Registers are written in numeric order, followed by the PC and PS, starting at the register indicated by target_address.

If target_address_type is EACB$K_GENERAL_REGISTER and the values of buffer_size and target_address would cause a write extending beyond R31 (the last available register), EXE$WRITE_PROCESS returns SS$_ILLSER status.

local_address

OpenVMS usage	longword_unsigned
type	longword (unsigned)
access	read only
mechanism	by reference

Address in local process from which data is to be transferred.

target_address

OpenVMS usage	longword_unsigned
type	longword (unsigned)
access	read only
mechanism	by reference (if address) by value (if constant)

If target_address_type is EACB$K_MEMORY, address in target process at which the transfer is to start.

If target_address_type is EACB$K_GENERAL_REGISTER, symbolic constant indicating at which general register the transfer should start. Possible constant values include EACB$K_R0 through EACB$K_R29, EACB$K_PC, and EACB$K_PS.

target_address_type

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

Symbolic constant indicating whether the target_address argument is a memory address (EACB$K_MEMORY) or a general register (EACB$K_GENERAL_REGISTER). Floating-point registers are not supported as target addresses.

ast_counter_address

OpenVMS usage	longword_unsigned
type	longword (unsigned)
access	read only
mechanism	by reference

Address of a longword used internally as an AST counter by EXE$READ_PROCESS and EXE$WRITE_PROCESS to detect errors. Supply the same address in the ast_counter_address argument for every call to these routines.

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 from the location indicated by local_address or write to the location indicated by ast_counter_address.
SS$_ILLSER	Routine was called with IPL greater than 0, an illegal target_address_type was specified. If target_address_type is EACB$K_GENERAL_REGISTER, this status can indicate that the values of buffer_size and target_address would cause a process write extending beyond R31 (the last available register).
SS$_INSFMEM	Insufficient memory available for specified buffer.
SS$_NONEXPR	The ipid argument does not correspond to an existing process.
SS$_NORMAL	The interprocess write finished successfully.
SS$_TIMEOUT	The write operation did not finish within a few seconds.

Description

EXE$WRITE_PROCESS reads data from the local process's address space and writes it to a target process's registers or a buffer in a target process's address space.

EXE$WRITE_PROCESS allocates nonpaged pool for an AST control block (ACB), an ACB extension, and a buffer of the specified size. It initializes the extended ACB with information describing the data transfer, copies the data to be written to the target process into the buffer, and then delivers an AST to the target process to perform the operation.

The AST routine copies the data from pool into the target location and then queues an AST to the requesting process to complete the write operation.

EXE$WRITE_PROCESS does not return to its caller until the read is completed, an error is encountered, or it has timed out. (The current timeout value is 3 seconds.)

3.6.2 Writing an Executive Image (Alpha Only)

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 are 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 image activator fixup section is created by the linker 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 3.6.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 3.6.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 3.6.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 3.6.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.

For additional information about OpenVMS executive images, see VMS for Alpha Platforms Internals and Data Structures.

3.6.2.1 INITIALIZATION_ROUTINE Macro (Alpha Only)

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.

3.6.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 3.6.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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5841PRO_009.HTML