PARAM タグ

アナリティクス スクリプトのための入力パラメーターを作成し、その入力値の要件を定義します。

入力パラメーターは、ユーザーがアナリティクス スクリプトを実行またはスケジュールする際に使用する実際の値を指定できるようにするプレースホルダーです。

構文

//PARAM variable_nametype <OPTIONAL> <MULTI> <SEPARATOR value> <QUALIFIER value> <VALUES value_list> label
  <説明>

パラメーター

名前 説明
変数名

ユーザーによって選択または指定された入力値を格納する変数の名前。変数名をアナリティクス スクリプト内で使用することで、入力値を参照できます。

例：

  • v_start_date
  • v_regions
  • v_input_file

パラメーターの一意の識別子にもなります。

メモ

アナリティクス スクリプトが実行されたとき、ユーザーが入力値を提供する場合にのみ、この変数は作成されます。パラメーターが省略可能で、ユーザーが入力をスキップした場合、変数は作成されません。

アナリティクス スクリプトの以降のロジックで変数の存在が必要となる場合は、変数の存在をテストすることができるので、存在しなければ、変数を作成して初期化します。詳細については、省略可能な入力パラメーターの設計を参照してください。

パラメーター変数名でサポートされていない文字

変数名にはスペースを使用しないでください。

変数名では次の文字を使用しないでください。次の文字はサポートされていません。

