Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

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

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. Old-filespec, new-filespec, or default-filespec contains more than 255 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.

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.

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. 
 
 
      

This Pascal program generates the following output:

37

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.

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.

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.

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 Digital support representative.

The Scan for Characters and Return Relative Position routine is used to find a specified set of characters in the source string. LIB$SCANC makes the VAX SCANC instruction available as a callable routine.

Note On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

Format

LIB$SCANC source-string ,table-array ,byte-integer-mask

RETURNS

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

Relative position in the source string of the character that terminated the operation, or zero if the terminator character is not found. If the source string has a zero length, then a zero is returned.

Arguments

source-string

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

Source string used by LIB$SCANC to index into a table. The source-string argument contains the address of a descriptor pointing to this source string.

table-array

OpenVMS usage:	vector_mask_byte
type:	byte (unsigned)
access:	read only
mechanism:	by reference, array reference

Table that LIB$SCANC indexes into and performs a logical AND operation with the byte-integer-mask byte. The table-array argument contains the address of an unsigned byte array that is this table.

byte-integer-mask

OpenVMS usage:	mask_byte
type:	byte (unsigned)
access:	read only
mechanism:	by reference

Mask on which a logical AND operation is performed with bytes in table-array. The byte-integer-mask argument contains the address of an unsigned byte that is this mask.

Description

LIB$SCANC uses successive bytes of the string specified by source-string to index into a table. The byte selected from the table is the byte on which a logical AND operation is performed with the mask byte. The operation is terminated when the result of the AND operation is equal to 1.

Condition Values Returned

None.

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

5932PRO_035.HTML