日本語PDF
  1. PL/SQLパッケージおよびタイプ・リファレンス
  2. UTL_TCP

279 UTL_TCP

UTL_TCPパッケージおよびそのプロシージャとファンクションにより、TCP/IPを使用してPL/SQLアプリケーションと外部のTCP/IPベースのサーバーを通信させることができます。インターネット・アプリケーションのプロトコルは多くがTCP/IPに基づいているため、このパッケージはインターネット・プロトコルと電子メールを使用するPL/SQLアプリケーションで使用すると便利です。

この章のトピックは、次のとおりです:

279.1 UTL_TCPの概要

UTL_TCPパッケージは、TCP/IPクライアント側のアクセス機能をPL/SQLに提供します。

279.2 UTL_TCPのセキュリティ・モデル

このパッケージは実行者権限のパッケージであるため、起動するユーザーには、接続するリモート・ネットワーク・ホストに割り当てられたアクセス制御リストで接続権限が付与されている必要があります。

ノート:

ファイングレイン・アクセスの管理の詳細は、『Oracle Databaseセキュリティ・ガイド』を参照してください。

279.3 UTL_TCPのタイプ

UTL_TCPパッケージには、CONNECTIONタイプおよびCR-LF改行(CRLF)タイプが含まれます。

CONNECTIONタイプ

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

フィールド

表279-1 connectionレコード・タイプのフィールド

フィールド 説明

remote_host

接続が確立したときのリモート・ホストの名前。接続が確立されない場合はNULLです。

remote_port

接続したリモート・ホストのポート番号。接続が確立されない場合はNULLです。

local_host

接続の確立に使用されるローカル・ホスト名。接続が確立されない場合はNULLです。

local_port

接続の確立に使用されるローカル・ホストのポート番号。接続が確立されない場合はNULLです。

charset

回線用文字セット。データベース内のテキスト・メッセージは、回線上とは異なる文字セット(つまり、通信プロトコルで指定されている文字セットや他の通信上の終端で規定されている文字セットなど)にコード化されている可能性があります。したがって、ネットワーク上での送受信時には、データベース内のテキスト・メッセージと回線用文字セットの間の変換が行われます。

newline

改行文字列。この改行文字列は、WRITE_LINE APIで送信されるテキスト行に追加されます。

tx_timeout

この接続で読込みまたは書込み操作を中止するまでの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パッケージの現行のリリースではサポートされていません。

CRLF

CR-LF改行文字列。多くの通信規格で一般的に使用されている改行文字列です。

構文

CRLF CONSTANT VARCHAR2(2 CHAR);

使用上のノート

このパッケージ変数によって、多くのインターネット・プロトコルで一般的に使用されている改行文字列を定義します。これはWRITE_LINEに対する改行文字列のデフォルト値で、接続のオープン時に指定されます。このようなプロトコルでは<CR><LF>を使用して新しい行を示しますが、一部の実装ではLFのみの使用を選択できます。この場合、ユーザーは、接続のオープン時に異なる改行文字列を指定できます。

279.4 UTL_TCPの例外

UTL_TCPでは、処理問題が発生すると、例外が発生します。

次の表に、TCP/IPパッケージで発生する例外を示します。

表279-2 TCP/IPの例外

例外 説明

BUFFER_TOO_SMALL

先読みに必要な入力バッファが小さすぎます。

END_OF_INPUT

接続先から読込み可能なデータがこれ以上ない場合に発生します。

NETWORK_ERROR

一般的なネットワーク・エラーです。

BAD_ARGUMENT

不正な引数がAPIコールに渡されました(負のバッファ・サイズなど)。

TRANSFER_TIMEOUT

データが読み込まれず、読込みタイムアウトが発生しました。

PARTIAL_MULTIBYTE_CHAR

完全に読み込まれた文字はありません。入力の終わりにマルチバイト文字の一部が検出されました。

279.5 UTL_TCPのルールおよび制限

