[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

3.6.2.4 LDR$LOAD_IMAGE (Alpha Only)

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


LDR$LOAD_IMAGE

Loads an OpenVMS executive image into the system.
Module 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 unused 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.
Context 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 to its caller information about the loaded image.

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

3.6.2.5 LDR$UNLOAD_IMAGE (Alpha Only)

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


LDR$UNLOAD_IMAGE

Unloads a removable executive image. This routine is called to unload an execlet. All resources are returned.
Module SYSLDR_DYN

Format

LDR$UNLOAD_IMAGE filename ,ref_handle


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 unloaded. The file name must be supplied exactly as it was supplied to LDR$LOAD_IMAGE when the executive image was loaded.

ref_handle


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

The longword address of the reference handle containing the three-longword block returned by LDR$LOAD_IMAGE when the executive image was loaded.
Context LDR$UNLOAD_IMAGE must be called in kernel 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$_INSFARG LDR$UNLOAD_IMAGE was not called with two parameters.
SS$_BADPARAMS Reference handle data inconsistent with LDRIMG block that matches the name in the first argument.
LOADER$_MARKUNL A call was made to the LDR$UNLOAD_IMAGE routine to unload a removable executive image that already has an outstanding unload request against it.
SS$_NOPRIV LDR$UNLOAD_IMAGE was not called in kernel mode.
SS$_NORMAL Executive image was successfully removed from the system.
LOADER$_NOT_UNL A call was made to LDR$UNLOAD_IMAGE to unload an executive image that is not loaded or that was not loaded with the LDR$V_UNL flag bit set.
LOADER$_UNL_PEN A call was made to LDR$UNLOAD_IMAGE to unload an executive image that is in use. The image is marked to be unloaded later.

Description

LDR$UNLOAD_IMAGE removes an executive image from system space and returns all memory resources allocated when the image was loaded. Images can only be removed if they were originally loaded with the bit LDR$V_UNL set in the input flags to LDR$LOAD_IMAGE.

3.7 Synchronizing Programs by Specifying a Time for Program Execution

You can synchronize timed program execution in the following ways:

3.7.1 Obtaining the System Time

The process control procedures that allow you to synchronize timed program execution require you to supply a system time value.

You can use either system services or RTL routines for obtaining and reading time. They are summarized in Table 3-7. With these routines, you can determine the system time, convert it to an external time, and pass a time back to the system. The system services use the operating system's default date format. With the RTL routines, you can use the default format or specify your own date format. However, if you are just using the time and date for program synchronization, using the operating system's default format is probably sufficient.

When using the RTL routines to change date/time formats, initialization routines are required. Refer to the OpenVMS RTL Library (LIB$) Manual for more information.

See Chapter 6 for a further discussion of using timing operations with the operating system.

Table 3-7 Time Manipulation System Services and Routines
Routine Description
SYS$GETTIM Obtains the current date and time in 64-bit binary format
SYS$NUMTIM Converts system date and time to numeric integer values
SYS$ASCTIM Converts an absolute or delta time from 64-bit system time format to an ASCII string
SYS$ASCUTC Converts an absolute time from 128-bit Coordinated Universal Time (UTC) format to an ASCII string
LIB$SYS_ASCTIM Converts binary time to ASCII string
SYS$BINTIM Converts a date and time from ASCII to system format
SYS$BINUTC Converts an ASCII string to an absolute time value in the 128-bit UTC format
SYS$FAO Converts a binary value into an ASCII character string in decimal, hexadecimal, or octal notation and returns the character string in an output string
SYS$GETUTC Returns the current time in 128-bit UTC format
SYS$NUMUTC Converts an absolute 128-bit binary time into its numeric components. The numeric components are returned in local time
SYS$TIMCON Converts 128-bit UTC to 64-bit system format or 64-bit system format to 128-bit UTC based on the value of the convert flag
LIB$ADD_TIMES Adds two quadword times
LIB$CONVERT_DATE_STRING Converts an input date/time string to an operating system internal time
LIB$CVT_FROM_INTERNAL_TIME Converts internal time to external time
LIB$CVTF_FROM_INTERNAL_TIME Converts internal time to external time (F-floating value)
LIB$CVT_TO_INTERNAL_TIME Converts external time to internal time
LIB$CVTF_TO_INTERNAL_TIME Converts external time to internal time (F-floating value)
LIB$CVT_VECTIM Converts 7-word vector to internal time
LIB$DAY Obtains offset to current day from base time, in number of days
LIB$DATE_TIME Obtains the date and time in user-specified format
LIB$FORMAT_DATE_TIME Formats a date and/or time for output
LIB$FREE_DATE_TIME_CONTEXT Frees date/time context
LIB$GET_DATE_FORMAT Returns the user's specified date/time input format
LIB$GET_MAXIMUM_DATE_LENGTH Returns the maximum possible length of an output date/time string
LIB$GET_USERS_LANGUAGE Returns the user's selected langauge
LIB$INIT_DATE_TIME_CONTEXT Initializes the date/time context with a user-specified format
LIB$SUB_TIMES Subtracts two quadword times

3.7.1.1 Executing a Program at a Specified Time

To execute a program at a specified time, use LIB$SPAWN to create a process that executes a command procedure containing two commands---the DCL command WAIT and the command that invokes the desired program. Because you do not want the parent process to remain in hibernation until the process executes, execute the process concurrently.

You can also use the SYS$CREPRC system service to execute a program at a specified time. However, because a process created by SYS$CREPRC hibernates rather than terminates after executing the desired program, Compaq recommends you use the LIB$SPAWN routine unless you need a detached process.

Example 3-14 executes a program at a specified delta time. The parent program prompts the user for a delta time, equates the delta time to the symbol EXECUTE_TIME, and then creates a subprocess to execute the command procedure LATER.COM. LATER.COM uses the symbol EXECUTE_TIME as the parameter for the WAIT command. (You might also allow the user to enter an absolute time and have your program change it to a delta time by subtracting the current time from the specified time. Chapter 6 discusses time manipulation.)

Example 3-14 Executing a Program Using Delta Time

! Delta time 
CHARACTER*17 TIME 
INTEGER LEN 
! Mask for LIB$SPAWN 
INTEGER*4 MASK 
 
! Declare status and library routine 
INTEGER STATUS, LIB$SPAWN 
 
! Get delta time 
STATUS = LIB$GET_INPUT (TIME, 
2                       'Time (delta): ', 
2                       LEN) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 
! Equate symbol to TIME 
STATUS = LIB$SET_SYMBOL ('EXECUTE_TIME', 
2                        TIME(1:LEN)) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 
! Set the mask and call LIB$SPAWN 
MASK = IBSET (MASK,0)            ! Execute subprocess concurrently 
STATUS = LIB$SPAWN('@LATER', 
2                  'DATA84.IN', 
2                  'DATA84.RPT', 
2                  MASK) 
 
END 

LATER.COM

$ WAIT 'EXECUTE_TIME' 
$ RUN SYS$DRIVE0:[USER.MATH]CALC                              
$ DELETE/SYMBOL EXECUTE_TIME 

3.7.1.2 Executing a Program at Timed Intervals

To execute a program at timed intervals, you can use either LIB$SPAWN or SYS$CREPRC.

Using LIB$SPAWN

Using LIB$SPAWN, you can create a subprocess that executes a command procedure containing three commands: the DCL command WAIT, the command that invokes the desired program, and a GOTO command that directs control back to the WAIT command. Because you do not want the parent process to remain in hibernation until the subprocess executes, execute the subprocess concurrently. See Section 3.7.1.1 for an example of LIB$SPAWN.

Using SYS$CREPRC

Using SYS$CREPRC, create a detached process to execute a program at timed intervals as follows:

  1. Create and hibernate a process---Use SYS$CREPRC to create a process that executes the desired program. Set the PRC$V_HIBER bit of the stsflg argument of the SYS$CREPRC system service to indicate that the created process should hibernate before executing the program.
  2. Schedule a wakeup call for the created subprocess---Use the SYS$SCHDWK system service to specify the time at which the system should wake up the subprocess, and a time interval at which the system should repeat the wakeup call.

Example 3-15 executes a program at timed intervals. The program creates a subprocess that immediately hibernates. (The identification number of the created subprocess is returned to the parent process so that it can be passed to SYS$SCHDWK.) The system wakes up the subprocess at 6:00 a.m. on the 23rd (month and year default to system month and year) and every 10 minutes thereafter.

Example 3-15 Executing a Program at Timed Intervals

! SYS$CREPRC options and values 
INTEGER OPTIONS 
EXTERNAL PRC$V_HIBER 
! ID of created subprocess 
INTEGER CR_ID 
! Binary times 
INTEGER TIME(2), 
2       INTERVAL(2) 
   .
   .
   .
! Set the PRC$V_HIBER bit in the OPTIONS mask and 
! create the process 
OPTIONS = IBSET (OPTIONS, %LOC(PRC$V_HIBER)) 
STATUS = SYS$CREPRC (CR_ID,         ! PID of created process 
2                    'CHECK',       ! Image 
2                    ,,,,, 
2                    'SLEEP',       ! Process name 
2                    %VAL(4),       ! Priority 
2                    ,, 
2                    %VAL(OPTIONS)) ! Hibernate 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
! Translate 6:00 a.m. (absolute time) to binary 
STATUS = SYS$BINTIM ('23-- 06:00:00.00', ! 6:00 a.m. 
2                    TIME) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
! Translate 10 minutes (delta time) to binary 
STATUS = SYS$BINTIM ('0 :10:00.00',      ! 10 minutes 
2                    INTERVAL) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
! Schedule wakeup calls 
STATUS = SYS$SCHDWK (CR_ID,         ! ID of created process 
2                    , 
2                    TIME,          ! Initial wakeup time 
2                    INTERVAL)      ! Repeat wakeup time 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
   .
   .
   .


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_010.HTML