Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 11.0.1 (日本語) » SQL Anywhere サーバ - プログラミング » SQL Anywhere データ・アクセス API » SQL Anywhere 外部環境のサポート

 

PHP 外部環境

SQL Anywhere では、PHP ストアド・プロシージャおよび関数をサポートしています。PHP ストアド・プロシージャまたは関数の動作は、SQL ストアド・プロシージャまたは関数と同じです。ただし、プロシージャまたは関数のコードは PHP で記述され、その実行はデータベース・サーバの外側 (つまり PHP 実行インスタンス内) で行われます。PHP 実行ファイルのインスタンスは、PHP ストアド・プロシージャおよび関数を使用する接続ごとに存在します。この動作は、Java ストアド・プロシージャおよび関数と異なります。Java の場合、接続ごとに 1 つのインスタンスではなく、各データベースの Java VM に 1 つのインスタンスがあります。PHP と Java のもう 1 つの大きな相違点は、PHP ストアド・プロシージャは結果セットを返さないのに対し、Java ストアド・プロシージャは結果セットを返すことができる点です。PHP で返すのは、PHP スクリプトの出力である LONG VARCHAR 型のオブジェクトだけです。

データベースでの PHP のサポートを使用するためには、次の 2 つの前提条件があります。

  1. PHP のコピーをデータベース・サーバ・コンピュータにインストールする必要があります。また、SQL Anywhere データベース・サーバで PHP 実行ファイルを検出できることが必要です。

  2. SQL Anywhere PHP ドライバ (SQL Anywhere に付属) が、データベース・サーバ・コンピュータにインストールされていることが必要です。SQL Anywhere PHP のインストールと設定を参照してください。

上記 2 つの前提条件に加え、データベース管理者は SQL Anywhere PHP 外部環境モジュールをインストールする必要もあります。SQL Anywhere 配布には、いくつかのバージョンの PHP のビルド済みモジュールが含まれています。ビルド済みモジュールをインストールするには、適切なドライバ・モジュールを php.ini で指定されている PHP 拡張ディレクトリにコピーします。UNIX では、シンボリック・リンクを使用することもできます。

♦  外部環境モジュールをインストールするには、次の手順に従います (Windows の場合)。
  1. PHP インストール・ディレクトリにある php.ini ファイルを探して、テキスト・エディタで開きます。extension_dir ディレクトリのロケーションを指定する行を探します。extension_dir に特定のディレクトリが設定されていない場合は、システム・セキュリティの安全上、独立したディレクトリを指定することをおすすめします。

  2. 目的の外部環境 PHP モジュールを、SQL Anywhere のインストール・ディレクトリから PHP の拡張ディレクトリにコピーします。使用するモデルは、次のとおりです。

    copy install-dir\Bin32\php-5.2.6_sqlanywhere_extenv11.dll
      php-dir\ext
  3. SQL Anywhere PHP ドライバも、SQL Anywhere のインストール・ディレクトリから PHP の拡張ディレクトリにインストールされていることを確認します。ファイル名は php-5.x.y_sqlanywhere.dll のようになります (x および y はバージョン番号を表します)。ステップ 2 でコピーしたファイルのバージョン番号と一致する必要があります。

♦  外部環境モジュールをインストールするには、次の手順に従います (UNIX の場合)。
  1. PHP インストール・ディレクトリにある php.ini ファイルを探して、テキスト・エディタで開きます。extension_dir ディレクトリのロケーションを指定する行を探します。extension_dir に特定のディレクトリが設定されていない場合は、システム・セキュリティの安全上、独立したディレクトリを指定することをおすすめします。

  2. 目的の外部環境 PHP モジュールを、SQL Anywhere のインストール・ディレクトリから PHP のインストール・ディレクトリにコピーします。使用するモデルは、次のとおりです。

    cp install-dir/bin32/php-5.2.6_sqlanywhere_extenv11.so
      php-dir/ext
  3. SQL Anywhere PHP ドライバも、SQL Anywhere のインストール・ディレクトリから PHP の拡張ディレクトリにインストールされていることを確認します。ファイル名は php-5.x.y_sqlanywhere.so のようになります (x および y はバージョン番号を表します)。ステップ 2 でコピーしたファイルのバージョン番号と一致する必要があります。