このパッケージで提供されるインタフェースで使用できるのは、PL/SQLプログラムにより開始される接続のみです。PL/SQLプログラムでは、プログラム外部で開始された接続を受け入れることができません。

279.6 UTL_TCPの例

UTL_TCPで可能な使用方法には、HTTPを介したWebページの取得や電子メールの送信などがあります。

次の例は、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;

279.7 UTL_TCPサブプログラムの要約

この表は、UTL_TCPサブプログラムを示し、簡単に説明しています。

表279-3 UTL_TCPパッケージのサブプログラム

サブプログラム 説明

AVAILABLEファンクション

TCP/IP接続からの読込みに使用可能なバイト数を決定します。

CLOSE_ALL_CONNECTIONSプロシージャ

オープン状態のTCP/IP接続をすべてクローズします。

CLOSE_CONNECTIONプロシージャ

オープン状態のTCP/IP接続をクローズします。

FLUSHプロシージャ

バッファが使用されている場合は、出力バッファの全データをサーバーに即時送信します。

GET_LINEファンクション

読み込んだデータの行を戻します。

GET_LINE_NCHARファンクション

読み込んだデータの行をNCHAR形式で戻します。

GET_RAWファンクション

読込みデータ量ではなく読み込んだデータを戻します。

GET_TEXTファンクション

読み込んだテキスト・データを戻します。

GET_TEXT_NCHARファンクション

読み込んだテキスト・データをNCHAR形式で戻します。

OPEN_CONNECTIONファンクション

指定したサービスへのTCP/IP接続をオープンします。

READ_LINEファンクション

オープン接続中のサービスからテキスト行を受信します。

READ_RAWファンクション

オープン接続中のサービスからバイナリ・データを受信します。

READ_TEXTファンクション

オープン接続中のサービスからテキスト・データを受信します。

SECURE_CONNECTIONプロシージャ

SSL/TLSを使用してTCP/IP接続を保護します。

WRITE_LINEファンクション

オープン接続中のサービスにテキスト行を送信します。

WRITE_RAWファンクション

オープン接続中のサービスにバイナリ・メッセージを送信します。

WRITE_TEXTファンクション

オープン接続中のサービスにテキスト・メッセージを送信します。

279.7.1 AVAILABLEファンクション

このファンクションは、TCP/IP接続からの読取りに使用可能なバイト数を決定します。このバイト数は、ブロッキングなしで即時に読み取ることができるバイト数です。接続からデータを読み取れるかどうかを判断します。

構文

UTL_TCP.AVAILABLE (
   c        IN OUT NOCOPY connection, 
   timeout  IN PLS_INTEGER DEFAULT 0)
RETURN PLS_INTEGER;

パラメータ

表279-4 AVAILABLEファンクションのパラメータ

パラメータ 説明

c

読込み可能なデータ量を判断するTCP接続。

timeout

読込みを中止し、使用可能なデータがないことを報告するまでに待機する時間(秒)。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;

279.7.2 CLOSE_ALL_CONNECTIONSプロシージャ

このプロシージャは、オープン状態のTCP/IP接続をすべてクローズします。

構文

UTL_TCP.CLOSE_ALL_CONNECTIONS;

使用上のノート

このコールは、PL/SQLプログラムが参照先のない接続を回避して終了する前に、すべての接続をクローズするために用意されています。

279.7.3 CLOSE_CONNECTIONプロシージャ

このプロシージャは、オープン状態のTCP/IP接続をクローズします。

構文

UTL_TCP.CLOSE_CONNECTION (
   c IN OUT NOCOPY connection);

パラメータ

表279-5 CLOSE_CONNECTIONプロシージャのパラメータ

パラメータ 説明

c

クローズするTCP接続。

使用上のノート

接続は、OPEN_CONNECTIONへのコールによって事前にオープンされている必要があります。cのremote_host、remote_port、local_host、local_portおよびcharsetフィールドは接続がクローズされた後にリセットされます。

