[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Programming Concepts Manual


Previous Contents Index

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.
Context The caller of EXE$READ_PROCESS must be executing in kernel mode at IPL 0. Kernel mode ASTs must be enabled.

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


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.
Module PROC_READ_WRITE

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.
Context The caller of EXE$WRITE_PROCESS must be executing in kernel mode at IPL 0. Kernel mode ASTs must be enabled.

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)

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 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:

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.


INITIALIZATION_ROUTINE

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)

The following template can serve as the basis of a LINK command and linker options file used to create an OpenVMS executive image. See the OpenVMS Linker Utility Manual for a full description of most linker qualifiers and options referenced by this example.

Note

Use of the linker to create executive images (specifically the use of the /ATTRIBUTES switch on the COLLECT= option) is not documented elsewhere and is not supported by Compaq.


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

3.6.2.3 Loading an Executive Image (Alpha Only)

There are two methods of loading an executive image:

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.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5841PRO_009.HTML