_Ropen() — Open a Record File for I/O Operations
Format
#include <recio.h>
_RFILE *_Ropen(const char * filename, const char * mode, ...);
Language Level
ILE C Extension
Threadsafe
Yes
Description
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 IBM® i system file
name.
- 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.
- 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 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.
- insertkeyfb=value
- Where value can be:
- Y
- Specifies that insert key feedback is requested for keyed files opened for writing with arrseq=N. This is the default.
- N
- Specifies that insert key feedback is not requested.
- keyfb=value
- Where value can be:
- Y
- Specifies that read key feedback is requested for keyed files opened for reading with arrseq=N. This is the default.
- N
- Specifies that read key feedback is not requested.
- 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 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.
- Value
- Meaning
- EBADMODE
- The file mode that is specified is not valid.
- EBADNAME
- The file name that is specified is not valid.
- ECONVERT
- A conversion error occurred.
- ENOTOPEN
- The file is not open.
- EIOERROR
- A non-recoverable I/O error occurred.
- EIORECERR
- A recoverable I/O error occurred.
Example
#include <stdio.h>
#include <stdlib.h>
#include <recio.h>
int main(void)
{
_RFILE *fp;
/* Open the file for processing in arrival sequence. */
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL )
{
printf ( "Open failed\n" );
exit ( 1 );
}
else
/* Do some processing */;
_Rclose ( fp );
}