オープン状態の接続は、明示的にクローズする必要があります。オープン状態の接続は、接続を格納しているPL/SQLレコード変数がPL/SQLプログラムで無効になると、そのままオープン状態となります。不要な接続を適切にクローズしないと、ローカルおよびリモートのシステム・リソースが無駄になります。

279.7.4 FLUSHプロシージャ

このプロシージャは、バッファが使用されている場合は、出力バッファの全データをサーバーに即時送信します。

構文

UTL_TCP.FLUSH (
   c IN OUT NOCOPY connection);

パラメータ

表279-6 FLUSHプロシージャのパラメータ

パラメータ 説明

c

データの送信先TCP接続。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

279.7.5 GET_LINEファンクション

このファンクションは、読み込んだデータの行を戻します。

構文

UTL_TCP.GET_LINE (
   c           IN OUT NOCOPY connection,
   remove_crlf IN            BOOLEAN DEFAULT FALSE,
   peek        IN            BOOLEAN DEFAULT FALSE) 
 RETURN VARCHAR2;

パラメータ

表279-7 GET_LINEファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

remove_crlf

TRUEの場合は、後に続く1つ以上のCRLF文字が受信メッセージから削除されます。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

戻り値

読み込んだテキスト行。

使用上のノート

  • 接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

  • 読込みタイムアウトのREAD_LINE、文字セット変換、バッファ・サイズおよびマルチバイト文字の箇所を参照してください。

279.7.6 GET_LINE_NCHARファンクション

このファンクションは、読み込んだデータの行をNCHAR形式で戻します。

構文

UTL_TCP.GET_LINE_NCHAR (
   c           IN OUT NOCOPY connection,
   remove_crlf IN            BOOLEAN DEFAULT FALSE,
   peek        IN            BOOLEAN DEFAULT FALSE) 
 RETURN NVARCHAR2;

パラメータ

表279-8 GET_LINE_NCHARファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

remove_crlf

TRUEの場合は、後に続く1つ以上のCRLF文字が受信メッセージから削除されます。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

戻り値

読み込んだテキスト行。

使用上のノート

  • 接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

  • 読込みタイムアウトのREAD_LINE、文字セット変換、バッファ・サイズおよびマルチバイト文字の箇所を参照してください。

279.7.7 GET_RAWファンクション

このファンクションは、読込みデータ量ではなく読み込んだデータを戻します。

構文

UTL_TCP.GET_RAW (
   c     IN OUT NOCOPY connection,
   len   IN            PLS_INTEGER DEFAULT 1,
   peek  IN            BOOLEAN     DEFAULT FALSE) 
 RETURN RAW;

パラメータ

表279-9 GET_RAWファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

len

受信するデータのバイト数(またはVARCHAR2の文字数)。デフォルトは1です。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

remove_crlf

TRUEの場合は、後に続く1つ以上のCRLF文字が受信メッセージから削除されます。

戻り値

読み込んだバイナリ・データ。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

この項で説明したget_* APIのすべては、対応するREAD_* APIの読込みタイムアウトに関する箇所を参照してください。GET_TEXTおよびGET_LINEについては、対応するREAD_* APIの文字セット変換、バッファ・サイズおよびマルチバイト文字の箇所を参照してください。

279.7.8 GET_TEXTファンクション

このファンクションは、読み込んだテキスト・データを戻します。

構文

UTL_TCP.GET_TEXT (
   c    IN OUT NOCOPY connection,
   len  IN            PLS_INTEGER DEFAULT 1,
   peek IN            BOOLEAN     DEFAULT FALSE) 
 RETURN VARCHAR2;

パラメータ

表279-10 GET_TEXTファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

len

受信するデータのバイト数(またはVARCHAR2の文字数)。デフォルトは1です。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

remove_crlf

TRUEの場合は、後に続く1つ以上のCRLF文字が受信メッセージから削除されます。

戻り値

読み込んだテキスト・データ。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

