9.205 STM_FILE_OPEN

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.

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.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:
Read
Write
Append

Text
Binary

LineTerminator=aaaaa
LineTerminator=LF

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.
N=NONE no authorities set
A=ALL set authority to RWX
R=READUSE set authority to RX
Default value is R

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.
N= Not apply
Y- Apply
Defaul value is N.

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

 

 

 

Technical Notes

File Open Options

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

See Windows Text Mode Handling

Terminator characters are Carriage Return, Line Feed

LineTerminator=LF

See Windows Text Mode Handling

Terminator character is Line Feed

LineTerminator=NL

Terminator character is New Line

LineTerminator=LFCR

See Windows Text Mode Handling

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.

 

Windows Text Mode Handling

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:

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