9.205 STM_FILE_OPEN
注意: 9.1 組み込み関数の規則 &<a href="bifcat2_01.htm"&>利用オプション&</a&>
この組み込み関数によって、ストリーム・ファイルを開く、または作成します。オプションによって、ファイルを開くまたは作成する方法を制御します。関連する組み込み関数を使用して、ストリーム・ファイルからデータを読み取ったり、書き込んだりすることができます。
LANSA/ADで実行している場合、この組み込み関数を使用して、IBM i IFSファイルの読み取り/書き込みを実行することができます。
関連する組み込み関数：9.206 STM_FILE_READ 、9.207 STM_FILE_WRITE 、9.204 STM_FILE_CLOSE 、 9.208 STM_FILE_WRITE_CTL
引数
番号 |
タイプ |
必須/任意 |
記述 |
最小長 |
最大長 |
最小小数桁数 |
最大小数桁数 |
1 |
A |
必須 |
開くファイルのフル・パスとファイル名。 |
1 |
制限なし |
|
|
2 |
A |
任意 |
このストリーム・ファイルの処理に適用されるオプション。 |
1 |
制限なし |
|
|
3 |
A |
任意 |
IBM iでのみ使用。ファイル作成時に共通権限として設定する権限レベル |
1 |
1 |
|
|
4 |
A |
任意 |
バッファリング。このオプションは、書き込みまたは追加操作のためにファイルを開く場合のみ有効です。このオプションをNに設定した場合、BIFが戻る前にデータが永久ストレージに書き込まれます。 |
1 |
1 |
|
|
5 |
A |
任意 |
IBM i でのみ使用、ファイル作成時、ファイルの権限をユーザー・プロファイルから取得したグループ・プロファイル設定に設定します。 N= 適用しない Y = 適用する デフォルト値は N です。 |
1 |
1 |
|
|
戻り値
番号 |
タイプ |
必須/任意 |
記述 |
最小長 |
最大長 |
最小小数桁数 |
最大小数桁数 |
1 |
N |
必須 |
ファイル番号(ファイル・ハンドル) |
1 |
3 |
0 |
0 |
2 |
A |
任意 |
戻りコード |
2 |
2 |
|
|
技術上の注記
ファイルを開く時のオプション
注：IBM iのパス区切り記号は/ (スラッシュ)です。IBM iでは、\ (バック・スラッシュ)は使用できません。使用すると、アクセスできないファイルが作成されます。
オプション・グループ |
指定がない場合のデフォルト |
指定できるオプション値 |
注 |
ファイル・モード |
読み取り |
Read |
読み取るためにファイルを開きます。ファイルは存在する必要があります。 |
|
|
Write |
書き込むためにファイルを開きます。ファイルは存在しない場合、作成されます。ファイルが存在する場合、データ内容は上書きされます。 |
|
|
Append |
ファイルの最後に書き込むためにファイルを開きます。書き込みアクションによって、既存のファイルにデータが追加されます。ファイルは存在しない場合、作成さ れます。 |
データ・モード |
Text |
Text |
テキスト・ストリームとしてデータを読み取り/書き込みます。文字変換が行われます。データは、ジョブのコード・ページとファイルのコード・ページとの間で変換されます。 |
|
|
Binary |
バイナリー・ストリームとしてデータを読み取り/書き込みます。文字変換は行われません。データは、入力または出力時に変更されません。ファイルが Binaryモードで作成される場合、そのファイルはジョブのコード・ページで作成されます。 |
行書式 |
LineTerminator=LF |
LineTerminator=ALL |
読み取りファイルでのみ有効です。 |
|
|
LineTerminator=CR |
終了文字は、復帰(CR)です。 |
|
|
LineTerminator=CRLF |
終了文字は、復帰(CR)、改行(LF)です。 |
|
|
LineTerminator=LF |
終了文字は、改行(LF)です。 |
|
|
LineTerminator=NL |
終了文字は、改行(NL)です。 |
|
|
LineTerminator=LFCR |
終了文字は、改行(LF)、復帰(CR)です。 |
|
|
LineTerminator=NONE |
行終了文字は使用されません。 |
末尾ブランクの除去 |
デフォルトのアクションは、データ・ストリームに書き込まれる前にデータ・ブロックから末尾ブランクを除去します。 |
Notrim |
書き込みアクションによって提供されるデータ・ブロックから末尾ブランクを除去しません。 |
コード・ページ |
ファ イルが作成される場合、現在のジョブのコード・ページが使用されます。 |
CodePage=nnnnn |
Append モードで既存のファイルに書き込むために開くファイルでは、このオプションは無視されます。コード・ページの情報は、ファイルを作成する必要がある場合にだけ使用されます。 |
WindowsのTextモード処理
Textモードでは、行終了が0x0d0aのファイルを読み込むと、Windowsは0x0aを戻すだけです。これに合わせて、LineTerminator=LFまたはALLを指定する必要があります。
Textモードでは、ファイル書き込み時に0x0aがバッファにある場合、Windowsにより0x0dが出力されます。ですから、LFが指定されると、ファイルは0x0d0aを受け取ります。CRを指定すると、ファイルは0x0dを受け取ります。CRLFを指定の場合は、ファイルは0x0d0d0aを受け取ります。
Binaryモードの場合、0x0d0aは読み込み時に何も行われません。ですから、CRLFが正常に作動します。
ストリーム・ファイルの組み込み関数が、Windowsでファイルから別のファイルへのコピーに使用され、このファイルの行終了文字が0x0d0aの場合、CRLFは残ります。
- Textモード読み込み LineTerminator=LFまたはALL、Textモード書き込み LineTerminator=LF
- Binaryモード読み込み LineTerminator=CRLFまたはALL、Binaryモード書き込み LineTerminator=CRLF
また、読み込んだ行に戻り値OVがある時にフラグを立てる特別な処理が無い限り、書き込み時に余分な行が出力されます。読み込みバッファを最大長より長くするか、書き込み時にOV行処理をすると、行は再構成されます。
Binaryモードは予測可能なので、Textモードより便利です。LANSAが優先的に処理できるようOSに指示します。WindowsではTextモードでの文字変換はありません。ですから、これを使用する意味はほとんどありません。返って混乱を招くだけです。WindowsではBinaryモードを使用してください。そうすると、この組み込み関数でファイルにある通りのデータを受け取ることができ、指定した通りの出力ができます。
行終了マーカーはプラットフォームによって異なります。例えばWindowsでは0x0d0a、Linuxでは0x0d0aが使用されています。
WindowsでもLinuxでも、TextモードでLineTerminator=LFにすることは可能ですし、正常に作動します。
コード・ページの変換
IBM iプラットフォームで実行している場合、実行中のジョブのコード・ページとストリーム・ファイルのコード・ページとの間で変換が実行される可能性があります。ストリーム・ファイルのコード・ページは、ファイル作成時に設定されます。
Textモードでファイルからデータを読み取る場合、データは、ファイルのコード・ページからジョブのコード・ページに変換されます。Binaryモードでデータを読み取る場合、変換は行われません。
書き込み用にファイルを作成する場合、そのファイルは、STM_FILE_OPENで指定したコード・ページで作成されます。コード・ページが指定されていない場合、既存のジョブのコード・ページが省略値として使用されます。ファイルに書き込まれるテキスト・データは、ジョブのコード・ページからファイルのコード・ページに変換されます。Binaryモードで書き込まれるデータは変換されません。
Appendモードで既存のファイルに書き込むためにファイルを開く場合、既存のファイルのコード・ページは変更されません。
WindowsやLinuxでは、コード・ページ変換は行われません。Textモードでファイルからデータを読み取る場合、データは、現在のコード・ページが想定されます。UTF-8およびUTF-16のデータはサポートされません。
例
IBM i IFS上のストリーム・ファイルが開かれます。ストリーム・ファイルはディレクトリ/tmpにあり、ファイル名はupdphone.txtです。ファイルはテキストとして読み取られ、標準の行終了文字(CRLF、LFCR、CR、LF、NL)によって各行の終わりが示されます。ストリーム・ファイルの各行が読み取られ、その情報はデータベース・ファイルPSLMSTを更新するために使用されます。ストリーム・ファイルの最後に到達すると、そのファイルは閉じられます。
FUNCTION OPTIONS(*DIRECT) ********** DEFINE FIELD(#FILENO) TYPE(*DEC) LENGTH(3) DECIMALS(0) DESC('Allocated file number') DEFINE FIELD(#RETNCODE) TYPE(*CHAR) LENGTH(2) DEFINE FIELD(#COMMA) TYPE(*CHAR) LENGTH(1) DEFINE FIELD(#OPTIONS) TYPE(*CHAR) LENGTH(256) DESC('Options for stream file open') CHANGE FIELD(#OPTIONS) TO('''Read Text LineTerminator=ALL''') ********** USE BUILTIN(STM_FILE_OPEN) WITH_ARGS('''/tmp/updphone.txt''' #OPTIONS) TO_GET(#FILENO #RETNCODE) IF COND('#retncode *NE OK') MESSAGE MSGTXT('Error occurred on OPEN') RETURN ENDIF ********** ********** Read IFS file updphone.txt until end of file. ********** File contains update for employee phone numbers. ********** Each line of data contains EMPNO,PHONENO with ********** a line terminator of Carriage return line feed. ********** eg A0001,754310 ********** A1007,325 187 ********** DOUNTIL COND('#retncode = EF') USE BUILTIN(STM_FILE_READ) WITH_ARGS(#FILENO) TO_GET(#EMPNO #RETNCODE #COMMA #PHONEBUS) IF COND('#retncode *EQ ER') MESSAGE MSGTXT('Error reading stream file') RETURN ENDIF IF COND('#retncode *EQ OK') ********** update PSLMST with information from stream file UPDATE FIELDS((#PHONEBUS)) IN_FILE(PSLMST) WITH_KEY(#EMPNO) ENDIF ********** ENDUNTIL ********** ********** Close stream file and finish USE BUILTIN(STM_FILE_CLOSE) WITH_ARGS(#FILENO) MESSAGE MSGTXT('Phone numbers updated') RETURN