この項で説明したget_* APIのすべては、対応するread_* APIの読込みタイムアウトに関する箇所を参照してください。GET_TEXTおよびGET_LINEについては、対応するREAD_* APIの文字セット変換、バッファ・サイズおよびマルチバイト文字の箇所を参照してください。

279.7.9 GET_TEXT_NCHARファンクション

このファンクションは、読み込んだテキスト・データをNCHAR形式で戻します。

構文

UTL_TCP.GET_TEXT_NCHAR (
   c    IN OUT NOCOPY connection,
   len  IN            PLS_INTEGER DEFAULT 1,
   peek IN            BOOLEAN     DEFAULT FALSE) 
 RETURN NVARCHAR2;

パラメータ

表279-11 GET_TEXT_NCHARファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

len

受信するデータのバイト数(またはVARCHAR2の文字数)。デフォルトは1です。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

remove_crlf

TRUEの場合は、後に続く1つ以上のCRLF文字が受信メッセージから削除されます。

戻り値

読み込んだテキスト・データ。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

この項で説明したget_* APIのすべては、対応するread_* APIの読込みタイムアウトに関する箇所を参照してください。GET_TEXTおよびGET_LINEについては、対応するREAD_* APIの文字セット変換、バッファ・サイズおよびマルチバイト文字の箇所を参照してください。

279.7.10 OPEN_CONNECTIONファンクション

このファンクションは、指定したサービスへの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,
   wallet_path          IN  VARCHAR2 DEFAULT NULL,
   wallet_password      IN  VARCHAR2 DEFAULT NULL, 
  RETURN connection;

パラメータ

表279-12 OPEN_CONNECTIONファンクションのパラメータ

パラメータ 説明

remote_host

サービスを提供するホストの名前。remote_hostがNULLの場合は、ローカル・ホストに接続します。

remote_port

サービスが接続をリスニングするポート番号。

local_host

サービスを提供するホストの名前。NULLの場合は無視されます。

local_port

サービスが接続をリスニングするポート番号。NULLの場合は無視されます。

in_buffer_size

入力バッファのサイズ。入力バッファを使用すると、サーバーからデータを受信する際の実行パフォーマンスを高速化できます。バッファの適正サイズは、クライアントとサーバーの間のデータの流れや、ネットワークの通信量または待機時間によって異なります。0(ゼロ)の値は、バッファを使用しないことを意味します。NULLの値は、バッファが使用されているかどうかをコール元が無視することを意味します。入力バッファの最大サイズは、32767バイトです。

out_buffer_size

出力バッファのサイズ。出力バッファを使用すると、サーバーにデータを送信する際の実行パフォーマンスを高速化できます。バッファの適正サイズは、クライアントとサーバーの間のデータの流れやネットワーク条件によって異なります。0(ゼロ)の値は、バッファを使用しないことを意味します。NULLの値は、バッファが使用されているかどうかをコール元が無視することを意味します。出力バッファの最大サイズは、32767バイトです。

charset

回線用文字セット。データベース内のテキスト・メッセージは、回線上とは異なる文字セット(つまり、通信プロトコルで指定されている文字セットや通信上の他の終端で規定されている文字セットなど)にコード化されている可能性があります。したがって、ネットワーク上での送受信時には、READ_TEXT、READ_LINE、WRITE_TEXTおよびWRITE_LINEを使用して、データベース内のテキスト・メッセージと回線用文字セットの間の変換が行われます。変換が不要な場合は、このパラメータをNULLに設定します。

newline

改行文字列。この改行文字列は、WRITE_LINE APIで送信されるテキスト行に追加されます。

tx_timeout

この接続で読込みまたは書込み操作を中止するまでのUTL_TCPパッケージの待機時間(秒)。読込み操作の場合、読み込めるデータがない場合に操作が即座に中止されます。書込み操作の場合、出力バッファがフルで、ブロックされずにネットワークに送信できるデータがない場合に操作が中止されます。0(ゼロ)は、まったく待機しないことを示します。NULLは、無期限に待機することを示します。

