 |
HP OpenVMS RTL Library (LIB$) Manual
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:
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.
|
|
