|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| 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.
| OpenVMS usage: | char_string |
| type: | character string |
| access: | write only |
| mechanism: | by descriptor |
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.
| OpenVMS usage: | context |
| type: | longword (unsigned) |
| access: | modify |
| mechanism: | by reference |
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.
This description is divided into three parts:
- Call Format for a Success Routine
- Call Format for an Error Routine
- Call Format for a Confirm Routine
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.
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.
The Reserve Event Flag routine allocates a local event flag number specified by event-flag-number.
LIB$RESERVE_EF event-flag-number
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$RESET_VM_ZONE zone-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$RESET_VM_ZONE_64 zone-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
SS$_NORMAL Routine successfully completed. LIB$_BADBLOADR An invalid zone-id argument.
| Previous | Next | Contents | Index |