VMS Help RTL Routines, LIB$, LIB$DELETE_FILE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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
    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 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 Compaq.
    1                       Reserved to Compaq.
    2    LIB$M_FIL_LONG_    (Alpha only) If set, LIB$DELETE_FILE can
         NAMES              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).