C$LIST-DIRECTORY Routine

The C$LIST-DIRECTORY routine lists the contents of a selected directory. Each operating system has a unique method for performing this task. C$LIST_DIRECTORY provides a single method that will work for all operating systems.

Usage

CALL "C$LIST-DIRECTORY" 
   USING OP-CODE, parameters

Parameters

OP-CODE PIC 99 COMP-X

Indicates which C$LIST-DIRECTORY operation to perform. The operations are described below.

OP-CODE parameters varies depending on the OP-CODE chosen.

Provides information and hold results for the operations specified. These parameters are described below.

Description

C$LIST-DIRECTORY allows you to get the names of files residing in a given directory. It accomplishes this through three distinct operations. The first operation opens the specified directory. The second operation returns the filenames in the list, one-at-a-time. The third operation closes the directory and deallocates all memory used by the routine. C$LIST-DIRECTORY has the following operation codes (defined in "acucobol.def"):

LISTDIR-OPEN (VALUE 1) Opens the specified directory. It has two parameters:

Directoryname PIC X(n) - contains the name of the directory to open. This directory must exist, and you must have permissions to read the directory. You may use remote name syntax if AcuServer is installed on the remote machine.

Pattern PIC X(n) - specifies the type of filename for which to search. This routine supports wildcards, meaning that the character "*" will match any number of characters, and the character "?" will match any single character. For example, you can search by file suffix (*.def) or by a common part of a file name (acu*).

If the call to LISTDIR-OPEN is successful, RETURN-CODE contains a handle to the list. The value in RETURN-CODE should be moved to a data item that is USAGE HANDLE. That data item should be passed as the directory handle to the other C$LIST-DIRECTORY operations. If the call to LISTDIR-OPEN fails, RETURN-CODE is set to a NULL handle.

LISTDIR-NEXT (VALUE 2) Reads each filename from the open directory. It has two parameters:

Handle USAGE HANDLE - is the handle returned in the LISTDIR-OPEN operation.

Filename PIC X(n) - is the location of the next filename to be returned. If the directory listing is finished, it is filled with spaces.

LISTDIR-CLOSE (VALUE 3) Releases the resources used by the other operations. It must be called to avoid memory leaks. It has one parameter, handle, which is the same data item used by the LISTDIR-NEXT operation.

Handle USAGE HANDLE - is the handle returned in the LISTDIR-OPEN operation.

Example

The following example lists the contents of a directory with repeated calls C$LIST-DIRECTORY:


WORKING-STORAGE SECTION.
copy "def/acucobol.def".
01  pattern       pic x(5) value "*.vbs".
01  directory     pic x(20) value "/virusscan".
01  filename      pic x(128).
01  mydir         usage handle.
PROCEDURE DIVISION.
MAIN.
* Call LISTDIR-OPEN to get a directory handle.
    call "C$LIST-DIRECTORY" using listdir-open, directory, pattern.
    move return-code to mydir.
    if mydir = 0
       stop run
    end-if.
* Call LISTDIR-NEXT to get the names of the files.  
* Repeat this operation until a filename containing only 
* spaces is returned.  The filenames are not necessarily 
* returned in any particular order.  Filenames may be 
* sorted on some machines and not on others.
    perform with test after until filename = spaces
       call "C$LIST-DIRECTORY" using listdir-next, mydir, filename
    end-perform.
* Call LISTDIR-CLOSE to close the directory and deallocate memory. 
* Omitting this call will result in memory leaks.
    call "C$LIST-DIRECTORY" using listdir-close, mydir.
    stop run.