C$LIST-DIRECTORY

C$LIST-DIRECTORY ルーチンは、選択したディレクトリの内容を表示します。各オペレーティング・システムには、このタスクを実行するための一意のメソッドが含まれています。C$LIST-DIRECTORY には、すべてのオペレーティング・システムで機能する単一のメソッドが含まれています。
注:この ACUCOBOL-GT ライブラリ・ルーチンはこの COBOL バージョンで利用できます。この COBOL システムの互換性の問題については、トピックの終わりにある「互換性の問題」節に示されています。

使用法

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 システムではサポートされていません。
  • オプションの LISTDIR-FILE-INFORMATION グループ項目で、フィールド LISTDIR-FILE-CREATION-TIME と LISTDIR-FILE-LAST-ACCESS-TIME はゼロのみを返します。