_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.

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 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.
Note: If the key field of the _RIOFB_T structure is never referenced by the application following writes, specifying insertkeyfb=N can result in better performance when writing. When the last I/O operation is writing, the _Rupfb() function will not update the _RIOFB_T structure with information about this writing operation if insertkeyfb=N is specified.
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.
Note: If the key field of the _RIOFB_T structure is never referenced by the application, specifying keyfb=N can result in better performance. When the last I/O operation is reading, the _Rupfb() function will not update the _RIOFB_T structure with information about this reading operation if keyfb=N is specified.
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.

The value of errno may be set to:
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.
See Table 1 and Table 1 for errno settings.

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 );
}

Related Information