Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
This section describes the file I/O interface functions.
Table 19-6 File I/O Interface Functions
Function/Page | Purpose |
---|---|
|
Closes a previously opened file. |
|
Tests to see if the file exists. |
|
Writes buffered data to a file. |
|
Gets the length of a file. |
|
Initializes the OCIFile package. |
|
Opens a file. |
|
Reads from a file into a buffer. |
|
Changes the current position in a file. |
|
Terminates the OCIFile package. |
|
Writes buflen bytes into the file. |
See Also:
For more information about using these functions, see Oracle Database Data Cartridge Developer's GuideOCIFileObject
The OCIFileObject data structure holds information about the way in which a file should be opened and the way in which it will be accessed once it has been opened. When this structure is initialized by OCIFileOpen()
, it becomes an identifier through which operations can be performed on that file. It is a necessary parameter to every function that operates on open files. This data structure is opaque to OCIFile clients. It is initialized by OCIFileOpen()
and terminated by OCIFileClose()
.
Purpose
Initializes the OCIFile package. It must be called before any other OCIFile routine is called.
Syntax
sword OCIFileInit( dvoid *hndl, OCIError *err );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Terminates the OCIFile package. It must be called after the OCIFile package is no longer being used.
Syntax
sword OCIFileTerm( dvoid *hndl, OCIError *err );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Opens a file.
Syntax
sword OCIFileOpen( dvoid *hndl, OCIError *err, OCIFileObject **filep, OraText *filename, OraText *path, ub4 mode, ub4 create, ub4 type );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
The file identifier.
The file name as a NULL
-terminated string.
The path of the file as a NULL
-terminated string.
The mode in which to open the file. Valid modes are
OCI_FILE_READ_ONLY
,
OCI_FILE_WRITE_ONLY
,
OCI_FILE_READ_WRITE
.
Indicates if the file be created if it does not exist — valid values are:
OCI_FILE_TRUNCATE
— create a file regardless of whether or not it exists. If the file already exists overwrite the existing file.
OCI_FILE_EXCL
— fail if the file exists, else create.
OCI_FILE_CREATE
— open the file if it exists, and create it if it does not.
OCI_FILE_APPEND
— set the file pointer to the end of the file prior to writing. This flag can be ORed with OCI_FILE_CREATE
File type. Valid values are
OCI_FILE_TEXT
,
OCI_FILE_BIN
,
OCI_FILE_STDIN
,
OCI_FILE_STDOUT
,
OCI_FILE_STDERR
.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Closes a previously opened file.
Syntax
sword OCIFileClose( dvoid *hndl, OCIError *err, OCIFileObject *filep );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
A pointer to a file identifier to be closed.
Comments
Once this returns, the OCIFileObject
structure pointed to by filep
will have been destroyed. Therefore, you should not attempt to access this structure after this returns.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Reads from a file into a buffer.
Syntax
sword OCIFileRead( dvoid *hndl, OCIError *err, OCIFileObject *filep, dvoid *bufp, ub4 bufl, ub4 *bytesread );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
A file identifier that uniquely references the file.
The pointer to a buffer into which the data will be read. The length of the allocated memory is assumed to be bufl
.
The length of the buffer in bytes.
The number of bytes read.
Comments
As many bytes as possible will be read into the user buffer. The read will end either when the user buffer is full, or when it reaches end-of-file.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Writes buflen
bytes into the file.
Syntax
sword OCIFileWrite( dvoid *hndl, OCIError *err, OCIFileObject *filep, dvoid *bufp, ub4 buflen, ub4 *byteswritten );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
A file identifier that uniquely references the file.
The pointer to a buffer from into which the data will be written. The length of the allocated memory is assumed to be buflen
.
The length of the buffer in bytes.
The number of bytes written.
Returns
OCI_SUCCESS
, OCI_INVALID_HANDLE
, OCI_ERROR
.
Purpose
Changes the current position in a file.
Syntax
sword OCIFileSeek( dvoid *hndl, OCIError *err, OCIFileObject *filep, uword origin, ubig_ora offset, sb1 dir );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
A file identifier that uniquely references the file.
The starting point we want to seek from. The starting point may be
OCI_FILE_SEEK_BEGINNING
(beginning),
OCI_FILE_SEEK_CURRENT
(current position),
OCI_FILE_SEEK_END
(end of file).
The number of bytes from the origin you want to start reading from.
The direction to go from the origin.
Note:
The direction can be either OCIFILE_FORWARD or OCIFILE_BACKWARD.Comments
This will allow a seek past the end of the file. Reading from such a position will cause an end-of-file condition to be reported. Writing to such a position will not work on all file systems. This is because some systems do not allow files to grow dynamically. They require that files be preallocated with a fixed size. Note that this function performs a seek to a byte location.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Tests to see if the file exists.
Syntax
sword OCIFileExists( dvoid *hndl, OCIError *err, OraText *filename, OraText *path, ub1 *flag );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
The file name as a NULL
-terminated string.
The path of the file as a NULL
-terminated string.
Set to TRUE
if the file exists or FALSE
if it does not.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Gets the length of a file.
Syntax
sword OCIFileGetLength( dvoid *hndl, OCIError *err, OraText *filename, OraText *path, ubig_ora *lenp );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
The file name as a NULL
-terminated string.
The path of the file as a NULL
-terminated string.
Set to the length of the file in bytes.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Purpose
Writes buffered data to a file.
Syntax
sword OCIFileFlush( dvoid *h OCIError *err, OCIFileObject *filep );
Parameters
The OCI environment or user session handle.
The OCI error handle; if there is an error, it is recorded in err
and this function returns OCI_ERROR
; diagnostic information can be obtained by calling OCIErrorGet()
.
A file identifier that uniquely references the file.
Returns
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.