C$LIST-DIRECTORY

C$LIST-DIRECTORY ルーチンは、選択したディレクトリの内容をリストします。各オペレーティングシステムには、このタスクを実行するための固有のメソッドが用意されています。C$LIST-DIRECTORY には、すべてのオペレーティングシステムで機能する単一のメソッドが用意されています。

注: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

使用法

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

パラメーター

OP-CODE PIC 99 COMP-X

どの C$LIST-DIRECTORY 操作を実行するかを示します。操作については、以降の説明を参照してください。

パラメーターは、選択する op-code に応じて異なります。

パラメーターは情報を提供し、指定した op-code の結果を保持します。これらのパラメーターについては、以降の説明を参照してください。

説明

C$LIST-DIRECTORY を使用すると、指定したディレクトリにあるファイルの名前を取得できます。この処理は、3 段階の操作で実行します。最初の操作では、指定したディレクトリを開きます。2 番目の操作では、リスト内のファイル名を一度に 1 つずつ返します。3 番目の操作では、ディレクトリを閉じて、ルーチンが使用したメモリ割り当てをすべて解除します。C$LIST-DIRECTORY には、次の操作コードが含まれます (acucobol.def で定義)。

LISTDIR-OPEN (VALUE 1)

指定したディレクトリを開きます。この操作では、次の 2 つのパラメーターを取ります。

Directoryname PIC X(n)

開くディレクトリの名前を含みます。このディレクトリは事前に作成しておき、そのディレクトリを読み取る権限を持っている必要があります。リモートマシンに AcuServer がインストールされている場合は、リモート名構文を使用できます。シンクライアントをサポートする「@[DISPLAY]:」を使用できます。次に例を示します。

C$LIST-DIRECTORY using listdir-open, 
"@[DISPLAY]:C:\path", pattern

Pattern PIC X(n)

検索対象のファイル名のタイプを指定します。このルーチンは「ワイルドカード」をサポートしており、文字「*」は任意の文字数に一致し、文字「?」は任意の 1 文字に一致します。たとえば、ファイルサフィックスで検索したり (*.def)、ファイル名の共通部分で検索したり (acu*) できます。

LISTDIR-OPEN の呼び出しが成功すると、RETURN-CODE にリストへのハンドルが含まれます。RETURN-CODE の値は、データ項目 USAGE HANDLE に転記する必要があります。このデータ項目はディレクトリハンドルとして他の C$LISTDIRECTORY の操作に渡す必要があります。LISTDIR-OPEN の呼び出しが失敗した場合 (ディレクトリが存在しない、ディレクトリにファイルがない、またはディレクトリの読み取り権限がない場合)、RETURN-CODE は NULL ハンドルに設定されます。

LISTDIR-NEXT (VALUE 2)

開いたディレクトリから各ファイル名を読み取ります。この操作では、次の 2 つのパラメーターを取ります。

Handle USAGE HANDLE: LISTDIR-OPEN 操作で返されるハンドル。
Filename PIC X(n): 次に返されるファイル名の場所。ディレクトリのリストが終わると、スペースで埋められます。

LISTDIR-NEXT の呼び出しには、追加引数 LISTDIR-FILE-INFORMATION (「acucobol.def」で定義) を含められます。この引数は返されるファイル名についての情報を受け取ります。これはオプションのグループ項目で、次のデータ項目についての情報を返します。

LISTDIR-FILE-TYPE: このファイルタイプは、次のいずれかになります。
B = ブロックデバイス C = 文字デバイス D = ディレクトリ F = 通常のファイル P = パイプ (FIFO) S = ソケット U = 不明
LISTDIR-FILE-CREATION-TIME: この作成日時は、ファイルが当初作成された日付 (および時刻) です。
LISTDIR-FILE-LAST-ACCESS-TIME: この最終アクセス日時は、いずれかのアプリケーションがファイルに最後にアクセスした日付 (および時刻) です。通常は何らかの方法でファイルにクエリを行った日時です。
LISTDIR-FILE-LAST-MODIFICATION-TIME: この最終更新日時は、ファイルに最後に書き込みをした日付 (および時刻) です。
LISTDIR-FILE-SIZE: これはファイルのサイズで、単位はバイトです。

LISTDIR-CLOSE (VALUE 3): 他の操作が使用しているリソースを解放します。メモリリークを避けるために呼び出す必要があります。この操作には 1 つのパラメーターとしてハンドルが含まれており、これは LISTDIR-NEXT 操作で使用されるものと同じデータ項目です。
ハンドル USAGE HANDLE: LISTDIR-OPEN 操作で返されるハンドル。

注: サポートされるファイルの形式はオペレーティングシステムによって異なるため、上記のデータ項目の意味はオペレーティングシステムに応じて若干異なります。これらの値をサポートするオペレーティングシステムであっても、ファイルシステムによってはサポートしない場合があります。UNIX® オペレーティングシステムの一部のバージョンでは、権限が変更されるとこれらの値が変更される場合があります。個別の規定については、使用しているオペレーティングシステムのドキュメントを参照してください。

例

次の例では、C$LISTDIRECTORY の呼び出しを繰り返し使用し、ディレクトリの内容をリストします。

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.

互換性の問題

このライブラリルーチンを使用する際には、DIALECT"ACU" コンパイラ指令を使用してコンパイルする必要があります。
「@[DISPLAY]」はこの COBOL システムではサポートされていません。