wallet_path

SSL/TLS用のOracle Walletを含むディレクトリ・パス。形式はfile: directory-pathです。

wallet_password

Walletをオープンするためのパスワード。Walletの自動ログインが有効の場合は、パスワードをNULLに設定できます。

戻り値

目的の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による書込み操作の制御は行われません。

例

DECLARE
  c UTL_TCP.CONNECTION;
BEGIN
  c := UTL_TCP.OPEN_CONNECTION(
   host            => 'www.example.com',
   port            => 443, 
   wallet_path     => 'file:/oracle/wallets/smtp_wallet',
   wallet_password => '****');
  UTL_TCP.SECURE_CONNECTION (c => c);
END;

279.7.11 READ_LINEファンクション

このファンクションは、オープン接続中のサービスからテキスト行を受信します。

行は、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;

パラメータ

表279-13 READ_LINEファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

data

受信データ。

remove_crlf

TRUEの場合は、後に続く1つ以上のCRLF文字が受信メッセージから削除されます。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

戻り値

受信したデータの文字数。

使用上のノート

接続は、OPEN_CONNECTION. へのコールを介してすでにオープン状態になっている必要がありますこのファンクションは、行の終わりまたは入力の最後に達するまで戻りません。テキスト・メッセージは、コール元に戻される前に、接続のオープン時に指定した回線用文字セットからデータベース文字セットに変換されます。

接続がオープンされたときに転送のタイムアウトが設定されている場合、このファンクションは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれる準備を完了するのを待機します。タイムアウトが発生すると、このファンクションは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

マルチバイト文字の一部が入力の終わりで検出された場合、このファンクションは読込みを中止し、完全に読み込まれたマルチバイト文字をすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char例外が発生します。READ_RAWファンクションを使用して例外を処理し、部分的なマルチバイト文字のバイトをバイナリとして読み込むことができます。マルチバイト文字の一部が渡されていない状態でタイムアウトが発生したため、マルチバイト文字の残りの部分が入力途中で表示された場合は、そのかわりにtransfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

279.7.12 READ_RAWファンクション

このファンクションは、オープン接続中のサービスからバイナリ・データを受信します。

構文

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;

パラメータ

表279-14 READ_RAWファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

data (IN OUT COPY)

受信データ。

len

受信するデータのバイト数。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを前もって確認、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合があります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン前に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

戻り値

受信したデータのバイト数。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。このファンクションは、指定したバイト数が読み込まれるまで、または入力の最後に達するまで戻りません。

接続がオープンされたときに転送のタイムアウトが設定されている場合、このファンクションは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれる準備を完了するのを待機します。タイムアウトが発生すると、このファンクションは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

279.7.13 READ_TEXTファンクション

このファンクションは、オープン接続中のサービスからテキスト・データを受信します。

構文

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;

パラメータ

表279-15 READ_TEXTファンクションのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

data

受信データ。

len

受信データの文字数。

peek

通常、ユーザーはデータを読み込むとそのデータを入力キューから削除、つまり消費しようとします。しかし、入力キューからデータを削除しないで、単にデータを先読み、つまり覗くだけにし、次回コール時にも依然としてそのデータが読込み可能な(または覗ける)状態にしておくことが望ましい場合もあります。入力キューにデータを保持するには、このフラグをTRUEに設定し、接続のオープン時に入力バッファをセットアップする必要があります。覗く(つまり、読み込んでも入力キューに保持)ことができるデータ量は、入力バッファ・サイズより小さくしてください。

戻り値

受信したデータの文字数。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。このファンクションは、指定した文字数が読み込まれるまで、または入力の最後に達するまで戻りません。テキスト・メッセージは、コール元に戻される前に、接続のオープン時に指定した回線用文字セットからデータベース文字セットに変換されます。

