UTL_TCP
パッケージおよびそのプロシージャとファンクションにより、TCP/IPを使用してPL/SQLアプリケーションと外部のTCP/IPベースのサーバーを通信させることができます。インターネット・アプリケーションのプロトコルは多くがTCP/IPに基づいているため、このパッケージはインターネット・プロトコルと電子メールを使用するPL/SQLアプリケーションで使用すると便利です。
この章では、次の項目について説明します。
概要
セキュリティ・モデル
タイプ
例外
ルールおよび制限
例
UTL_TCP
パッケージは、TCP/IPクライアント側のアクセス機能をPL/SQLに提供します。
このパッケージは実行者権限のパッケージになったため、起動するユーザーには、接続するリモート・ネットワーク・ホストに割り当てられたアクセス制御リストで接続権限が付与されている必要があります。
注意: 詳細は、『Oracle Databaseセキュリティ・ガイド』の外部ネットワーク・サービスへのファイングレイン・アクセスの管理に関する項を参照してください。 |
TCP/IP接続を示すPL/SQLレコード・タイプです。
構文
TYPE connection IS RECORD ( remote_host VARCHAR2(255), remote_port PLS_INTEGER, local_host VARCHAR2(255), local_port PLS_INTEGER, charset VARCHAR2(30), newline VARCHAR2(2), tx_timeout PLS_INTEGER, private_sd PLS_INTEGER);
フィールド
表218-1 connectionレコード・タイプのフィールド
フィールド | 説明 |
---|---|
|
接続が確立したときのリモート・ホストの名前。接続が確立されない場合は |
|
接続したリモート・ホストのポート番号。接続が確立されない場合はNULLです。 |
|
接続の確立に使用されるローカル・ホスト名。接続が確立されない場合は |
|
接続の確立に使用されるローカル・ホストのポート番号。接続が確立されない場合は |
|
回線用キャラクタ・セット。データベース内のテキスト・メッセージは、回線上とは異なるキャラクタ・セット(つまり、通信プロトコルで指定されているキャラクタ・セットや他の通信上の終端で規定されているキャラクタ・セットなど)にコード化されている可能性があります。したがって、ネットワーク上での送受信時には、データベース内のテキスト・メッセージと回線用キャラクタ・セットの間の変換が行われます。 |
|
改行文字列。この改行文字列は、 |
|
この接続で読込みまたは書込み操作を中止するまでのUTL_TCPパッケージの待機時間(秒)。読込み操作の場合、読み込めるデータがない場合に操作が即座に中止されます。書込み操作の場合、出力バッファがフルで、ブロックされずにネットワークに送信できるデータがない場合に操作が中止されます。0(ゼロ)は、まったく待機しないことを示します。NULLは、無期限に待機することを示します。 |
使用上の注意
connectionレコードのフィールドは、多くの場合OPEN_CONNECTION
を使用して、接続情報を戻すために使用されます。これらのフィールドを変更しても、接続には影響はありません。 private_XXXX
フィールドは、実装目的にのみ使用されます。これらの値は変更しないでください。
現行のリリースのUTL_TCP
パッケージでは、open_connection
がTCP/IP接続を確立すると、local_host
およびlocal_port
パラメータは無視されます。この場合、接続が確立されると、指定したローカル・ホストおよびポート番号が使用されません。local_host
およびlocal_port
フィールドは、ファンクションにより戻される接続レコードで設定されません。
書込み操作のタイムアウトは、UTL_TCP
パッケージの現行のリリースではサポートされていません。
CR-LF改行文字列。多くの通信規格で一般的に使用されている改行文字列です。
構文
CRLF CONSTANT VARCHAR2(2 CHAR);
使用上の注意
このパッケージ変数によって、多くのインターネット・プロトコルで一般的に使用されている改行文字列を定義します。 これはWRITE_LINE
に対する改行文字列のデフォルト値で、接続のオープン時に指定されます。 このようなプロトコルでは<CR><LF>
を使用して新しい行を示しますが、一部の実装ではLFのみの使用を選択できます。この場合、ユーザーは、接続のオープン時に異なる改行文字列を指定できます。
表218-2に、TCP/IPパッケージで発生する例外を示します。
例外 | 説明 |
---|---|
|
先読みに必要な入力バッファが小さすぎます。 |
|
接続先から読込み可能なデータがこれ以上ない場合に発生します。 |
|
一般的なネットワーク・エラーです。 |
|
不正な引数がAPIコールに渡されました(負のバッファ・サイズなど)。 |
|
データが読み込まれず、読込みタイムアウトが発生しました。 |
|
完全に読み込まれた文字はありません。入力の終わりにマルチバイト・キャラクタの一部が検出されました。 |
このパッケージで提供されるインタフェースで使用できるのは、PL/SQLプログラムにより開始される接続のみです。PL/SQLプログラムでは、プログラム外部で開始された接続を受け入れることができません。
次の例は、HTTPを介してWebページを取り出すときのTCP/IPパッケージの使用方法を示したコードです。ポート80(HTTPの標準ポート)でリスニングするWebサーバーに接続し、ルート・ドキュメントを要求します。
DECLARE c utl_tcp.connection; -- TCP/IP connection to the Web server ret_val pls_integer; BEGIN c := utl_tcp.open_connection(remote_host => 'www.acme.com', remote_port => 80, charset => 'US7ASCII'); -- open connection ret_val := utl_tcp.write_line(c, 'GET / HTTP/1.0'); -- send HTTP request ret_val := utl_tcp.write_line(c); BEGIN LOOP dbms_output.put_line(utl_tcp.get_line(c, TRUE)); -- read result END LOOP; EXCEPTION WHEN utl_tcp.end_of_input THEN NULL; -- end of input END; utl_tcp.close_connection(c); END;
次の例は、アプリケーションがTCP/IPパッケージを使用して、電子メールを送信する方法を示したコードです(PL/SQLによる電子メールとも呼ばれます)。ポート25でSMTPサーバーに接続し、簡単なテキスト・メッセージを送信します。
PROCEDURE send_mail (sender IN VARCHAR2, recipient IN VARCHAR2, message IN VARCHAR2) IS mailhost VARCHAR2(30) := 'mailhost.mydomain.com'; smtp_error EXCEPTION; mail_conn utl_tcp.connection; PROCEDURE smtp_command(command IN VARCHAR2, ok IN VARCHAR2 DEFAULT '250') IS response varchar2(3); len pls_integer; BEGIN len := utl_tcp.write_line(mail_conn, command); response := substr(utl_tcp.get_line(mail_conn), 1, 3); IF (response <> ok) THEN RAISE smtp_error; END IF; END; BEGIN mail_conn := utl_tcp.open_connection(remote_host => mailhost, remote_port => 25, charset => 'US7ASCII'); smtp_command('HELO ' || mailhost); smtp_command('MAIL FROM: ' || sender); smtp_command('RCPT TO: ' || recipient); smtp_command('DATA', '354'); smtp_command(message); smtp_command('QUIT', '221'); utl_tcp.close_connection(mail_conn); EXCEPTION WHEN OTHERS THEN -- Handle the error END;
表218-3 UTL_TCPパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
|
TCP/IP接続からの読込みに使用可能なバイト数を決定します。 |
|
オープン状態のTCP/IP接続をすべてクローズします。 |
|
オープン状態のTCP/IP接続をクローズします。 |
|
バッファが使用されている場合は、出力バッファの全データをサーバーに即時送信します。 |
|
読み込んだデータの行を戻します。 |
|
読み込んだデータの行をNCHAR形式で戻します。 |
|
読込みデータ量ではなく読み込んだデータを戻します。 |
|
読み込んだテキスト・データを戻します。 |
|
読み込んだテキスト・データをNCHAR形式で戻します。 |
|
指定したサービスへのTCP/IP接続をオープンします。 |
|
オープン接続中のサービスからテキスト行を受信します。 |
|
オープン接続中のサービスからバイナリ・データを受信します。 |
|
オープン接続中のサービスからテキスト・データを受信します。 |
|
オープン接続中のサービスにテキスト行を送信します。 |
|
オープン接続中のサービスにバイナリ・メッセージを送信します。 |
|
オープン接続中のサービスにテキスト・メッセージを送信します。 |
このファンクションは、TCP/IP接続からの読込みに使用可能なバイト数を決定します。この数は、ブロッキングなしで即時に読み込むことができるバイト数です。接続からデータを読み込めるかどうかを判断します。
構文
UTL_TCP.AVAILABLE ( c IN OUT NOCOPY connection, timeout IN PLS_INTEGER DEFAULT 0) RETURN PLS_INTEGER;
パラメータ
表218-4 AVAILABLEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
読込み可能なデータ量を判断するTCP接続。 |
|
読込みを中止し、使用可能なデータがないことを報告するまでに待機する時間(秒)。0(ゼロ)は、まったく待機しないことを示します。NULLは、無期限に待機することを示します。 |
戻り値
ブロックされずに読み込むことができるバイト数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。ユーザーはこのAPIを使用して、読込みAPIをコールする前に、データが読込み可能かどうかを確認できるため、入力からデータを読み込む準備が整っていないことでプログラムがブロックされることはありません。
このファンクションでは、読込み可能なバイト数が実際に使用可能なバイト数よりも少なく戻される場合があります。プラットフォームによっては、このファンクションが常に1を戻し、使用可能なデータがあることを示します。アプリケーションの移植性を検討する場合、読込み可能なデータがある場合はこのファンクションが正の値を戻し、ない場合は0(ゼロ)を戻すことを前提としてください。 このファンクションは、特定の接続でのすべてのデータが読み取られた後に次の読取りを行うとEND_OF_INPUT
例外が発生する場合、正の値を戻します。
次の例で、移植可能な方法によるファンクションの使用について示します。
DECLARE c utl_tcp.connection data VARCHAR2(256); len PLS_INTEGER; BEGIN c := utl_tcp.open_connection(...); LOOP IF (utl_tcp.available(c) > 0) THEN len := utl_tcp.read_text(c, data, 256); ELSE ---do some other things . . . . END IF END LOOP; END;
このプロシージャは、オープン状態のTCP/IP接続をすべてクローズします。
構文
UTL_TCP.CLOSE_ALL_CONNECTIONS;
使用上の注意
このコールは、PL/SQLプログラムが参照先のない接続を回避する前に、すべての接続をクローズするために用意されています。
このプロシージャは、オープン状態のTCP/IP接続をクローズします。
構文
UTL_TCP.CLOSE_CONNECTION ( c IN OUT NOCOPY connection);
パラメータ
使用上の注意
接続は、OPEN_CONNECTION
へのコールによって事前にオープンされている必要があります。 cのremote_host、remote_port、local_host、local_port
およびcharset
フィールドは接続がクローズされた後にリセットされます。
オープン状態の接続は、明示的にクローズする必要があります。オープン状態の接続は、接続を格納しているPL/SQLレコード変数がPL/SQLプログラムで無効になると、そのままオープン状態となります。不要な接続を適切にクローズしないと、ローカルおよびリモートのシステム・リソースが無駄になります。
このプロシージャは、バッファが使用されている場合は、出力バッファの全データをサーバーに即時送信します。
構文
UTL_TCP.FLUSH ( c IN OUT NOCOPY connection);
パラメータ
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
このファンクションは、読み込んだデータの行を戻します。
構文
UTL_TCP.GET_LINE ( c IN OUT NOCOPY connection, remove_crlf IN BOOLEAN DEFAULT FALSE, peek IN BOOLEAN DEFAULT FALSE) RETURN VARCHAR2;
パラメータ
表218-7 GET_LINEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
|
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
戻り値
読み込んだテキスト行。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
読込みタイムアウトのREAD_LINE
、キャラクタ・セット変換、バッファ・サイズおよびマルチバイト・キャラクタの箇所を参照してください。
このファンクションは、読み込んだデータの行をNCHAR形式で戻します。
構文
UTL_TCP.GET_LINE_NCHAR ( c IN OUT NOCOPY connection, remove_crlf IN BOOLEAN DEFAULT FALSE, peek IN BOOLEAN DEFAULT FALSE) RETURN NVARCHAR2;
パラメータ
表218-8 GET_LINE_NCHARファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
|
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
戻り値
読み込んだテキスト行。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
読込みタイムアウトのREAD_LINE
、キャラクタ・セット変換、バッファ・サイズおよびマルチバイト・キャラクタの箇所を参照してください。
このファンクションは、読込みデータ量ではなく読み込んだデータを戻します。
構文
UTL_TCP.GET_RAW ( c IN OUT NOCOPY connection, len IN PLS_INTEGER DEFAULT 1, peek IN BOOLEAN DEFAULT FALSE) RETURN RAW;
パラメータ
表218-9 GET_RAWファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
受信するデータのバイト数(または |
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
|
|
戻り値
読み込んだバイナリ・データ。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
この項で説明したget_*
APIのすべては、対応するREAD_*
APIの読込みタイムアウトに関する箇所を参照してください。GET_TEXT
およびGET_LINE
については、対応するREAD_*
APIのキャラクタ・セット変換、バッファ・サイズおよびマルチバイト・キャラクタの箇所を参照してください。
このファンクションは、読み込んだテキスト・データを戻します。
構文
UTL_TCP.GET_TEXT ( c IN OUT NOCOPY connection, len IN PLS_INTEGER DEFAULT 1, peek IN BOOLEAN DEFAULT FALSE) RETURN VARCHAR2;
パラメータ
表218-10 GET_TEXTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
受信するデータのバイト数(または |
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
|
|
戻り値
読み込んだテキスト・データ。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
この項で説明したget_*
APIのすべては、対応するread_*
APIの読込みタイムアウトに関する箇所を参照してください。GET_TEXT
およびGET_LINE
については、対応するREAD_*
APIのキャラクタ・セット変換、バッファ・サイズおよびマルチバイト・キャラクタの箇所を参照してください。
このファンクションは、読み込んだテキスト・データをNCHAR形式で戻します。
構文
UTL_TCP.GET_TEXT_NCHAR ( c IN OUT NOCOPY connection, len IN PLS_INTEGER DEFAULT 1, peek IN BOOLEAN DEFAULT FALSE) RETURN NVARCHAR2;
パラメータ
表218-11 GET_TEXT_NCHARファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
受信するデータのバイト数(または |
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
|
|
戻り値
読み込んだテキスト・データ。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
この項で説明したget_*
APIのすべては、対応するread_*
APIの読込みタイムアウトに関する箇所を参照してください。GET_TEXT
およびGET_LINE
については、対応するREAD_*
APIのキャラクタ・セット変換、バッファ・サイズおよびマルチバイト・キャラクタの箇所を参照してください。
このファンクションは、指定したサービスへのTCP/IP接続をオープンします。
構文
UTL_TCP.OPEN_CONNECTION ( remote_host IN VARCHAR2, remote_port IN PLS_INTEGER, local_host IN VARCHAR2 DEFAULT NULL, local_port IN PLS_INTEGER DEFAULT NULL, in_buffer_size IN PLS_INTEGER DEFAULT NULL, out_buffer_size IN PLS_INTEGER DEFAULT NULL, charset IN VARCHAR2 DEFAULT NULL, newline IN VARCHAR2 DEFAULT CRLF, tx_timeout IN PLS_INTEGER DEFAULT NULL) RETURN connection;
パラメータ
表218-12 OPEN_CONNECTIONファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
サービスを提供するホストの名前。 |
|
サービスが接続をリスニングするポート番号。 |
|
サービスを提供するホストの名前。NULLの場合は無視されます。 |
|
サービスが接続をリスニングするポート番号。NULLの場合は無視されます。 |
|
入力バッファのサイズ。入力バッファを使用すると、サーバーからデータを受信する際の実行パフォーマンスを高速化できます。バッファの適正サイズは、クライアントとサーバーの間のデータの流れやネットワーク条件によって異なります。0(ゼロ)の値は、バッファを使用しないことを意味します。NULLの値は、バッファが使用されているかどうかをコール元が無視することを意味します。入力バッファの最大サイズは、32767バイトです。 |
|
出力バッファのサイズ。出力バッファを使用すると、サーバーにデータを送信する際の実行パフォーマンスを高速化できます。バッファの適正サイズは、クライアントとサーバーの間のデータの流れやネットワーク条件によって異なります。0(ゼロ)の値は、バッファを使用しないことを意味します。NULLの値は、バッファが使用されているかどうかをコール元が無視することを意味します。出力バッファの最大サイズは、32767バイトです。 |
|
回線用キャラクタ・セット。 データベース内のテキスト・メッセージは、回線上とは異なるキャラクタ・セット(つまり、通信プロトコルで指定されているキャラクタ・セットや他の通信上の終端で規定されているキャラクタ・セットなど)にコード化されている可能性があります。したがって、ネットワーク上での送受信時には、 |
|
改行文字列。この改行文字列は、 |
|
この接続で読込みまたは書込み操作を中止するまでの |
戻り値
目的のTCP/IPサービスへの接続。
使用上の注意
このUTL_TCP
パッケージでオープンした接続は、オープン状態のまま、あるデータベース・コールから共有サーバー構成内の別のデータベース・コールに渡すことができます。ただし、接続は明示的にクローズする必要があります。接続を格納しているPL/SQLレコード変数がPL/SQLプログラムで無効になると、接続はオープン状態のままになります。不要な接続を適切にクローズしないと、ローカルおよびリモートのシステム・リソースが無駄になります。
現行のリリースのUTL_TCP
パッケージでは、open_connection
がTCP/IP接続を確立すると、local_host
およびlocal_port
パラメータは無視されます。この場合、接続が確立されると、指定したローカル・ホストおよびポート番号が使用されません。local_host
およびlocal_port
フィールドは、ファンクションにより戻される接続レコードで設定されません。
tx_timeout
は、読込み操作および書込み操作の両方を制御するものです。ただし、現行のリリースでは実装が制限されているため、tx_timeout
による書込み操作の制御は行われません。
このファンクションは、オープン接続中のサービスからテキスト行を受信します。行は、LF改行、CR改行またはCR-LF改行(CRの後にLFが続く)で終了します。
構文
UTL_TCP.READ_LINE ( c IN OUT NOCOPY connection, data IN OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS, peek IN BOOLEAN DEFAULT FALSE) RETURN PLS_INTEGER;
パラメータ
表218-13 READ_LINEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
受信データ。 |
|
|
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
戻り値
受信したデータの文字数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。 このファンクションは、行の終わりまたは入力の最後に達するまで戻りません。テキスト・メッセージは、コール元に戻される前に、接続のオープン時に指定した回線用キャラクタ・セットからデータベース・キャラクタ・セットに変換されます。
接続がオープンされたときに転送のタイムアウトが設定されている場合、このファンクションは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれる準備を完了するのを待機します。タイムアウトが発生すると、このファンクションは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
マルチバイト・キャラクタの一部が入力の終わりで検出された場合、このファンクションは読込みを中止し、完全に読み込まれたマルチバイト・キャラクタをすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char
例外が発生します。READ_RAW
ファンクションを使用して例外を処理し、部分的なマルチバイト・キャラクタのバイトをバイナリとして読み込むことができます。マルチバイト・キャラクタの一部が渡されていない状態でタイムアウトが発生したため、マルチバイト・キャラクタの残りの部分が入力途中で表示された場合は、そのかわりにtransfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
このファンクションは、オープン接続中のサービスからバイナリ・データを受信します。
構文
UTL_TCP.READ_RAW ( c IN OUT NOCOPY connection, data IN OUT NOCOPY RAW, len IN PLS_INTEGER DEFAULT 1, peek IN BOOLEAN DEFAULT FALSE) RETURN PLS_INTEGER;
パラメータ
表218-14 READ_RAWファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
受信データ。 |
|
受信するデータのバイト数。 |
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグを |
戻り値
受信したデータのバイト数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。このファンクションは、指定したバイト数が読み込まれるまで、または入力の最後に達するまで戻りません。
接続がオープンされたときに転送のタイムアウトが設定されている場合、このファンクションは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれる準備を完了するのを待機します。タイムアウトが発生すると、このファンクションは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
このファンクションは、オープン接続中のサービスからテキスト・データを受信します。
構文
UTL_TCP.READ_TEXT ( c IN OUT NOCOPY connection, data IN OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS, len IN PLS_INTEGER DEFAULT 1, peek IN BOOLEAN DEFAULT FALSE) RETURN PLS_INTEGER;
パラメータ
表218-15 READ_TEXTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの受信元TCP接続。 |
|
受信データ。 |
|
受信データの文字数。 |
|
通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを先読み、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合もあります。入力キューにデータを保持するには、このフラグを |
戻り値
受信したデータの文字数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。このファンクションは、指定した文字数が読み込まれるまで、または入力の最後に達するまで戻りません。テキスト・メッセージは、コール元に戻される前に、接続のオープン時に指定した回線用キャラクタ・セットからデータベース・キャラクタ・セットに変換されます。
明示的に無視された場合を除き、VARCHAR2
バッファのサイズはバイト数で指定されます。これに対し、len
パラメータは読み込まれる最大文字数を参照します。データベース・キャラクタ・セットにマルチバイトが設定されていると、単一の文字が複数のバイトで構成されている場合は、バッファが最大文字数を保持できることを確認する必要があります。一般に、VARCHAR2
バッファは読み込まれる文字数にデータベース・キャラクタ・セットの1文字の最大バイト数を乗算した数と等しくする必要があります。
接続がオープンされたときに転送のタイムアウトが設定されている場合、このファンクションは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれる準備を完了するのを待機します。タイムアウトが発生すると、このファンクションは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
マルチバイト・キャラクタの一部が入力の終わりで検出された場合、このファンクションは読込みを中止し、完全に読み込まれたマルチバイト・キャラクタをすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char
例外が発生します。READ_RAW
ファンクションを使用して例外を処理し、部分的なマルチバイト・キャラクタのバイトをバイナリとして読み込むことができます。マルチバイト・キャラクタの一部が渡されていない状態でタイムアウトが発生したため、マルチバイト・キャラクタの残りの部分が入力途中で表示された場合は、そのかわりにtransfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
このファンクションは、オープン接続中のサービスにテキスト行を送信します。送信前に、newline
文字列がメッセージに追加されます。
構文
UTL_TCP.WRITE_LINE ( c IN OUT NOCOPY connection, data IN VARCHAR2 DEFAULT NULL CHARACTER SET ANY_CS) RETURN PLS_INTEGER;
パラメータ
戻り値
実際に送信したデータの文字数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。テキスト・メッセージは、回線に送信される前に、接続のオープン時に指定した回線用キャラクタ・セットに変換されます。
このファンクションは、オープン接続中のサービスにバイナリ・メッセージを送信します。指定されたバイト数が書き込まれるまで、何も戻されません。
構文
UTL_TCP.WRITE_RAW ( c IN OUT NOCOPY connection, data IN RAW, len IN PLS_INTEGER DEFAULT NULL) RETURN PLS_INTEGER;
パラメータ
表218-17 WRITE_RAWファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの送信先TCP接続。 |
|
送信するデータを含んだバッファ。 |
|
送信するデータのバイト数。 |
戻り値
送信したデータのバイト数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。
このファンクションは、オープン接続中のサービスにテキスト・メッセージを送信します。
構文
UTL_TCP.WRITE_TEXT ( c IN OUT NOCOPY connection, data IN VARCHAR2 CHARACTER SET ANY_CS, len IN PLS_INTEGER DEFAULT NULL) RETURN num_chars PLS_INTEGER;
パラメータ
表218-18 WRITE_TEXTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
データの送信先TCP接続。 |
|
送信するデータを含んだバッファ。 |
|
送信するデータの文字数。 |
戻り値
実際に送信したデータの文字数。
使用上の注意
接続は、OPEN_CONNECTION
へのコールを介してすでにオープン状態になっている必要があります。テキスト・メッセージは、回線に送信される前に、接続のオープン時に指定した回線用キャラクタ・セットに変換されます。