 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$DEC_OVER
The Enable or Disable Decimal Overflow Detection routine enables or
disables decimal overflow detection for the calling routine activation.
The previous decimal overflow setting is returned.
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 available on OpenVMS Alpha and I64 systems in
translated form and is applicable to translated VAX images only.
Format
LIB$DEC_OVER new-setting
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword integer (unsigned) |
| access: |
write only |
| mechanism: |
by value |
The old decimal overflow enable setting (the previous contents of
SF$W_PSW[PSW$V_DV] in the caller's frame).
Argument
new-setting
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
New decimal overflow enable setting. The new-setting
argument is the address of an unsigned longword that contains the new
decimal overflow enable setting. Bit 0 set to 1 means enable; bit 0 set
to 0 means disable.
Description
The caller's stack frame is modified by this routine.
A call to LIB$DEC_OVER affects only the current routine activation and
does not affect any of its callers or any routines that it may call.
However, the setting does remain in effect for any routines that are
subsequently entered through a JSB entry point.
Example
|
DECOVF: ROUTINE OPTIONS (MAIN);
DECLARE LIB$DEC_OVER ENTRY (FIXED BINARY (7)) /* Address of byte for
/* enable/disable
/* setting */
RETURNS (FIXED BINARY (31)); /* Old setting */
DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY;
DECLARE RESULT FIXED BINARY (31);
DECLARE (A,B) FIXED DECIMAL (4,2);
ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow');
RESULT = LIB$DEC_OVER (DISABLE); /* Disable recognition of decimal
/* overflow in this block */
A = 99.99;
B = A + 2;
PUT SKIP LIST ('In MAIN');
BEGIN;
B = A + 2;
PUT LIST ('In BEGIN block');
CALL Q;
Q: ROUTINE;
B = A + 2;
PUT LIST ('In Q');
END Q;
END /* Begin */;
END DECOVF;
|
This PL/I program shows how to use LIB$DEC_OVER to enable or disable
the detection of decimal overflow. Note that in PL/I, disabling decimal
overflow using this routine causes the condition to be disabled only in
the current block; descendent blocks will enable the condition unless
this routine is called in each block.
LIB$DELETE_FILE
The Delete One or More Files routine deletes one or more files. The
specification of the files to be deleted may include wildcards.
LIB$DELETE_FILE is similar in function to the DCL command DELETE.
Format
LIB$DELETE_FILE filespec [,default-filespec] [,related-filespec]
[,user-success-procedure] [,user-error-procedure]
[,user-confirm-procedure] [,user-specified-argument] [,resultant-name]
[,file-scan-context] [,flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String containing the OpenVMS Record Management Services (RMS) file
specification of the files to be deleted. The filespec
argument is the address of a descriptor pointing to the file
specification. If the specification includes wildcards, each file that
matches the specification is deleted. If running on Alpha or I64 and
flag LIB$M_FIL_LONG_NAMES is set, the string must not contain more
characters than specified by NAML$C_MAXRSS, otherwise the string must
not contain more than 255 characters. Any string class is supported.
default-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Default file specification of the files to be deleted. The
default-filespec argument is the address of a
descriptor pointing to the default file specification. This is an
optional argument; if the argument is omitted, the default is the null
string. Any string class is supported.
See the OpenVMS Record Management Services Reference Manual for information about default file specifications.
related-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Related file specification of the files to be deleted. The
related-filespec argument is the address of a
descriptor pointing to the related file specification. Any string class
is supported. This is an optional argument; if the argument is omitted,
the default is the null string.
Input file parsing is used. See the OpenVMS Record Management Services Reference Manual for information on
related file specifications and input file parsing.
The related file specification is useful when you are processing lists
of file specifications. Unspecified portions of the file specification
are inherited from the last file processed.
user-success-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied success routine that LIB$DELETE_FILE calls after it
successfully deletes a file.
The success routine can be used to display a log of the files that were
deleted. For more information on the success routine, see Call Format for a Success Routine
in the Description section.
user-error-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied error routine that LIB$DELETE_FILE calls when it detects
an error.
The error routine returns a success/fail value that LIB$DELETE_FILE
uses to determine if more files should be processed. For more
information on the error routine, see Call Format for an Error Routine in the Description
section.
user-confirm-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied confirm routine that LIB$DELETE_FILE calls before each
file is deleted. The value returned by the confirm routine determines
whether or not the file will be deleted. The confirm routine can be
used to select specific files for deletion based on criteria such as
expiration date, size, and so on. For more information about the
confirm routine, see Call Format for a Confirm Routine in the Description section.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
User-supplied argument that LIB$DELETE_FILE passes to the error,
success, and confirm routines each time they are called. Whatever
mechanism is used to pass user-specified-argument to
LIB$DELETE_FILE is also used to pass it to the routines. This is an
optional argument; if the argument is omitted, zero is passed by value.
resultant-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String into which LIB$DELETE_FILE writes the RMS resultant file
specification of the last file processed. The
resultant-name argument is the address of a descriptor
pointing to the resultant name.
If present, resultant-name is used to store the file
specification passed to the user-supplied routines, instead of a
default class S, type T string. Therefore, this argument should be
specified when the user-supplied routines are used and those routines
require a descriptor type other than class S, type T. Any string class
is supported.
If you specify one or more of the user-supplied action routines, the
descriptor used to pass resultant-name must be:
- Of the same class as the descriptor required by the
filespec argument of any action routines. 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.
- (Alpha and I64 only) Of the same form as the descriptor required
by the filespec argument of all action routines. For
example, if the filespec argument of an action routine
uses a 64-bit descriptor, then the resultant-name
argument must also use a 64-bit descriptor.
file-scan-context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context for deleting a list of file specifications. The
file-scan-context argument is the address of a
longword containing the context value.
You must initialize the file scan context to zero before the first of a
series of calls to LIB$DELETE_FILE. LIB$FILE_SCAN uses this context to
retain the file context for multiple input files. You must specify this
context only when you are dealing with multiple input files, as the DCL
command DELETE does. You may deallocate the context allocated by
LIB$FILE_SCAN by calling LIB$FILE_SCAN_END after all calls to
LIB$DELETE_FILE have been completed.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User flags. The flags argument is the address of an
unsigned longword containing the user flags.
The flag bits and their corresponding symbols are described in the
following table:
| Bit |
Symbol |
Description |
|
0
|
|
Reserved to HP.
|
|
1
|
|
Reserved to HP.
|
|
2
|
LIB$M_FIL_LONG_NAMES
|
(Alpha or I64 only) If set, LIB$DELETE_FILE can process file names with
a maximum length of NAML$C_MAXRSS. If clear, LIB$DELETE_FILE can
process file specifications with a maximum length of 255 (default).
|
Description
This Description section is divided into the following parts:
Call Format for a Success Routine
The success routine is called only if the
user-success-procedure argument was specified in the
LIB$DELETE_FILE argument list.
The calling format of a success routine is as follows:
user-success-procedure filespec [,user-specified-argument]
|
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
RMS resultant file specification of the file being deleted. The
filespec argument is the address of a descriptor
pointing to the file specification. If the
resultant-name argument 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.
On Alpha and I64 systems, the descriptor specified by each of the
action routines for the filespec argument and the
descriptor specified by the LIB$DELETE_FILE
resultant-name argument, if any, must be of the same
form. They must all be 32-bit descriptors or all 64-bit descriptors. If
you do not specify a resultant-name argument, then the
filespec argument must use a 32-bit descriptor.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
unspecified |
Value of user-specified-argument passed by
LIB$DELETE_FILE to the success routine. The same passing mechanism that
was used to pass user-specified-argument to
LIB$DELETE_FILE is used by LIB$DELETE_FILE to pass
user-specified-argument to the success routine. This
is an optional argument.
Call Format for an Error Routine
The error routine is called only if the
user-error-procedure argument was specified in the
LIB$DELETE_FILE argument list.
The calling format of an error routine is as follows:
user-error-procedure filespec ,rms-sts ,rms-stv ,error-source
[,user-specified-argument]
|
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String containing the RMS resultant file specification of the file
being deleted. If 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.
On Alpha and I64 systems, the descriptor specified by each of the
action routines for the filespec argument and the
descriptor specified by the LIB$DELETE_FILE
resultant-name argument, if any, must be of the same
form. They must all be 32-bit descriptors or all 64-bit descriptors. If
you specify no resultant-name argument, then the
filespec argument must use a 32-bit descriptor.
rms-sts
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Primary condition code (FAB$L_STS) that describes the error that
occurred. The rms-sts argument is the address of an
unsigned longword that contains the primary condition code.
rms-stv
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Secondary condition code (FAB$L_STV) that describes the error that
occurred. The rms-stv argument is the address of an
unsigned longword that contains the secondary condition code.
error-source
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Integer code that indicates the point at which the error was found. The
error-source argument is the address of a longword
integer containing the code of the error source.
Possible values for the error code are as follows:
|
0
|
Error searching for file specification
|
|
1
|
Error deleting file
|
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
unspecified |
Value passed to LIB$DELETE_FILE that is then passed to
user-error-procedure using the same passing mechanism
that was used to pass it to LIB$DELETE_FILE. This is an optional
argument.
If the error routine returns a success status (bit 0 set), then
LIB$DELETE_FILE continues processing files. If a failure status (bit 0
clear) is returned, then processing ceases immediately, and
LIB$DELETE_FILE returns with the error status.
If the user-error-procedure argument is not specified,
LIB$DELETE_FILE returns to its caller the most severe error status
encountered while deleting 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 confirm routine is called only if the
user-confirm-procedure argument was specified in the
call to LIB$DELETE_FILE.
The calling format of the confirm routine is as follows:
user-confirm-procedure filespec ,fab [,user-specified-argument]
|
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
RMS resultant file specification of the file to be deleted. The
filespec argument is the address of a descriptor
pointing to the file specification.
If 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.
On Alpha and I64 systems, the descriptor specified by each of the
action routines for the filespec argument and the
descriptor specified by the LIB$DELETE_FILE
resultant-name argument, if any, must be of the same
form. They must all be 32-bit descriptors or all 64-bit descriptors. If
you do not specify a resultant-name argument, then the
filespec argument must use a 32-bit descriptor.
fab
| OpenVMS usage: |
fab |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
RMS file access block (FAB) that describes the file being deleted. Your
program may perform an RMS $OPEN on the FAB to obtain file attributes
to determine whether the file should be deleted, but it must close the
file with $CLOSE before returning to LIB$DELETE_FILE.
On Alpha and I64 systems, 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 names 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: |
unspecified |
| access: |
read only |
| mechanism: |
unspecified |
The value of the user-specified-argument argument that
LIB$DELETE_FILE passes to the confirm routine using the same passing
mechanism that was used to pass it to LIB$DELETE_FILE. This is an
optional argument.
If confirm routine returns a success status (bit 0 set), the file is
then deleted; otherwise, the file is not deleted.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_ERRROUCAL
|
Success, but an error routine was 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.
Filespec or
default-filespec is longer than 4095 characters.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. The descriptor for a string argument was not
a valid string descriptor.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments. An incorrect number of arguments was passed
to LIB$DELETE_FILE.
|
Any condition value returned by LIB$SCOPY_xxx except those
condition values specifying truncation errors.
Any condition value returned by RMS. If
user-error-procedure is not specified, this is the
most severe of the RMS errors encountered while deleting the files.
Example
|
PROGRAM DELETE_EXAMPLE(INPUT, OUTPUT);
{+}
{ Declare external function LIB$DELETE_FILE. Throughout this
{ example, the user-arg argument is not used.
{-}
FUNCTION LIB$DELETE_FILE(
FILESPEC: VARYING [A] OF CHAR;
DEFAULT_FILESPEC: VARYING [B] OF CHAR;
REL_FILESPEC : VARYING [D] OF CHAR;
%IMMED [UNBOUND] ROUTINE SUCCESS_ROUTINE
(FILESPEC : VARYING [A] OF CHAR) := %IMMED 0;
%IMMED [UNBOUND] FUNCTION ERROR_ROUTINE
(FILESPEC : VARYING [A] OF CHAR; RMS_STS, RMS_STV : INTEGER)
: BOOLEAN := %IMMED 0;
%IMMED [UNBOUND] FUNCTION CONFIRM_ROUTINE
(FILESPEC: VARYING [A] OF CHAR): BOOLEAN := %IMMED 0;
VAR USER_ARG : [UNSAFE] INTEGER := %IMMED 0;
VAR RESULT_NAME : VARYING [C] OF CHAR := %IMMED 0
) : INTEGER; EXTERN;
{+}
{ Declare a routine which will display the names of the files
{ as they are deleted.
{-}
ROUTINE LOG_ROUTINE(FILESPEC : VARYING [A] OF CHAR);
BEGIN
WRITELN('File ', FILESPEC, ' successfully deleted');
END;
{+}
{ Declare a routine which will notify the user that an error
{ occurred.
{-}
FUNCTION ERR_ROUTINE(FILESPEC: VARYING [A] OF CHAR;
RMS_STS, RMS_STV: INTEGER): BOOLEAN;
BEGIN
WRITELN('Delete of ', FILESPEC, ' failed ', HEX(RMS_STS));
ERR_ROUTINE := TRUE;
END;
{+}
{ Declare a routine which checks to see if the file should be
{ deleted. If the filename contains the string 'XYZ', then it is
{ deleted.
{-}
FUNCTION CONFIRM_ROUTINE( FILESPEC: VARYING [A] OF CHAR): BOOLEAN;
BEGIN
IF INDEX(FILESPEC, 'XYZ') <> 0
THEN
CONFIRM_ROUTINE := TRUE
ELSE
CONFIRM_ROUTINE := FALSE;
END;
{+}
{ The main program begins here.
{-}
VAR
FILES_TO_DELETE, RESULTANT_NAME : VARYING [255] OF CHAR;
RET_STATUS : INTEGER;
BEGIN
WRITE ('Files to delete: ');
READLN(FILES_TO_DELETE);
RET_STATUS := LIB$DELETE_FILE(
FILES_TO_DELETE, '*;', '', LOG_ROUTINE, ERR_ROUTINE,
CONFIRM_ROUTINE,,RESULTANT_NAME);
IF NOT ODD(RET_STATUS)
THEN
WRITELN('Delete failed. The error was ', HEX(RET_STATUS));
END.
|
This Pascal program prompts the user for file specifications of files
to be deleted. Of those, it deletes only files that contain the string
XYZ somewhere in their resultant file specification. The names of
deleted files are displayed.
|