明示的に上書きされた場合を除き、VARCHAR2バッファのサイズはバイト数で指定されます。これに対し、lenパラメータは読み取られる最大文字数を参照します。データベース文字セットにマルチバイトが設定されていると、単一の文字が複数のバイトで構成されている場合は、バッファが最大文字数を保持できることを確認する必要があります。一般に、VARCHAR2バッファのサイズは、読み取られる文字数にデータベース文字セットの1文字の最大バイト数を乗算した数と等しくする必要があります。

接続がオープンされたときに転送のタイムアウトが設定されている場合、このファンクションは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれる準備を完了するのを待機します。タイムアウトが発生すると、このファンクションは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

マルチバイト文字の一部が入力の終わりで検出された場合、このファンクションは読込みを中止し、完全に読み込まれたマルチバイト文字をすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char例外が発生します。READ_RAWファンクションを使用して例外を処理し、部分的なマルチバイト文字のバイトをバイナリとして読み込むことができます。マルチバイト文字の一部が渡されていない状態でタイムアウトが発生したため、マルチバイト文字の残りの部分が入力途中で表示された場合は、そのかわりにtransfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

279.7.14 SECURE_CONNECTIONプロシージャ

このプロシージャは、SSL/TLSを使用してTCP/IP接続を保護します。

SSL/TLSでは、OPEN_CONNECTIONファンクションによる接続のオープン時に指定する必要のあるOracle Walletが要求されます。

構文

UTL_TCP.SECURE_CONNECTION (
   c    IN OUT NOCOPY connection);

パラメータ

表279-16 SECURE_CONNECTIONプロシージャのパラメータ

パラメータ 説明

c

データの受信元TCP接続。

279.7.15 WRITE_LINEファンクション

このファンクションは、オープン接続中のサービスにテキスト行を送信します。送信前に、newline文字列がメッセージに追加されます。

構文

UTL_TCP.WRITE_LINE (
   c    IN OUT NOCOPY connection,
   data IN            VARCHAR2 DEFAULT NULL CHARACTER SET ANY_CS) 
  RETURN PLS_INTEGER;

パラメータ

表279-17 WRITE_LINEファンクションのパラメータ

パラメータ 説明

c

データの送信先TCP接続。

data

送信するデータを含んだバッファ。

戻り値

実際に送信したデータの文字数。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。テキスト・メッセージは、回線に送信される前に、接続のオープン時に指定した回線用文字セットに変換されます。

279.7.16 WRITE_RAWファンクション

このファンクションは、オープン接続中のサービスにバイナリ・メッセージを送信します。指定されたバイト数が書き込まれるまで、何も戻されません。

構文

UTL_TCP.WRITE_RAW (
   c    IN OUT NOCOPY connection,
   data IN            RAW,
   len  IN            PLS_INTEGER DEFAULT NULL) 
 RETURN PLS_INTEGER;

パラメータ

表279-18 WRITE_RAWファンクションのパラメータ

パラメータ 説明

c

データの送信先TCP接続。

data

送信するデータを含んだバッファ。

len

送信するデータのバイト数。lenがNULLの場合は、データの長さ全体が書き込まれます。

戻り値

送信したデータのバイト数。

使用上のノート

接続は、OPEN_CONNECTIONへのコールを介してすでにオープン状態になっている必要があります。

279.7.17 WRITE_TEXTファンクション

このファンクションは、オープン接続中のサービスにテキスト・メッセージを送信します。

構文

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;

パラメータ

表279-19 WRITE_TEXTファンクションのパラメータ

パラメータ 説明

c

データの送信先TCP接続。

data

送信するデータを含んだバッファ。

len

送信するデータの文字数。lenがNULLの場合は、データの長さ全体が書き込まれます。実際に書き込まれるデータ量は、ネットワーク条件のために削減される可能性があります。

戻り値

実際に送信したデータの文字数。

使用上のノート

接続は、OPEN_CONNECTION. へのコールを介してすでにオープン状態になっている必要がありますテキスト・メッセージは、回線に送信される前に、接続のオープン時に指定した回線用文字セットに変換されます。