hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index

If you are specifying one or more of the action routine arguments, be sure that the descriptor class used to pass resultant-name is the same as the descriptor class required by the action routine. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines, but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use.

new-resultant-name


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

String into which LIB$RENAME_FILE writes the new OpenVMS RMS resultant file specification of the last file processed. The new-resultant-name argument is the address of a descriptor pointing to the new name. This is an optional argument. If present, it is used to store the file specification passed to the user-supplied routines instead of a class S, type T string. Any string class is supported.

If you are specifying one or more of the action routine arguments, be sure that the descriptor class used to pass resultant-name is the same as the descriptor class required by the action routine. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines, but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use.

file-scan-context


OpenVMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference

Context for renaming a list of file specifications. The file-scan-context is the address of a longword that contains this context. You must initialize this longword to zero before the first of a series of calls to LIB$RENAME_FILE. LIB$RENAME_FILE uses the file scan context to retain the file context for multiple input files.

LIB$FILE_SCAN uses this context to retain multiple input file related file context. This is an optional argument; it need only be specified if you are using multiple input files, as the DCL command RENAME does. You may deallocate the context allocated by LIB$FILE_SCAN while processing the LIB$RENAME_FILE requests by calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_FILE have been completed. See the description of LIB$FILE_SCAN for a more detailed description of this argument.


Description

This description is divided into three parts:

Call Format for a Success Routine

The success routine is optional; it is called only if the user-success-procedure argument is specified in the call to LIB$RENAME_FILE.

The calling format of a success routine is as follows:

user-success-procedure old-filespec ,new-filespec [,user-specified-argument]

old-filespec


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

RMS resultant file specification of the file before it was renamed. If old-resultant-name was specified, it is used to pass the string to the success 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 newly renamed file. If new-resultant-name was specified, it is used to pass the string to the success routine. Otherwise, a class S, type T string is passed. Any string class is supported.

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 success routine using the same passing mechanism that was used to pass it to LIB$RENAME_FILE.

Call Format for an Error Routine

The error routine returns a success/fail value that LIB$RENAME_FILE uses to determine whether or not more files will be processed if an error is encountered. The error routine is called only if the user-error-procedure argument was specified in the call to LIB$RENAME_FILE. If the user-error-procedure argument was not specified, the default is to continue processing.

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 and I64 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 and I64, 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 HP 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 


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 and I64 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.


Previous Next Contents Index