現在地: LANSA テクニカル リファレンスガイド > 9. 組み込み関数 > 9.205 STM_FILE_OPEN

9.205 STM_FILE_OPEN

注意: 9.1 組み込み関数の規則      利用オプション

この組み込み関数によって、ストリーム・ファイルを開く、または作成します。オプションによって、ファイルを開くまたは作成する方法を制御します。関連する組み込み関数を使用して、ストリーム・ファイルからデータを読み取ったり、書き込んだりすることができます。

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

必須

開くファイルのフル・パスとファイル名。

例えば/mydir/myfile.txt などです。「ファイルを開く時のオプション 」を参照してください。

読み取るためにファイルを開く場合、ファイルは存在する必要があります。書き込むためにファイルを開く場合、ファイルは存在しない場合作成されます。

1

制限なし

 

 

2

A

任意

このストリーム・ファイルの処理に適用されるオプション。

複数のオプションを指定することができます。

オプションは、1つ以上のブランク文字で区切る必要があります。

詳細については、下記の「技術上の注記 」を参照してください。

使用可能なオプション：
Read
Write
Append

Text
Binary

LineTerminator=aaaaa
LineTerminator=LF

NoTrim

CodePage=nnnnn

1

制限なし

 

 

3

A

任意

IBM iでのみ使用。ファイル作成時に共通権限として設定する権限レベル

N = NONE (権限は設定されない)

A = ALL (権限をRWXに設定)

R = READUSE (権限をRXに設定)

デフォルト値はRです。

1

1

 

 

4

A

任意

バッファリング。このオプションは、書き込みまたは追加操作のためにファイルを開く場合のみ有効です。このオプションをNに設定した場合、BIFが戻る前にデータが永久ストレージに書き込まれます。

Y = バッファリング

N = バッファリングなし

デフォルト値はYです。

1

1

 

 

5

A

任意

IBM i でのみ使用、ファイル作成時、ファイルの権限をユーザー・プロファイルから取得したグループ・プロファイル設定に設定します。
N= 適用しない
Y = 適用する
デフォルト値は N です。

1

1

 

 

 

戻り値

番号

タイプ

必須/任意

記述

最小長

最大長

最小小数桁数

最大小数桁数

1

N

必須

ファイル番号(ファイル・ハンドル)

ファイルが開かれたときに一意のファイル番号がこのファイルに割り当てられ、この値で戻されます。このファイル番号は、このファイルに対してアクションを実行するときに使用する必要があります。例えば、STM_FILE_READを使用してこのファイルからデータを読み取る場合、このファイル番号を指定する必要があります。

最大256個のファイルをいつでも開くことができ、該当するファイル番号を指定することによって、このファイルのいずれかを処理することができます。

1

3

0

0

2

A

任意

戻りコード

OK = ファイルが開かれ、ファイル番号が割り当てられた

ER = ファイルを開くときにエラーが発生した。詳細については、メッセージを参照してください。

2

2

 

 

 

技術上の注記

ファイルを開く時のオプション

注：IBM iのパス区切り記号は/ (スラッシュ)です。IBM iでは、\ (バック・スラッシュ)は使用できません。使用すると、アクセスできないファイルが作成されます。

オプション・グループ

指定がない場合のデフォルト

指定できるオプション値

注

ファイル・モード

読み取り

Read

読み取るためにファイルを開きます。ファイルは存在する必要があります。

Write

書き込むためにファイルを開きます。ファイルは存在しない場合、作成されます。ファイルが存在する場合、データ内容は上書きされます。

Append

ファイルの最後に書き込むためにファイルを開きます。書き込みアクションによって、既存のファイルにデータが追加されます。ファイルは存在しない場合、作成さ れます。

データ・モード

Text

Text

テキスト・ストリームとしてデータを読み取り/書き込みます。文字変換が行われます。データは、ジョブのコード・ページとファイルのコード・ページとの間で変換されます。

Binary

バイナリー・ストリームとしてデータを読み取り/書き込みます。文字変換は行われません。データは、入力または出力時に変更されません。ファイルが Binaryモードで作成される場合、そのファイルはジョブのコード・ページで作成されます。

行書式

このオプションによって、行を終了する文字を指定することができます。

ファイルを読み取る場合、この文字が検索され、終了文字までのデータが各読み取りアクションによって戻されます。終了文字は戻されません。

ファイルに書き込む場合、行終了文字は、各書き込みアクションによってデータの最後に追加されます。

LineTerminator=LF

LineTerminator=ALL

デフォルト=LT

読み取りファイルでのみ有効です。

行終了文字(CR、CRLF、LF、NL、LFCR)のいずれかを使用して、行の終わりを示します。

LineTerminator=CR

終了文字は、復帰(CR)です。

LineTerminator=CRLF

詳細は｢WindowsのTextモード処理」を参照してください。

終了文字は、復帰(CR)、改行(LF)です。

LineTerminator=LF

詳細は｢WindowsのTextモード処理」を参照してください。

終了文字は、改行(LF)です。

LineTerminator=NL

終了文字は、改行(NL)です。

LineTerminator=LFCR

詳細は｢WindowsのTextモード処理｣を参照してください。

終了文字は、改行(LF)、復帰(CR)です。

LineTerminator=NONE

読み込みが終了して、書き込む前に、行の終わりの全ての行終了文字(LT)が削除されます。行の終わりとは、BIFが行終了として認識する位置であり、ファイル行の終わりではありません。ファイルと一致しないLTが選択された場合、行の終わりにならないので、LTは削除されません。出力も同様です。BIFにより書きだされた各行の終わりからのみ、LTが削除されます。

行終了文字は使用されません。

末尾ブランクの除去

このオプションは、書き込まれるファイルに使用することができ、書き込みアクションによって提供されるデータ・ブロックから末尾ブランクを除去するかどうかを制御します。

デフォルトのアクションは、データ・ストリームに書き込まれる前にデータ・ブロックから末尾ブランクを除去します。

Notrim

書き込みアクションによって提供されるデータ・ブロックから末尾ブランクを除去しません。

コード・ページ

このオプションは、ファイル作成時に使用します。IBM i IFSで作成されるファイルは、指定のコード・ページとして作成されます。

IBM i以外のプラットフォームで実行している場合、このオプションは無視されます。

ファ イルが作成される場合、現在のジョブのコード・ページが使用されます。

CodePage=nnnnn

ここで、nnnnnは必要なコード・ページを指します。

注： 通常、英語のIBM i IFSファイルには、CodePage=00819を使用します。

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は残ります。

また、読み込んだ行に戻り値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