OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

The calling format of the error routine is as follows:

user-error-procedure old-filespec ,new-filespec ,rms-sts ,rms-stv ,error-source ,user-specified-argument

old-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the file being renamed when the error occurred. If old-resultant-name was specified, it is used to pass the string to the error routine. Otherwise, a class S, type T string is passed. Any string class is supported.
new-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the new file name being used when the error occurred. If new-resultant-name was specified, it is used to pass the string to the error routine. Otherwise, a class S, type T string is passed. Any string class is supported.
rms-sts

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by reference

Primary condition code (FAB$L_STS) which describes the error that occurred. The rms-sts argument is the address of an unsigned longword that contains this primary condition code.
rms-stv

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by reference

Secondary condition code (FAB$L_STV) which describes the error that occurred. The rms-stv argument is the address of an unsigned longword that contains this secondary condition code.
error-source

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by reference

Integer code indicating where the error was found. The error-source argument is the address of a longword containing the error source.
The values of error-source and their meanings are as follows:

0 Error searching for old-filespec

1 Error parsing new-filespec

2 Error renaming file

user-specified-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: unspecified

Value of user-specified-argument that LIB$RENAME_FILE passes to the error routine using the same passing mechanism that was used to pass it to LIB$RENAME_FILE.

If the error routine returns a success status (bit 0 set), then LIB$RENAME_FILE will continue processing files. If the error routine returns a failure status (bit 0 clear), processing ceases immediately and LIB$RENAME_FILE returns with an error status.

If the user-error-procedure argument is not specified, LIB$RENAME_FILE will return to its caller the most severe error status encountered while renaming the files. If the error routine is called for an error, the success status LIB$_ERRROUCAL is returned.

The error routine is not called for errors related to string copying.

Call Format for a Confirm Routine

The calling format of a confirm routine is as follows:

user-confirm-procedure old-filespec ,new-filespec ,old-fab [,user-specified-argument]

old-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the file about to be renamed. If old-resultant-name was specified, it is used to pass the string to the confirm routine. Otherwise, a class S, type T string is passed. Any string class is supported.
new-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification which the file will be given. If new-resultant-name was specified, it is used to pass the string to the confirm routine. Otherwise, a class S, type T string is passed. Any string class is supported.
old-fab

OpenVMS usage: fab

type: unspecified

access: read only

mechanism: by reference

Address of the RMS FAB that describes the file being renamed. Your program may perform an RMS $OPEN on the FAB to obtain file attributes it needs to determine whether the file should be renamed, but must close the file with $CLOSE before returning to LIB$RENAME_FILE.
(Alpha only) If the LIB$M_FIL_LONG_NAMES FLAGS is set, the FAB references a NAML block rather than a NAM block. The NAML block supports the use of long file specifications with a maximum length of NAML$C_MAXRSS. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks.
user-specified-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: unspecified

Value of user-specified-argument passed by LIB$RENAME_FILE to the confirm routine using the same passing mechanism that was used to pass it to LIB$RENAME_FILE. This is an optional argument.
If the confirm routine returns a success value (bit 0 set), the file is renamed; otherwise, the file is not renamed.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_ERRROUCAL Success---error routine called. A file error was encountered but the error routine was called to handle the condition.

LIB$_INVARG Invalid argument. The flags argument has one or more undefined bits set.

LIB$_INVFILSPE Invalid file specification. On VAX, Old-filespec, new-filespec, or default-filespec contains more than 255 characters. On Alpha, Old-filespec, new-filespec, or default-filespec contains more than NAML$C_MAXRSS characters.

LIB$_INVSTRDES Invalid string descriptor. One of the string argument descriptors was not a valid string descriptor.

LIB$_WRONUMARG Wrong number of arguments. An incorrect number of arguments was passed to LIB$RENAME_FILE.

Any condition value returned by LIB$SCOPY_xxx; truncation errors are ignored.

Any condition value returned by RMS. If the user-error-procedure argument was not specified, this is the most severe of the RMS errors which occurred while renaming the files.

LIB$RESERVE_EF

The Reserve Event Flag routine allocates a local event flag number specified by event-flag-number.

Format

LIB$RESERVE_EF event-flag-number

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

event-flag-number

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by reference

Event flag number to be allocated by LIB$RESERVE_EF. The event-flag-number argument contains the address of a signed longword integer that is this event flag number.

Description

LIB$RESERVE_EF allocates a specific local event flag. It differs from LIB$GET_EF, which allocates an arbitrary local event flag, which is the recommended procedure. Reserving a specific local event flag is not recommended because another routine may attempt to use the same flag, and the flag will no longer function as expected.
The following table lists the availability of local event flags.

Number Availability

0 Never used by this routine and always available

1 through 23 Initially reserved; available after being freed by LIB$FREE_EF

24 through 31 Reserved to OpenVMS

32 through 63 Initially free

Note
Beware of running multiple images linked with /NOSYSSHR in the same process and having more than one image make calls to LIB$RESERVE_EF. Each image contains its own copy of the event flag bit array that is designed to be process-wide and synchronize ownership of event flags. Multiple calls to LIB$GET_EF could cause the same event flag to be allocated more than once.

