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]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2 – 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.
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.
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.
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:
o 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.
o (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 VSI.
1 Reserved to VSI.
2 LIB$M_FIL_LONG_ (Alpha or I64 only) If set, LIB$DELETE_
NAMES 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).