The _Ropen() function opens the record file specified by filename according
to the mode parameter, which may be followed by optional
parameters, if the varparm keyword parameter is specified
in the mode parameter. The open mode and keyword parameters
may be separated by a comma and one or more spaces. The _Ropen() function
does not dynamically create database files for you. All of the files
you refer to in the _Ropen() function must exist, or the open operation
will fail.
Files that are opened by the _Ropen() function are closed implicitly
when the activation group they are opened in, is ended. If a pointer
to a file opened in one activation group is passed to another activation
group and the opening activation group is ended, the file pointer
will no longer be valid.
The _Ropen() function applies to all types of files. The filename variable
is any valid i5/OS system file name.
The mode parameter specifies the type of access that is
requested for the file. It contains an open mode that is followed
by optional keyword parameters. The mode parameter may be
one of the following values:
Mode
Description
rr
Open an existing file for reading records.
wr
Open an existing file for writing records. If the file contains
data, the content is cleared unless the file is a logical file.
ar
Open an existing file for writing records to the end of the
file (append).
rr+
Open an existing file for reading, writing or updating records.
wr+
Open an existing file for reading, writing or updating records.
If the file contains data, the content is cleared unless the file
is a logical file.
ar+
Open an existing file for reading and writing records. All data
is written to the end of the file.
The mode may be followed by any of the following keyword
parameters:
Keyword
Description
arrseq=value
Where value can be:
Y
Specifies that the file is processed in arrival sequence.
N
Specifies that the file is processed using the access path that
is used when the file was created. This is the default.
blkrcd=value
Where value can be:
Y
Performs record blocking. The i5/OS operating
system determines the most efficient block size for you. This parameter
is valid for database, DDM, diskette and tape files. It is only valid
for files opened for input-only or output-only (modes rr, wr, or ar).
N
Does not perform record blocking. This is the default.
ccsid=value
Specifies the CCSID that is used for translation of the file.
The default is 0 which indicates that the job CCSID is used.
commit=value
Where value can be:
Y
Specifies that the database file is opened under commitment
control. Commitment control must have been set up prior to this.
N
Specifies that the database file is not opened under commitment
control. This is the default.
dupkey=value
value can be:
Y
Duplicate key values will be flagged in the _RIOFB_T structure.
N
Duplicate key values will not be flagged. This is the default.
indicators=value
Indicators are valid for printer, display, and ICF files. value can
be:
Y
The indicators that are associated with the file are returned
in a separate indicator area instead of in the I/O buffers.
N
The indicators are returned in the I/O buffers. This is the
default.
lrecl=value
The length, in bytes, for fixed length records, and the maximum
length for variable length records. This parameter is valid for diskette,
display, printer, tape, and save files.
nullcap=value
Where value can be:
Y
The program is capable of handling null fields in records.
This is valid for database and DDM files.
N
The program cannot handle null fields in records. This is the
default.
riofb=value
Where value can be:
Y
All fields in the _RIOFB_T structure are updated by any
I/O operation that returns a pointer to the _RIOFB_T structure.
However, the blk_filled_by field is not updated when using the _Rreadk
function. This is the default.
N
Only the num_bytes field in the _RIOFB_T structure
is updated.
rtncode=value
Where value can be:
Y
Use this option to bypass exception generation and handling.
This will improve performance in the end-of-file and record-not-found
cases. If the end-of-file is encountered, num_bytes will be set
to EOF, but no errno values will be generated. If no record is found,
num_bytes will be set to zero, and errno will be set to EIORECERR.
This parameter is only valid for database and DDM files. For DDM files,
num_bytes is not updated for _Rfeod.
N
The normal exception generation and handling process will occur
for the cases of end-of-file and record-not-found. This is the default.
secure=value
Where value can be:
Y
Secures the file from overrides.
N
Does not secure the file from overrides. This is the default.
splfname=(value)
For spooled output only. Where value can be:
*FILE
The name of the printer file is used for the spooled output
file name.
spool-file-name
Specify the name of the spooled output file. A maximum of 10
characters can be used.
usrdta=(value)
To specify, for spooled output only, user-specified data that
identifies the file.
user-data
Specify up to 10 characters of user-specified text.
varparm=(list)
Where (list) is a list of optional keywords indicating
which optional parameters will be passed to _Ropen().
The order of the keywords within the list indicates the order that
the optional parameters will appear after the mode parameter.
The following is a valid optional keyword:
lvlchk
The lvlchk keyword is used in conjunction with the lvlchk option
on #pragma mapinc. When this keyword is used, a pointer to an object
of type _LVLCHK_T (generated by #pragma mapinc) must be specified
after the mode parameter on the _Ropen() function. For
more details on this pointer, see the lvlchk option of #pragma
mapinc in the IBM Rational Development Studio for i: ILE C/C++ Programmer's Guide.
vlr=value
Variable length record, where value is the minimum
length of bytes of a record to be written to the file. The value can
equal -1, or range from 0 to the maximum record length of the file.
This parameter is valid for database and DDM files.
When VLR processing
is required, _Ropen() will set min_length field. If the
default value is not used, the minimum value that is provided by the
user will be directly copied into min_length field. If the default
value is specified, _Ropen() gets the minimum length from
DB portion of the open data path.
Return Value
The _Ropen() function returns a pointer to a structure
of type _RFILE if the file is opened successfully. It returns NULL
if opening the file is unsuccessful.