データベースでの Perl のサポートを使用できるのは、SQL Anywhere バージョン 11 以降のデータベースのみです。SQL Anywhere 10 データベースがロードされている場合、データベースでの PHP のサポートを使用しようとすると、外部環境がサポートされていないことを示すエラーが返されます。

PHP をデータベースで使用するには、データベース・サーバが PHP 実行ファイルを検出して開始できる必要があります。データベース・サーバが PHP 実行ファイルを検出して開始できるかどうかを確認するには、次の文を実行します。

START EXTERNAL ENVIRONMENT PHP;

「外部実行ファイル」が見つからないというメッセージが表示された場合、問題の原因はデータベース・サーバが PHP 実行ファイルを検出できていないことにあります。この場合は、ALTER EXTERNAL ENVIRONMENT 文を実行し、PHP 実行ファイルのロケーション (実行ファイル名も含む) を明示的に設定するか、PHP 実行ファイルがあるディレクトリが PATH 環境変数に含まれていることを確認する必要があります。

ALTER EXTERNAL ENVIRONMENT PHP 
  LOCATION 'php-path';

次に例を示します。

ALTER EXTERNAL ENVIRONMENT PHP
  LOCATION 'c:\\php\\php-5.2.6-win32\\php.exe';

デフォルト設定に戻すには、次の文を実行します。

ALTER EXTERNAL ENVIRONMENT PHP
  LOCATION 'php';

「メイン・スレッド」が見つからないというメッセージが表示された場合は、次のことを確認します。

START EXTERNAL ENVIRONMENT PHP 文は、データベース・サーバが PHP を開始できるかどうかを確認する以外で使用することはありません。通常、PHP ストアド・プロシージャまたは関数を呼び出すと、PHP は自動的に開始されます。

これと同様に、PHP のインスタンスを停止するために STOP EXTERNAL ENVIRONMENT PHP 文を使用する必要もありません。インスタンスは、接続が切断されると自動的に停止します。ただし、PHP をこれ以上使用することがなく、一部のリソースを解放する必要がある場合は、STOP EXTERNAL ENVIRONMENT PHP 文を使用して接続のための PHP インスタンスを解放します。

データベース・サーバが PHP 実行ファイルを開始できることを確認したら、次に必要な PHP コードをデータベースにインストールします。これは、INSTALL 文を使用して行います。たとえば、次の文を実行して、特定の PHP スクリプトをデータベースにインストールできます。

INSTALL EXTERNAL OBJECT 'php-script' 
  NEW 
  FROM FILE 'php-file'
  ENVIRONMENT PHP;

PHP コードは、次のようにして式から構築してインストールすることもできます。

INSTALL EXTERNAL OBJECT 'php-script' 
  NEW
  FROM VALUE 'php-statements'
  ENVIRONMENT PHP;

PHP コードは、次のようにして変数から構築してインストールすることもできます。

CREATE VARIABLE PHPVariable LONG VARCHAR;
SET PHPVariable = 'php-statements';
INSTALL EXTERNAL OBJECT 'php-script' 
  NEW 
  FROM VALUE PHPVariable
  ENVIRONMENT PHP;

PHP コードをデータベースから削除するには、次のように REMOVE 文を使用します。

REMOVE EXTERNAL OBJECT 'php-script';

既存の PHP コードを変更するには、次のように INSTALL 文の UPDATE 句を使用します。

INSTALL EXTERNAL OBJECT 'php-script' 
  UPDATE 
  FROM FILE 'php-file'
  ENVIRONMENT PHP;
INSTALL EXTERNAL OBJECT 'php-script' 
  UPDATE 
  FROM VALUE 'php-statements'
  ENVIRONMENT PHP;
SET PHPVariable = 'php-statements';
INSTALL EXTERNAL OBJECT 'php-script' 
  UPDATE 
  FROM VALUE PHPVariable
  ENVIRONMENT PHP;

PHP コードがデータベースにインストールされたら、次に必要な PHP ストアド・プロシージャおよび関数を作成できます。PHP ストアド・プロシージャおよび関数を作成するときは、LANGUAGE に必ず PHP を指定します。また、EXTERNAL NAME 文字列には、PHP サブルーチンを呼び出し、OUT パラメータを返すために必要な情報が含まれています。

引数は $argv 配列で PHP スクリプトに渡されます。これは、PHP がコマンド・ラインから引数を受け取る方法 ( $argv[1] が最初の引数) に似ています。出力パラメータを設定するには、出力パラメータを適切な $argv 要素に割り当てます。戻り値は、常にスクリプトの出力 (LONG VARCHAR) です。