See the OpenVMS Programming Concepts Manual for more information.

Number	Availability
0	Never used by this routine and always available
1 through 23	Initially reserved; available after being freed by LIB$FREE_EF
24 through 31	Reserved to OpenVMS
32 through 63	Initially free

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_EF_ALRRES Event flag already reserved.

LIB$_EF_RESSYS Event flag reserved to system. This occurs if the event flag number is outside the ranges of 1 through 23 and 32 through 63.

Example


PROGRAM RESERVE_EF(INPUT, OUTPUT); routine LIB$RESERVE_EF(%REF EVENT_FLAG_NUM : INTEGER); EXTERN; routine LIB$FREE_EF(%REF EVENT_FLAG_NUM : INTEGER); EXTERN; VAR FLAG_NUM : INTEGER; BEGIN FLAG_NUM := 37; LIB$RESERVE_EF(FLAG_NUM); WRITELN(FLAG_NUM); LIB$FREE_EF(FLAG_NUM); END.

PROGRAM RESERVE_EF(INPUT, OUTPUT); 
 
routine LIB$RESERVE_EF(%REF EVENT_FLAG_NUM : INTEGER); EXTERN; 
routine LIB$FREE_EF(%REF EVENT_FLAG_NUM : INTEGER); EXTERN; 
 
VAR 
  FLAG_NUM : INTEGER; 
 
BEGIN 
  FLAG_NUM := 37; 
  LIB$RESERVE_EF(FLAG_NUM); 
  WRITELN(FLAG_NUM); 
  LIB$FREE_EF(FLAG_NUM); 
END.

This Pascal program generates the following output:
37

LIB$RESET_VM_ZONE

The Reset Virtual Memory Zone routine frees all blocks of memory that were previously allocated from a zone in the 32-bit virtual address space.

Note
No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$RESET_VM_ZONE zone-id

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

zone-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Zone identifier. The zone-id is the address of a longword that contains the identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.

Description

LIB$RESET_VM_ZONE frees all the blocks of memory that were previously allocated from the zone. The memory becomes available to satisfy further allocation requests for the zone; the memory is not returned to the processwide 32-bit page pool managed by LIB$GET_VM_PAGE. Your program can continue to use the zone after you call LIB$RESET_VM_ZONE.
Resetting a zone is a much more efficient way to reuse storage than individually freeing each allocated object in the zone.
It is the caller's responsibility to ensure that he or she has "exclusive" access to the zone while the reset operation is being performed. Results are unpredictable if another thread of control attempts to perform any operation on the zone while LIB$RESET_VM_ZONE is in progress.
If you specified deallocation filling when you created the zone, LIB$RESET_VM_ZONE will fill all of the allocated blocks that are freed.
If the zone you are resetting was created using the LIB$CREATE_USER_VM_ZONE routine, then you must have an appropriate action routine for the reset operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must have specified a user-reset-procedure.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_BADBLOADR An invalid zone-id argument.

LIB$RESET_VM_ZONE_64 (Alpha Only)

The Reset Virtual Memory Zone routine frees all blocks of memory that were previously allocated from a zone in the 64-bit virtual address space.

Format

LIB$RESET_VM_ZONE_64 zone-id

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

zone-id

OpenVMS usage: identifier

type: quadword (unsigned)

access: read only

mechanism: by reference

Zone identifier. The zone-id is the address of a quadword that contains the identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.

Description

LIB$RESET_VM_ZONE_64 frees all the blocks of memory that were previously allocated from the zone. The memory becomes available to satisfy further allocation requests for the zone; the memory is not returned to the processwide 64-bit page pool managed by LIB$GET_VM_PAGE_64. Your program can continue to use the zone after you call LIB$RESET_VM_ZONE_64.
Resetting a zone is a much more efficient way to reuse storage than individually freeing each allocated object in the zone.
It is the caller's responsibility to ensure that he or she has "exclusive" access to the zone while the reset operation is being performed. Results are unpredictable if another thread of control attempts to perform any operation on the zone while LIB$RESET_VM_ZONE_64 is in progress.
If you specified deallocation filling when you created the zone, LIB$RESET_VM_ZONE_64 will fill all of the allocated blocks that are freed.
If the zone you are resetting was created using the LIB$CREATE_USER_VM_ZONE_64 routine, then you must have an appropriate action routine for the reset operation. That is, in your call to LIB$CREATE_USER_VM_ZONE_64, you must have specified a user-reset-procedure.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_BADBLOADR An invalid zone-id argument.

LIB$REVERT

The Revert to the Handler of the Routine Activator routine deletes the condition handler established by LIB$ESTABLISH by clearing the address pointing to the condition handler from the activated routine's stack frame.

Note
No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

This routine is not available to native OpenVMS Alpha programs but is recognized and handled appropriately by most Compaq high-level language compilers.

Format

LIB$REVERT

RETURNS

OpenVMS usage: address

type: address

access: write only

mechanism: by value

Previous contents of SF$A_HANDLER (longword 0) of the caller's stack frame. This is the address of the condition handler previously in effect. If no condition handler was in effect, zero is returned.

