ILE C/C++ Run-Time Library Functions
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 iSeries 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 iSeries 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 WebSphere Development Studio: 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 12 and Table 14 for errno settings.
Example that uses _Ropen()
#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
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.