` ~ ! @ # $ % ^ & * ( ) - + = { } [ ] | \ : ; ' " < > , . / ?
種類

パラメーターのデータ型。これにより、入力できる入力値の種類を制御します。

次の型を、大文字を使用して指定することができます。

  • C – 文字データ
  • N – 数値データ
  • D - 日付時刻データの日付サブタイプ
  • DT- 日付時刻データの日付時刻サブタイプ
  • T - 日付時刻データの時刻サブタイプ
  • L – 論理データ

メモ

アナリティクス スクリプトが正常に実行されるようにするには、文字の入力値を修飾することが必要です。
OPTIONAL

省略可能

パラメーターは任意であり、ユーザーは値を入力しなくてもいいことを示します。

詳細については、省略可能な入力パラメーターの設計を参照してください。
MULTI

省略可能

パラメーターは複数の入力値を受け入れることを示します。

メモ

MULTI は、型が L（論理名）または F（ファイル）の場合には使用できません。

MULTI と VALUES

MULTI は、 VALUES オプションの有無にかかわらず使用できます。

MULTI

VALUES

ユーザーは値のリストから 1 つ以上の値を選択できます。

MULTI

VALUES

ユーザーは 1 つ以上の値を手動で入力できます。

詳細については、MULTI および VALUES オプションの要約を参照してください。

複数文字入力値

MULTI を指定し、型が C（文字）である場合は、入力値の文字列に区切り文字とテキスト修飾子が自動的に挿入されるよう、SEPARATOR と QUALIFIER オプションを指定することもできます。

メモ

アナリティクス スクリプトが正常に実行されるようにするには、複数の文字の入力値を区切ったり修飾したりすることが必要です。区切り文字および修飾子は自動的に挿入するか、ユーザーが手動で挿入できます。
SEPARATOR 値

省略可能

SEPARATOR は、MULTI が指定され、型が C（文字）も場合にのみ使用できます。

処理するアナリティクス スクリプトに渡される区切り文字付きの一覧を作成するときに、複数の文字入力値の間に区切り文字を自動的に挿入することを指定します。

値には、使用する区切り文字を指定します。よく使われる分離記号、すなわち区切り文字はカンマ,です。

SEPARATOR を省略した場合は、デフォルトで、1 つのスペースが区切り文字として使用されます。スペース文字を値として指定することはできません。

詳細については、文字入力値の区切りと修飾を参照してください。
QUALIFIER 値

省略可能

QUALIFIER は、MULTI が指定され、型が C（文字）も場合にのみ使用できます。

処理するアナリティクス スクリプトに渡される区切り文字付きの一覧を作成するときに、各文字入力値の始まりと終わりにテキスト修飾子の文字を自動的に挿入することを指定します。修飾子文字内に囲まれたあらゆるテキストが、プレーン テキストとして扱われます。

値には、使用する修飾子文字を指定します。よく使われる修飾子は一重引用符'です。

QUALIFIER を省略した場合に使用されるデフォルトの修飾子はありません。スペース文字を値として指定することはできません。

詳細については、文字入力値の区切りと修飾を参照してください。

メモ

アナリティクスの入力パラメーターは現在のところ、テキスト修飾子として二重引用符（"）の使用をサポートしていません。代わりに、一重引用符（'）を使用することができます。二重引用符を指定すると、PARAM タグが正しく動作しなくなります。
VALUES 値リスト

省略可能

ユーザーがアナリティクス スクリプトを実行するときに選択できる値のリスト。

次の構文を使用して、値を指定します。

VALUES |値 1|値 2|値 3|値 n|

VALUES と MULTI

VALUES は MULTI オプションの有無にかかわらず使用できます。

VALUES

MULTI

ユーザーは値のリストから 1 つ以上の値を選択できます。

VALUES

MULTI

ユーザーは値のリストから単一の値を選択できます。

詳細については、MULTI および VALUES オプションの要約を参照してください。

値リストの値の形式

文字値
  • スペースと句読点を含めることができます
数値
  • 正数でも負数でも指定できます。
  • 10 進表記法を用いて、桁区切り記号を付けないで指定する必要があります。

    例：1500.00 または -1500.00
日付時刻値
  • 日付は、書式 MM/DD/YYYY を使用して指定する必要があります

    （例：12/31/2014）

  • 日付時刻は、書式 MM/DD/YYYY hh:mm:ss を使用して指定する必要があります

    （例：12/31/2014 23:59:59）

  • 時刻は、書式 hh:mm:ss を使用して指定する必要があります（

    例：23:59:59）
論理値 VALUE は、型が L（ローカル）の場合には使用できません。
ラベル

パラメーターのユーザー インターフェイスのラベル。

ロボットで、ラベルは入力フィールドで表示されます。
説明

省略可能

パラメーターに関する詳細情報を提供する説明テキスト。

ロボットで、説明は入力フィールドで表示されます。

説明はユーザーを支援する手順を提供できます。たとえば、"給与支払期間の締切日を入力してください" などと指定します。

説明は、関連する PARAM タグより後の次の行に入力する必要があります。説明を複数行で指定することはできますが、行を飛ばすことはできません。ロボットで表示する場合には、改行は保持されません。

例

基本的な例

ユーザーが任意で日付の範囲を指定できるようにする

//PARAM v_start_date D OPTIONAL 開始日（任意）
  分析の開始日を入力します
//PARAM v_end_date D OPTIONAL 終了日（任意）
  分析の終了日を入力します

ユーザーに処理する取引の最大数を選択するように要求する

//PARAM v_maxTrans N VALUES |250|500|750|1000| 処理する最大取引数

ユーザーに商業カテゴリ コードを 1 つ以上指定するように要求する

//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' 含める MC コード
  商業カテゴリ コードを 1 つ以上指定します。コードの後に Enter を押して、各コードが新しい行に移動するようにします。コードを引用符で囲まないでください。

ユーザーに商業カテゴリ コードを 1 つ以上選択するように要求する

//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' VALUES |4121 タクシー/リムジン|5812 レストラン|5813 飲み屋 - アルコール飲料|5814 ファスト フード レストラン| 含める MC コード
  商業カテゴリ コードを 1 つ以上選択します。

高度な例

ユーザーに金額の範囲を指定するように要求する

最低金額～最高金額の範囲内に含まれる、テーブル内のレコードを分類化する必要があります。この範囲は変更される場合があるため、スクリプト作成者は、アナリティクス スクリプトを実行するユーザーがスクリプトをスケジュールまたは実行する際にこの範囲を定義できるようにする入力パラメーターを提供します。

COMMENT
//ANALYTIC テスト アナリティクス
//PARAM v_min_amount N 最低額
    最低額を入力します
//PARAM v_max_amount N 最高額
    最高額を入力します
END

CLASSIFY ON %v_FieldA% IF BETWEEN(AMOUNT, v_min_amount, v_max_amount) SUBTOTAL AMOUNT TO "Classified_%v_AnalysisTable%.FIL"

 ユーザーが任意で 1 つ以上の顧客番号を除外できるようにする

テーブル内のレコードを分類化する必要がある場合に、ユーザーに分析から特定の顧客を除外できるようにさせたいとします。

これを行うには、スクリプト作成者はオプションの文字パラメーターを提供します。作成するスクリプトでは、顧客番号の値が指定されたかどうかをテストし、指定されている場合には、指定された顧客番号を分類化コマンドの対象から除外します。

COMMENT
//ANALYTIC テスト アナリティクス
//PARAM v_cust_no C OPTIONAL MULTI SEPARATOR , QUALIFIER ' 除外する顧客番号（省略可能）
  1 つ以上の顧客番号を指定します。番号の指定後に Enter を押して、各番号を新しい行に移動します。番号を引用符で囲まないでください。
END

IF FTYPE("v_cust_no") = "U" v_cust_no = ""
GROUP IF v_cust_no = ""
  CLASSIFY ON %v_FieldA% SUBTOTAL AMOUNT TO "Classified_%v_AnalysisTable%.FIL"
ELSE
  CLASSIFY ON %v_FieldA% IF NOT MATCH(CUSTNO, %v_cust_no%) SUBTOTAL AMOUNT TO "Classified_%v_AnalysisTable%.FIL"
END

オプションのパラメーターへのデフォルト値の使用

取引レコードを結果テーブルに抽出するアナリティクス スクリプトを作成するとします。スクリプトを実行するユーザーに対し、日付範囲を提供するだけでなく、抽出するレコードをフィルターリングするためのエンティティの一覧をも提供するオプションを用意する必要があります。

そのようにするには、以下の 3 つのオプション パラメーターを作成します。

  • v_start_date
  • v_end_date
  • v_entity_list

スクリプトの冒頭の数行で、これらの値が設定されているかどうかをテストします。設定されていない場合は、最早日付および最遅日付のデフォルト値と、v_entity_list に対してテストするというデフォルト フラグを設定します。

EXTRACT コマンドでは、レコードをフィルターリングする値を使用します。

COMMENT
//ANALYTIC テスト
  このアナリティクス スクリプトは PARAM をテストします
//RESULT TABLE t_results
//PARAM v_start_date D OPTIONAL 開始日を入力
//PARAM v_end_date D OPTIONAL 終了日を入力
//PARAM v_entity_list C MULTI OPTIONAL |entity1|entity2|
END

IF NOT ISDEFINED("v_start_date") v_start_date = `19000101`
IF NOT ISDEFINED("v_end_date") v_end_date = `99991231`
IF NOT ISDEFINED("v_entity_list") v_entity_list = "'all'"

EXTRACT FIELDS ALL TO t_results IF BETWEEN(transaction_date v_start_date v_end_date) AND (MATCH(entity_field %v_entity_list%) OR v_entity_list = "'all'")

備考

省略可能な入力パラメーターの設計

PARAM タグで OPTIONAL を使用した場合、その入力パラメーターに関連付けられた変数は、アナリティクス スクリプトの実行時に作成されるかどうかわかりません。

  • ユーザーが入力値を指定した場合は、変数が自動的に作成されます
  • ユーザーが省略可能なパラメーターをスキップし、入力値を指定しなかった場合には、変数は作成されません

パラメーター変数の存在のテスト

アナリティクス スクリプトの以降のロジックが、パラメーター変数の内容を評価できるものとしている場合は、それが空や NULL の状態を評価するものであっても、パラメーター変数の存在をテストする必要があります。パラメーター変数が存在しない場合は、作成して、ヌルに初期化する必要があります。

IF コマンドと FTYPE( ) 関数または ISDEFINED( ) 関数を使用し、テストを実行して、存在しない場合は変数を作成します。

IF FTYPE("変数名") = "U" 変数名 = ""
IF NOT ISDEFINED("var_name") var_name =""

テストを実行するとき

アナリティクス ヘッダーより後、パラメーター変数の存在に依存する Analytics スクリプトのロジックより前に、テストを実行します。

MULTI および VALUES オプションの要約

以下の表は、ユーザー インターフェイスのユーザー入力コントロールに対する、MULTI および VALUE オプションの効果の要約です。

ユーザー入力コントロール（ロボット）

パラメーター設計

MULTI

VALUES

フィールドに単一の入力値を手動で入力する

フィールドに 1 つ以上の入力値を手動で入力する

値のドロップダウンリストから選択された単一の入力値

チェックリストの値から 1 つ以上の入力値を選択する

文字入力値の区切りと修飾

文字入力値が複数存在する場合は、値を区切り文字で区切る必要があります。また、アナリティクス スクリプトを正常に実行させるために、値を修飾する必要があります。

入れ子になったテキスト修飾子を使用しない

文字の入力パラメーターを作成するとき、またアナリティクス スクリプトを実行するユーザーに文字入力値の入力方法を指示するときには、余分なテキスト修飾子、つまり入れ子になったテキスト修飾子（修飾子の中の修飾子）を作成しないように注意する必要があります。余分なテキスト修飾子により、入力パラメーターが正しく動作しなくなります。

テキスト修飾子を挿入する方法

文字入力値の前後にテキスト修飾子を挿入するための方法は 4 種類あります。方法によっては、入力値の間に区切り文字も挿入されます。

アナリティクス スクリプトを開発するときには、別の方法で実験し、ユーザーが入力する文字値に適切なものを見つけなければならない場合があります。

メモ

MULTI オプションと VALUES オプションをどのように使用しているかによって、1 つまたは複数の方法を適用できない場合があります。

各入力パラメーターはこれらの方法の 1 つのみを使用する必要があります。

  方法 説明
1 SEPARATOR および QUALIFIER を使用する

PARAM タグに SEPARATOR および QUALIFIER オプションを含めます。

例：

//PARAM v_regions C MULTI SEPARATOR , QUALIFIER '

MULTI なしで VALUES を使用する場合は適用されません。

ヒント

可能な限り、この方法を使用します。これは、必要とする労力が最も少なく、また、エラーを起こす度合いが最も低いです。
2 区切り文字と修飾子を手動で指定する

アナリティクス スクリプトのユーザーに、実際の入力値に加えて区切り文字と修飾子を手動で指定するように要求します。

例：

'North America','Europe','Asia'

MULTI の有無にかかわらず、VALUES を使用する場合は適用されません。
3 値リストに修飾子を含める

VALUES オプションと一緒に指定される値リストの各値に修飾子を含めます。

例：

VALUES |'Asia'|'Europe'|'Middle East'|'North America'|

VALUES なしで MULTI を使用する場合は適用されません。
4 パラメーター変数を修飾子で囲む

Analytics スクリプトの構文で、パラメーター変数をテキスト修飾子で囲みます。

例：

IF MATCH(REGIONS, "%v_regions%")

この方法は、MULTI なしで VALUES を使用している場合にのみ使用します。
 

メモ

アナリティクスの入力パラメーターは現在のところ、テキスト修飾子として二重引用符（"）の使用をサポートしていません。その代わりに、値リストで、あるいは入力値の前後に手動で修飾子を指定するときは、QUALIFIER オプションによって一重引用符（'）を使用できます。二重引用符は、Analytics スクリプトの本文ではテキスト修飾子として使用できます。

別の方法を使用するとき

以下の表には、テキスト修飾子を挿入するさまざまな方法をどのような場合に使用するかまとめてあります。

 

MULTI

VALUES

MULTI

VALUES

MULTI

VALUES

方法 1

SEPARATOR および QUALIFIER オプションを使用する

使用した場合は、方法 2 を使用しない

該当なし

使用した場合は、方法 3 を使用しない

方法 2

区切り文字と修飾子を手動で指定する

使用した場合は、方法 1 を使用しない

該当なし

該当なし

方法 3

値リストに修飾子を含める

該当なし

使用した場合は、方法 4 を使用しない

使用した場合は、方法 1 を使用しない

方法 4

パラメーター変数を修飾子で囲む

使用しない

使用した場合は、方法 3 を使用しない

使用しない