Page History
9.205 STM_FILE_OPEN
| Note |
|---|
| Note: Built-In Function Rules Usage Options |
This Built-In function opens or creates a stream file. Options control how the file is opened or created. Associated Built-In Functions may be used to read or write data to the stream file.
...
Related Built-In Functions: 9.206 STM_FILE_READ, 9.207 STM_FILE_WRITE, 9.204 STM_FILE_CLOSE , and 9.208 STM_FILE_WRITE_CTL.
Arguments
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | A | Req | Full path and file name of the file to be opened. eg /mydir/myfile.txt. See File Open Options following. If the file is opened for read, the file must exist. If the file is opened for write or append, the file will be created if it does not exist. | 1 | Unlimited | ||
2 | A | Opt | Options that are to be applied to handling of this stream file. Multiple options may be specified. Options must be separated by at least one blank character. Refer to Technical Notes for details. Possible options: Text LineTerminator=aaaaa NoTrim CodePage=nnnnn | 1 | Unlimited | ||
3 | A | Opt | Used on IBM i only: Authority level to set the public authorities when a file is created. | 1 | 1 | ||
4 | A | Opt | Buffering. This option is only valid if the file is opened for a Write or Append operation. If this option is set to N, data will be written to permanent storage before the BIF returns. Y = Buffering. N = No buffering. Default value is Y | 1 | 1 | ||
5 | A | Opt | Used on IBM i only: When a file is created, set the file authorities to the Group Profile settings obtained from the User Profile. | 1 | 1 |
Return Values
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | N | Req | File number (file handle) A unique file number is allocated to this file when opened and returned in this value. This file number must be used when further actions are made against this file. For example when data is to be read from this file using STM_FILE_READ this file number must be provided. Up to 256 files may be opened at any time. Any of these files may be processed by providing the appropriate file number. | 1 | 3 | 0 | 0 |
2 | A | Opt | Return Code OK = File has been opened and file number allocated. ER = Error occurred on the file open. Refer to messages for details. | 2 | 2 |
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Note |
|---|
| Note: IBM i path separator is / (forward slash). \ (back slash) is not acceptable in IBM i. It will create an unreachable file. |
Option group | Default value if not specified | Option values which may be specified | Notes |
|---|---|---|---|
File mode | Read | Read | The file will be opened for read. The file must exist. |
Write | The file will be opened for write. If the file does not exist it will be created. If the file does exist the data contents will be overwritten. | ||
Append | The file will be opened for write at the end of the file. Write actions will append the data to the existing file. If the file does not exist it will be created. | ||
Data mode | Text | Text | Data is read/written as a text stream. Character conversion is done. The data will be converted between the code page of the job and the code page of the file. |
Binary | Data is read/written as a binary stream. No character conversion is done. The data is not altered on input or output. If a file is created in Binary mode, it will be created with the code page of the job. | ||
Line format This option enables you to specify the line terminating character/s. On read files, this character is searched for and data up to the terminator returned by each read action. The terminator character/s is/are not returned. On files being written the line terminator is added to the end of the data on each write action. | LineTerminator=LF | LineTerminator=ALL Default=LF | Valid on READ files only. Any of the line terminators (CR, CRLF, LF, NL or LFCR) will be used to indicate the end of a line. |
LineTerminator=CR | Terminator character is Carriage Return | ||
LineTerminator=CRLF | Terminator characters are Carriage Return, Line Feed | ||
LineTerminator=LF | Terminator character is Line Feed | ||
LineTerminator=NL | Terminator character is New Line | ||
LineTerminator=LFCR | Terminator characters are Line Feed, Carriage Return | ||
LineTerminator=NONE All line terminators (LT) are stripped off the ends of lines after reading and before writing. The end of line is what the BIF has recognised as an end of line, not the file's end of line. If an LT is chosen that does not match the file, then no LTs will be stripped because they are not at the end of the line. Similarly on output. Each line that is written out by the BIF will have LT stripped from the end only. | No line terminator characters are used. | ||
Trim trailing blanks This option may be used for files being written and controls the trimming of trailing blanks from Data Blocks provided to the write action. | The default action is to trim trailing blanks from Data Blocks before writing to the data stream. | Notrim | Trailing blanks will not be trimmed from Data Blocks provided on the write action. |
Code page This option is used when files are created . Files created on IBM i IFS will be created as the specified code page. This option is ignored when executing on a non IBM i platform. | The code page of the current job is used if a file is created. | CodePage=nnnnn where nnnnn is the code page required. Note: CodePage=00819 is usual for English IBM i IFS files. | This option will be ignored by a file opened for writing in Append mode to an existing file. The code page information is used only if the file needs to be created. |
| Anchor | ||||
|---|---|---|---|---|
|
Text mode, when reading a file with 0x0d0a line termination Windows only returns 0x0a. To match this you need to specify LineTerminator=LF or ALL
...
Its probable that using Text mode and LineTerminator=LF for both Windows and Linux would also work.
Code page conversion
When executing on an IBM i platform, conversion between the code page of the executing job and the code page of the stream file may occur. The code page of the stream file is established when the file is created.
...
On Windows and Linux, no code page conversion occurs. When reading data from a file in text mode, the data is assumed to be in the current code page. Data in UTF-8 and UTF-16 is not supported.
Example
A stream file on the IBM i IFS is opened. The stream file is in directory /tmp and named updphone.txt . The file is to be read as text and any of the standard line terminators (CRLF, LFCR, CR, LF, NL) indicates the end of each line. Each line of the stream file is read and the information used to update database file PSLMST. When the end of the stream file is encountered, it is closed.
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
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
...
RETURN
ENDIF
IF COND('#retncode *EQ OK')
...
********** update PSLMST with information from stream
...
file
UPDATE FIELDS((#PHONEBUS)) IN_FILE(PSLMST) WITH_KEY(#EMPNO)
ENDIF
ENDIF
**********
...
ENDUNTIL
ENDUNTIL
**********
...
********** Close stream file and
...
finish
USE BUILTIN(STM_FILE_CLOSE) WITH_ARGS(#FILENO)
...
MESSAGE MSGTXT('Phone numbers updated')
...
RETURN