カートリッジ・サービス — ファイルI/Oインタフェース

カートリッジ・サービスのファイルI/Oインタフェース関数をリストし、説明します。

表20-5は、この項で説明しているファイルI/Oインタフェース関数を示しています。

表20-5 ファイルI/Oインタフェース関数

関数	用途
OCIFileClose()	オープンされているファイルをクローズします。
OCIFileExists()	ファイルの存在を確認するためにテストします。
OCIFileFlush()	バッファ・データをファイルに書き込みます。
OCIFileGetLength()	ファイルの長さを取得します。
OCIFileInit()	OCIFileパッケージを初期化します。
OCIFileOpen()	ファイルをオープンします。
OCIFileRead()	ファイルからバッファにデータを読み取ります。
OCIFileSeek()	ファイルの現行の位置を変更します。
OCIFileTerm()	OCIFileパッケージを終了します。
OCIFileWrite()	buflenバイトをファイルに書き込みます。

関連項目:

これらの関数の使用方法の詳細は、『Oracle Databaseデータ・カートリッジ開発者ガイド』を参照してください

OCIFileObject

OCIFileObjectデータ構造には、ファイルのオープン方法およびオープンしてからそのファイルへアクセスする方法に関する情報が保持されています。この構造をOCIFileOpen()で初期化すると、ファイルで実行可能な操作によって識別子となります。このパラメータは、オープンされているファイルで実行するすべての機能に必要です。このデータ構造はOCIFileクライアントには不透明です。これはOCIFileOpen()で初期化し、OCIFileClose()で終了します。

OCIFileClose()

用途

オープンされているファイルをクローズします。

構文

sword OCIFileClose( void          *hndl, 
                    OCIError      *err, 
                    OCIFileObject *filep );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

クローズされるファイル識別子へのポインタです。

コメント

この関数によってOCI_SUCCESSが戻されると、filepによって指し示されたOCIFileObject構造は破棄されます。したがって、この関数によってOCI_SUCCESSが戻されてからこの構造にはアクセスしないでください。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileExists()

用途

ファイルの存在を確認するためにテストします。

構文

sword OCIFileExists( void     *hndl, 
                     OCIError *err, 
                     OraText  *filename, 
                     OraText  *path, 
                     ub1      *flag );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filename (IN)

NULLで終了する文字列のファイル名です。

path (IN)

NULLで終了する文字列のファイルのパスです。

flag (OUT)

ファイルが存在する場合はTRUEに設定し、それ以外の場合はFALSEに設定します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileFlush()

用途

バッファ・データをファイルに書き込みます。

構文

sword OCIFileFlush( void          *hndl
                    OCIError      *err, 
                    OCIFileObject *filep );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileGetLength()

用途

ファイルの長さを取得します。

構文

sword OCIFileGetLength( void     *hndl, 
                        OCIError *err, 
                        OraText  *filename, 
                        OraText  *path, 
                        ubig_ora *lenp );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filename (IN)

NULLで終了する文字列のファイル名です。

path (IN)

NULLで終了する文字列のファイルのパスです。

lenp (OUT)

バイトで示したバッファの長さに設定します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileInit()

用途

OCIFileパッケージを初期化します。この関数をコールしてから、他のOCIFileルーチンをコールする必要があります。

構文

sword OCIFileInit( void     *hndl, 
                   OCIError *err );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileOpen()

用途

ファイルをオープンします。

構文

sword OCIFileOpen( void           *hndl, 
                   OCIError       *err, 
                   OCIFileObject  **filep, 
                   OraText        *filename, 
                   OraText        *path, 
                   ub4            mode, 
                   ub4            create, 
                   ub4            type );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイル識別子です。

filename (IN)

NULLで終了する文字列のファイル名です。

path (IN)

NULLで終了する文字列のファイルのパスです。

mode (IN)

ファイルをオープンするモードです。次のモードが有効です。

OCI_FILE_READ_ONLY

OCI_FILE_WRITE_ONLY

OCI_FILE_READ_WRITE

create (IN)

ファイルが存在しない場合に作成するかどうか指定します。次の値が有効です。

OCI_FILE_TRUNCATE — ファイルをその存在の有無に関係なく作成します。ファイルが存在する場合は、既存のファイルが上書きされます。

OCI_FILE_EXCL — ファイルが存在する場合は失敗し、存在しない場合はファイルが作成されます。

OCI_FILE_CREATE — ファイルが存在する場合はそのファイルをオープンし、存在しない場合はファイルが作成されます。

OCI_FILE_APPEND — 書込みの前にファイルの終わりへのファイル・ポインタを設定します。このフラグは、OCI_FILE_CREATEで論理演算子ORとともに使用できます。

type (IN)

ファイルの型。次の値が有効です。

OCI_FILE_TEXT

OCI_FILE_BIN

OCI_FILE_STDIN

OCI_FILE_STDOUT

OCI_FILE_STDERR

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileRead()

用途

ファイルからバッファにデータを読み取ります。

構文

sword OCIFileRead( void          *hndl, 
                   OCIError      *err, 
                   OCIFileObject *filep, 
                   void          *bufp, 
                   ub4           bufl, 
                   ub4           *bytesread );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

bufp (IN)

データの読取り先バッファへのポインタです。buflのメモリー長が割り当てられるとみなされます。

bufl (IN)

バイトで示したバッファの長さです。

bytesread (OUT)

読取りバイト数です。

コメント

可能なバイト数をユーザー・バッファに読み取ります。読取りはユーザー・バッファが一杯になった場合、またはEOFに達すると終了します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileSeek()

用途

ファイルの現行の位置を変更します。

構文

sword OCIFileSeek( void          *hndl, 
                   OCIError      *err, 
                   OCIFileObject *filep, 
                   uword         origin, 
                   ubig_ora      offset, 
                   sb1           dir );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

origin (IN)

検索の開始地点です。次のいずれかの値を使用します。

OCI_FILE_SEEK_BEGINNING (先頭)

OCI_FILE_SEEK_CURRENT (現行の位置)

OCI_FILE_SEEK_END (EOF)

offset (IN)

読取り開始地点からのバイト数です。

dir (IN)

開始地点から移動する方向です。

注意:

方向はOCIFILE_FORWARDまたはOCIFILE_BACKWARDのいずれかです。

コメント

この関数では、ファイルの終わりを超えて検索できます。このような位置から読取りを実行すると、EOF条件がレポートされます。そのような位置への書込みは一部のファイル・システムでしか機能しません。これは、ファイルの動的成長が許可されていないシステムがあるためです。このようなシステムでは、ファイルを固定サイズで事前割当てする必要があります。この関数はバイト位置に対して検索を実行するということに注意してください。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileTerm()

用途

OCIFileパッケージを終了します。この関数は、OCIFileパッケージを使用しなくなってからコールする必要があります。

構文

sword OCIFileTerm( void     *hndl, 
                   OCIError *err );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileWrite()

用途

buflenバイトをファイルに書き込みます。

構文

sword OCIFileWrite( void          *hndl, 
                    OCIError      *err, 
                    OCIFileObject *filep, 
                    void          *bufp, 
                    ub4           buflen, 
                    ub4           *byteswritten );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

bufp (IN)

データの書込み元バッファへのポインタです。buflenのメモリー長が割り当てられるとみなされます。

buflen (IN)

バイトで示したバッファの長さです。

byteswritten (OUT)

書込みバイト数です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。