PHP ストアド・プロシージャは、入出力の引数にあらゆるデータ型セットを指定して作成できます。ただし、PHP スクリプト内で使用されるために、パラメータは boolean、integer、double、または string の間で変換されます。戻り値は、常に LONG VARCHAR 型のオブジェクトです。簡単な PHP の例を次に示します。

INSTALL EXTERNAL OBJECT 'SimplePHPExample' 
  NEW 
  FROM VALUE '<? function SimplePHPFunction(
    $arg1, $arg2, $arg3, $arg4 ) 
    { return ($arg1 * 1000) + 
      ($arg2 * 100) + 
      ($arg3 * 10) + 
      $arg4; 
    } ?>'
  ENVIRONMENT PHP;

CREATE FUNCTION SimplePHPDemo( 
  IN thousands INT, 
  IN hundreds INT, 
  IN tens INT, 
  IN ones INT) 
RETURNS LONG VARCHAR
EXTERNAL NAME '<file=SimplePHPExample> print SimplePHPFunction(
    $argv[1], $argv[2], $argv[3], $argv[4]);' 
LANGUAGE PHP;

// The number 1234 should appear
SELECT SimplePHPDemo(1,2,3,4);

PHP では、EXTERNAL NAME 文字列は 1 行の SQL 文で指定されます。

サーバ側の PHP を使用するには、PHP コードでデフォルトのデータベース接続を使用します。データベース接続のハンドルを取得するには、空の文字列引数 ('' または "") を指定して sasql_pconnect を呼び出します。空の文字列引数を指定することで、新しい外部環境接続を開くのではなく、現在の外部環境接続を返すように SQL Anywhere PHP ドライバに伝えます。次の例では、テーブルを作成してから PHP ストアド・プロシージャを呼び出して、テーブルにデータを移植します。

CREATE TABLE phpTab(c1 int, c2 char(128));

INSTALL EXTERNAL OBJECT 'ServerSidePHPExample' 
  NEW 
  FROM VALUE '<? function ServerSidePHPSub() { 
    $conn = sasql_pconnect( '''' ); 
    sasql_query( $conn,
    "INSERT INTO phpTab 
       SELECT table_id, table_name FROM SYS.SYSTAB" );
    sasql_commit( $conn ); 
  } ?>'
  ENVIRONMENT PHP;

CREATE PROCEDURE PHPPopulateTable() 
EXTERNAL NAME '<file=ServerSidePHPExample> ServerSidePHPSub()'
LANGUAGE PHP;

CALL PHPPopulateTable();

// The following should return 2 identical rows
SELECT count(*) FROM phpTab 
UNION ALL 
SELECT count(*) FROM SYS.SYSTAB;

PHP では、EXTERNAL NAME 文字列は 1 行の SQL 文で指定されます。上の例では、SQL での引用符の解析方法に従って、単一引用符が二重になっています。PHP ソース・コードがファイル内にある場合は、単一引用符を二重にしません。

エラーをデータベース・サーバに戻すには、PHP 例外をスローします。次の例は、これを行う方法を示します。

CREATE TABLE phpTab(c1 int, c2 char(128));

INSTALL EXTERNAL OBJECT 'ServerSidePHPExample' 
  NEW 
  FROM VALUE '<? function ServerSidePHPSub() {
    $conn = sasql_pconnect( '''' );
    if( !sasql_query( $conn,
      "INSERT INTO phpTabNoExist
         SELECT table_id, table_name FROM SYS.SYSTAB" )
    ) throw new Exception(
      sasql_error( $conn ),
      sasql_errorcode( $conn )
    );
    sasql_commit( $conn );
  } ?>'
  ENVIRONMENT PHP;

CREATE PROCEDURE PHPPopulateTable()
  EXTERNAL NAME
    '<file=ServerSidePHPExample> ServerSidePHPSub()'
  LANGUAGE PHP;

CALL PHPPopulateTable();

上の例は、テーブル phpTabNoExist が見つからないことを示す SQLE_UNHANDLED_EXTENV_EXCEPTION エラーで終了します。

データベースでの PHP サポートの使用に関する詳細および例については、samples-dir\SQLAnywhere\ExternalEnvironments\PHP ディレクトリのサンプルを参照してください。