Arguments

None.

Description

LIB$REVERT returns the address that it clears from the calling routine's stack frame. LIB$REVERT is used only if your routine is to establish and then cancel a condition handler for a portion of its execution.
LIB$REVERT is provided primarily for use with languages without built-in error-handling facilities, such as Fortran. Do not use LIB$REVERT from BASIC, COBOL, Pascal, or PL/I. See the documentation for the language you are using for information about how that language handles errors.
In VAX MACRO, you merely use the following instruction rather than calling LIB$REVERT:
CLRL (FP) ; set handler address to 0 ; in current stack frame

Condition Values Returned

None.

LIB$RUN_PROGRAM

The Run New Program routine causes the current program to stop running and begins execution of another program.

Format

LIB$RUN_PROGRAM program-name

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

program-name

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

File name of the program to be run in place of the current program. The program-name argument contains the address of a descriptor pointing to this file name string.
The maximum length of the file name is 255 characters. The default file type is .EXE.

Description

LIB$RUN_PROGRAM stops execution of the current program and begins execution of another program.

If successful, control does not return to the calling program. Instead, the $EXIT system service is called, the new program image replaces the old image in the user process, and the command language interpreter (CLI) gives control to the new image.
If unsuccessful, control returns to the command interpreter.

This routine is supported for use with the DCL and MCR CLIs. If an image is run directly as a subprocess or as a detached process, there is no CLI present to perform this function. In those cases, the error status LIB$_NOCLI is returned.
LIB$RUN_PROGRAM causes the current image to exit at the point of the call and directs the CLI, if one is present, to start running another program. If LIB$RUN_PROGRAM executes successfully, control passes to the second program; if not, control passes to the CLI. The calling program cannot regain control. This technique is called chaining.
This routine is provided primarily for compatibility with PDP-11 systems, where chaining is used to extend the address space of a system.
This routine may also be useful in an OpenVMS environment where address space is severely limited and large images are not possible. For example, you might use chaining to perform system generation on a small virtual address space, for a large page file.
With LIB$RUN_PROGRAM, the calling program can pass arguments to the next program in the chain only by using the common storage area. One way to do this is for the calling program to call LIB$PUT_COMMON to pass the information into the common storage area. Then the called program calls LIB$GET_COMMON to retrieve the data.
In general, this practice is not recommended. There is no convenient way to specify the order and type of arguments passed into the common storage area; so programs that pass arguments in this way must know about the format of the data before it is passed. When you use common storage, it is very difficult to keep your program modular and AST-reentrant; a method of arbitration must be designated to define which program can modify common storage and when.
Further, LIB$RUN_PROGRAM cannot be used if no command language interpreter is present, as in the case of image subprocesses and detached subprocesses.
If you want control to return to the caller, use LIB$SPAWN instead.

Condition Values Returned

LIB$_INVARG Invalid argument.

LIB$_NOCLI No CLI present to perform function. The calling process did not have a CLI to perform the function or the CLI did not support the request type. Note that an image run as a subprocess or detached process does not have a CLI.

LIB$_UNECLIERR Unexpected CLI error. The CLI returned an error status which was not recognized. This error may be caused by use of a nonstandard CLI. If this error occurs while using the DCL or MCR CLIs, please report the problem to your Compaq support representative.

Contents

Index

privacy and legal statement

5932PRO_036.HTML

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

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

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

0	Error searching for old-filespec
1	Error parsing new-filespec
2	Error renaming file

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	unspecified

OpenVMS usage:	fab
type:	unspecified
access:	read only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
LIB$_ERRROUCAL	Success---error routine called. A file error was encountered but the error routine was called to handle the condition.
LIB$_INVARG	Invalid argument. The flags argument has one or more undefined bits set.
LIB$_INVFILSPE	Invalid file specification. On VAX, Old-filespec, new-filespec, or default-filespec contains more than 255 characters. On Alpha, Old-filespec, new-filespec, or default-filespec contains more than NAML$C_MAXRSS characters.
LIB$_INVSTRDES	Invalid string descriptor. One of the string argument descriptors was not a valid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments. An incorrect number of arguments was passed to LIB$RENAME_FILE.

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

SS$_NORMAL	Routine successfully completed.
LIB$_EF_ALRRES	Event flag already reserved.
LIB$_EF_RESSYS	Event flag reserved to system. This occurs if the event flag number is outside the ranges of 1 through 23 and 32 through 63.

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

SS$_NORMAL	Routine successfully completed.
LIB$_BADBLOADR	An invalid zone-id argument.

OpenVMS usage:	address
type:	address
access:	write only
mechanism:	by value

LIB$_INVARG	Invalid argument.
LIB$_NOCLI	No CLI present to perform function. The calling process did not have a CLI to perform the function or the CLI did not support the request type. Note that an image run as a subprocess or detached process does not have a CLI.
LIB$_UNECLIERR	Unexpected CLI error. The CLI returned an error status which was not recognized. This error may be caused by use of a nonstandard CLI. If this error occurs while using the DCL or MCR CLIs, please report the problem to your Compaq support representative.