9.228 STM_FILE_OPEN
Þ Note: Built-In Function Rules.
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.
When executing in LANSA for i, these Built-In functions may be used to read and write to IBM i IFS files.
Related Built-In Functions: 9.229 STM_FILE_READ, 9.230 STM_FILE_WRITE, 9.227 STM_FILE_CLOSE and 9.231 STM_FILE_WRITE_CTL.
For use with
|
Arguments
|
Return Values
|
Note: IBM i path separator is / (forward slash). \ (back slash) is not acceptable in IBM i. It will create an unreachable file.
|
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
In Text mode, when writing a file, 0x0d is output by Windows if 0x0a is in the buffer. Thus when LF is specified, the file gets 0x0d0a. When CR is specified file gets 0x0d. When CRLF is specified file gets 0x0d0d0a.
In Binary mode the 0x0d0a is read intact. Thus CRLF works.
When the stream file Built-In Functions are used to copy from one file to another and the line termination in the file is 0x0d0a on Windows, these combinations preserve the CRLF:
- Read Text mode, LineTerminator=LF or ALL, Write Text Mode, LineTerminator=LF
- Read Binary mode, LineTerminator=CRLF or ALL, Write Binary Mode, LineTerminator=CRLF
Also, unless there is special processing for flagging that reading a line has returned OV, extra lines will be output when writing. Either make your read buffer greater than the maximum length or handle the OV lines when writing so that the line is re-constituted.
Binary mode is more portable than text mode because it is entirely predictable. It tells the OS to get out of the way and let LANSA handle it. On Windows there is no character conversion in text mode so there is very little reason to use it—it only causes confusion. Use Binary on Windows. You know that the Built-In Function will receive your data exactly as you see it in the file and will output it exactly as you specify it.
End of Line markers vary from platform to platform. Windows uses 0x0d0a and Linux uses 0x0a.
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.
When reading data from a file in text mode, the data is converted from the file's code page to the job's code page. When reading data in binary mode, no conversion is done.
When a file is created for writing, it will be created with the code page specified on the STM_FILE_OPEN. If no code page was provided, it will default to the code page of the executing job. Text data written to a file will be converted from the code page of the job to the code page of the file. Data written in Binary mode will not be converted.
If a file is opened for writing in Append mode to an existing file, the code page of the existing file remains unchanged.
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
**********
********** 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