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 操作を実行するかを示します。操作については、以降の説明を参照してください。
注: シンクライアントの場合、ディスプレイホスト上の現在のディレクトリを基準とした相対ディレクトリで操作する場合、パス名は @[DISPLAY}:.\ で始める必要があります。.\ を省略すると、TEMP ユーザー環境変数で識別されるパス名に相対的なディレクトリで操作されます。
パラメーター: パラメーターは、選択する 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 システムではサポートされていません。
オプションの LISTDIR-FILE-INFORMATION グループ項目では、フィールド LISTDIR-FILE-CREATION-TIME および LISTDIR-FILE-LAST-ACCESS-TIME はゼロのみを返します。