4.16.9 SQLクエリーの実行
機能
ODBCを利用してDBサーバに接続し,任意のSQL文を発行します。
プロパティ「クエリーファイルパス(リモート)」(database.queryFilePath)に指定したテキストファイル(以降,「クエリーファイル」と呼びます)からSQL文を読み込んで1つずつ実行し,結果をプロパティ「出力先フォルダパス(リモート)」(database.outputFolderPath)が示すフォルダにCSVファイルとして出力します。ファイル名は,「SQLRES_<3桁の連番>.csv」です。
例:SQLRES_001.csv
クエリーファイル内のSQL文は1行1SQL文とし,かつ999行以下にしてください。
クエリーファイルに複数のSQL文が記述された場合は,結果も複数のCSVファイルに分割して出力します。
参照系のSQL文の実行結果は,CSVファイルの最初にヘッダ行を出力したあとに続けて出力します。また,文字エンコーディングについてはDB操作サーバのデフォルトで出力します。
更新系のSQL文については結果を何も出力せず,ファイルも作成しません。更新系のSQL文に対応するファイル名の連番は,詰めずに欠番として扱います。
入力のクエリーファイルと出力のCSVファイルの例を次に示します。
入力例:
Select * from TBL_APP_USERS ・・・ (1行目)
Insert into TBL_APP_USERS(ID,NAME,DISCRIPT) Values(888,'日立 八郎','新しい人です') ・・・ (2行目)
Select * from TBL_APP_USERS ・・・ (3行目)
出力例:
SQLRES_001.csv (1行目の実行結果)
ID,NAME,DISCRIPT
111,日立 太郎,サンプル1
222,日立 次郎,サンプル2
SQLRES_003.csv (3行目の実行結果)
ID,NAME,DISCRIPT
111,日立 太郎,サンプル1
222,日立 次郎,サンプル2
888,日立 八郎,新しい人です
このドキュメント内で使用しているODBCに関する用語は,「ODBCデータソースアドミニストレーター」で使用されている表示名です。ODBCに関する用語を次に示します。
・ODBCデータソースアドミニストレーター
Windowsに標準のツールです。データソースの作成と管理に使います。
・データソース
DBサーバに接続するために必要な情報を集めたものです。
「ODBCデータソースアドミニストレーター」で作成します。
・データソース名(DSN)
データソースの識別名です。
「ODBCデータソースアドミニストレーター」ではデータソース名またはDSNと記載されています。
・ODBCドライバー
「ODBCデータソースアドミニストレーター」ではODBCドライバー,または単にドライバーと記載されています。
この部品が前提とするサーバを次に示します。
・DB操作サーバ(実行対象サーバ)
DBサーバに接続しODBCコマンドを実行するサーバです。
・DBサーバ
対象のDBMSがインストールされているサーバです。
利用場面
この部品は,DBに登録されている情報へユーザーが任意のSQLを用いてアクセスする場合などに使用できます。
前提条件
【システム内前提製品】/【実行対象システム内前提製品】/【実行対象システム内前提製品の稼働OS】の最新のサポート状況については,リリースノートを参照してください。
【システム内前提製品】
JP1/Automatic Operation 11-00以降
【実行対象システム内前提製品】
(1)DBサーバ
・Oracle 10g Standard/Enterprise
・Oracle 11g Standard/Enterprise
・Oracle 12c Standard/Enterprise
(2)DB操作サーバ
・Microsoft .Net Framework 2.0以降
・DBサーバのDBMSに対応した32bit版ODBCドライバー
【実行対象システム内前提製品の稼働OS】
(1)DBサーバ
・DBMSの要求を満たすもの。
(2)DB操作サーバ
・Windows Server 2008 R2 Standard/Enterprise/Datacenter
・Windows Server 2012 Standard/Datacenter,Windows Server 2012 R2 Standard/Enterprise/Datacenter
ただし,Server Coreインストール環境は除く。
【実行対象システム内前提製品の使用条件】
(1)ネットワーク構成に関する条件
・DB操作サーバからDBサーバへ,ODBC接続が可能であること。
(2)ODBCに関する条件
・DB操作サーバにODBCドライバが正常にインストール済みであること。
・DB操作サーバにおいて,ODBCデータソースアドミニストレータでデータソースが作成済みであること。
・作成したデータソースの各種設定は正常に完了しており,そのデータソースを用いてDBサーバへの接続を確認済みであること。
注意事項
(1) プロパティ「クエリーファイルパス(リモート)」(database.queryFilePath)に指定したテキストファイル(以降,「クエリーファイル」と呼びます)の1行に複数のSQL文が記述された場合,この部品は異常終了します。
(2) プロパティ「エンコード種別」(common.encodeType)に指定したエンコード種別は,クエリーファイルのエンコード種別とDBに設定しているエンコード種別との両方と一致している必要があります。DBのエンコード種別について詳しくはODBCドライバーとDBMSの仕様を確認してください。
(3) プロパティ「出力先フォルダパス(リモート)」(database.outputFolderPath)に指定したフォルダ(以降,「出力先フォルダ」と呼びます)にファイルが既にある場合,既存のファイルを上書きします。指定したフォルダパスに誤りがないか,充分に確認してください。
(4) クエリーファイルに複数のSQL文が記述されて,一部のSQLが失敗した場合は中断してロールバックし,失敗したSQL文より後ろに記述されているSQL文は実行しません。また,出力先フォルダの空き容量が不足してファイルを書き込めないような場合にも同様にロールバックし,それより後ろのSQL文は実行しません。
(5) ロールバックした場合,SQL文実行が失敗する直前までの結果が出力先フォルダに出力されます。その場合,不完全なCSVファイルが出力されることがあります。
(6) ロールバックする前にCREATE文やALTER文やDROP文が実行されていた場合,ご使用のDBMSの仕様によってこれらの結果はロールバック後も復旧されない事があります。
(7) この部品がODBCドライバーを介してロールバックを試みても,ODBCドライバーに固有の設定をしている場合は,DBMSはデータを復元しない可能性があります。詳しくはODBCドライバーとDBMSの仕様を確認してください。
(8) この部品を利用するサービスでは,プロパティ「DBユーザーパスワード」(database.dbUserPassword)にマッピングするプロパティをパスワード型で扱ってください。
(9) セキュリティ上,クエリーファイルは,意図しない内容に書き換えられたりファイルごと差し替えられたりしないよう,適切に管理してください。併せて,使用するDBアカウントには必要最小限の権限を付与するようにしてください。
(10) データソースを作成する場合は通常,コントロールパネルの「管理ツール」からODBCデータソースアドミニストレーターを起動しますが,この部品は32bit版を扱うので,コマンドラインから絶対パス("%SystemRoot%¥SysWOW64¥odbcad32.exe")を指定して起動してください。
(11) データソースには「システムデータソース」と「ユーザーデータソース」がありますが,この部品は「システムデータソース」だけをサポートします。
(12) この部品は環境変数"SystemRoot"を参照して32bit版の"PowerShell.exe"を呼び出すため,DB操作サーバにおいてこの環境変数がOSインストール時から変更された場合,この部品が異常終了することがあります。
(13) クエリーファイルに記述されたSQL文の1行が長すぎる場合,この部品は異常終了することがあります。DB操作サーバのメモリが枯渇しない限りにおいて最大4GB/行までクエリーファイルから読み込むことができますが,それより短いSQL文でもODBCドライバーが限界を超えてしまう場合があります。詳しくはODBCドライバーとDBMSの仕様を確認してください。
(14) SQL文を実行した結果,CSVファイルの1行が長くなりすぎる場合,この部品は異常終了することがあります。DB操作サーバのメモリが枯渇しない限りにおいて最大4GB/行までCSVファイルに書き込むことができますが,それより短くてもODBCドライバーが限界を超えてしまう場合があります。詳しくはODBCドライバーとDBMSの仕様を確認してください。
(15) プロパティ「DBユーザーID」(database.dbUserId)と「DBユーザーパスワード」(database.dbUserPassword)に指定された文字列は,大文字と小文字を区別します。
バージョン
02.00.00
部品のタグ
Control Database,Windows,Oracle Database
タスクログに表示される部品の名称
dbIssueSqlQueries
戻り値
戻り値 |
説明 |
---|---|
0 |
正常 |
12 |
異常(ユーザーミス) プロパティ不正 |
23 |
異常(環境不正) 前提環境不正 |
27 |
異常(エラー内容はタスクログで確認) |
41 |
異常(部品内でエラーを検知) プロパティ未入力(部品スクリプトでエラーを検知) |
プロパティ一覧
プロパティ一覧を次の表に示します。
プロパティキー |
プロパティ名 |
説明 |
デフォルト値 |
入出力種別 |
必須区分 |
---|---|---|---|---|---|
plugin.destinationHost |
実行対象サーバのホスト名 |
この部品を実行するサーバのホスト名またはIPアドレスを指定します。IPv6アドレスには対応していません。 |
− |
入力 |
○ |
database.queryFilePath |
クエリーファイルパス(リモート) |
SQL文を記述したテキストファイルへのフルパスを1024文字以内で指定します。ファイル内には,1行に複数のSQL文を書かないでください。また,複数行にまたがるようなSQL文も書かないでください。1ファイル当たり999行を超えないようにしてください。 |
− |
入力 |
○ |
common.encodeType |
エンコード種別 |
プロパティ「クエリーファイルパス(リモート)」で指定したテキストファイルのエンコード種別名を指定します。EUC-JP,SJIS,UTF-8,UTF-16のどれかを指定できます。 |
UTF-8 |
入力 |
○ |
odbc.dataSourceName |
ODBCデータソース名 |
予めODBCデータソースアドミニストレータでDB操作サーバ上に作成したデータソースの名前を指定します。 |
− |
入力 |
○ |
database.dbUserId |
DBユーザーID |
DBサーバへログインするために用いるアカウントのIDを指定します。 |
− |
入力 |
○ |
database.dbUserPassword |
DBユーザーパスワード |
DBユーザーIDに対応するパスワードを指定します。 |
− |
入力 |
○ |
database.outputFolderPath |
出力先フォルダパス(リモート) |
SQLを実行した結果の出力先フォルダを1024文字以内のフルパスで指定します。出力ファイルは,DB操作サーバのシステムデフォルトの文字エンコードで出力されます。 |
− |
入力 |
○ |
common.returnValue |
部品の戻り値 |
この部品の戻り値が格納されます。 |
− |
出力 |
△ |