1st_Spec_Memo_HDLVAR_2nd_Edition.txt

　HDLVAR 仕様書メモ　第２版　by ONnoji
　Rev.0 2024.12.28

　この文書はINF_Framework(以降 INF_FW と表記する)の機能：HDLVAR に関する仕様メモです。

　内容は初版( Rev.0 2009.12.18 〜 Rev.9 2020.09.09 )を改訂したものである。

　■はじめに

　時の流れは早いもので、機能：HDLVARを作成して１５年経過しました。
　この度、INF_Framework の機能：HDLVARのブラシアップを行いましたので仕様書メモの第２版を書くことにしました。
　ちなみに、初版の仕様書メモはHDLVARの開発中の備忘録として書かれているので第三者には非常に読み難くい物でありました。
　そこで第２版ではダイアグラム（図示）をメインにして読み易くいたしました。(^^ゞ

　■HDLVARとは

　HDLVARとは、ウィンドウ・ハンドル番号(HDL)＋変数(VAR)の意味を込めたネーミングです。

　この機能は、主ウィンドウからモーダルなダイアログボックスを開いた時に、

　・主ウィンドウ側の指定した局所変数の値をダイアログボックスの同名変数へ値を転送する
　　もしも、ダイアログボックス側に局所変数が宣言されていない場合には局所変数が自動的に宣言される
　・ダイアログボックスの［ＯＫ］・［キャンセル］（または［×］）・［適用］ボタンの値を主ウィンドウ側の手続きの引数として返す
　・ダイアログボックスの［ＯＫ］・［適用］ボタンを実行した場合には、ダイアログボックス側の変数の値を主ウィンドウ側に転送する
　・ダイアログボックスを閉じた時に指定した主ウィンドウ側の手続き名を実行する

　なおHDLVAR機能はモードレスなダイアログボックスに対しても有効ですが、すでに開いているダイアログボックスに対しては無効です。

　なのでモードレスなダイアログボックスに対して適用する場合にも、必ず新しいダイアログボックスをオープンしてください。

　↑以上のようにHDLVARを文章で説明すると複雑で分かり難くなるので、第２版では以下のダイアグラム（図示）をご覧いただいてご理解ください。


　〔主ウィンドウ〕　　　　　　　　　　　　　　【値を渡す局所変数の指定例】
　┌───────────────────┐
　│手続き定義開始　　　　　　　　　　　　│　※１行で指定する場合　配列変数を指定する場合には、要素数も指定する　指定しない場合には未定義値
　│cmdObjectNameClick( ) 　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│　&HDLVARmStoreParameter = "整数　｛ &mIndex ｝文字列　｛ &mFieldName, &mFieldNameDim[10] ｝"
　│**HDLVARのパラメータ　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│　※複数行で指定する場合
　│**　値を渡す局所変数の指定　　　　　　│
　│&HDLVARmStoreParameter　= 文字式　　　│　&HDLVARmStoreParameter = "整数　｛ &mFieldIndex ｝"
　│　　　　　　　　　　　　　　　　　　　│　&HDLVARmStoreParameter = &HDLVARmStoreParameter + "文字列　｛ &mFieldName, &mFieldNameDim[10] ｝"
　│**　値を返す局所変数の指定　　　　　　│
　│&HDLVARmReturnParameter = 文字式　　　│　【値を返す局所変数の指定例】
　│　　　　　　　　　　　　　　　　　　　│
　│**　主ウィンドウで実行する手続き名　　│　&HDLVARmReturnParameter = "&mFieldIndex, &mFieldName, &mFieldNameDim"　※指定しない場合には未定義値
　│&procedureName = 手続き名 　　　　　　│
　│**この例では"cmdObjectNameClickReturn"│　【主ウィンドウで実行する手続き名の指定例】
　│　　　　　　　　　　　　　　　　　　　│
　│**HDLVARの引数　　　　　　　　　　　　│　&procedureName = "cmdObjectNameClickReturn"　※手続きを実行しない場合には未定義値
　│**整数　　&modalControl 　　　　　　　│
　│**文字列　&wfmFileName　　　　　　　　│　【モーダル／モードレスの指定例】
　│**文字列　&tblFileName　　　　　　　　│
　│**文字列　&procedureName　　　　　　　│　&modalControl = 1 / &modalControl = 0
　│**整数　　&hdl　　　　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│　【フォームの指定例】
　│&modalControl　= 1 　　 　　　　　　　│
　│&procedureName = 文字式 　　　　　　　│　&wfmFileName = #一括パス + "filename.wfx"
　│&wfmFileName　 = フルパスのフォーム名 │　&tblFileName = #u　　※NULLフォームの場合には未定義値
　│&tblFileName　 = #u 　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│　【HDLVARの呼び出し】
　│手続き実行　　　　　　　　　　　　　　│
　│　HDLVARprcWindowAppearVarSend( 　　　│　手続き実行　HDLVARprcWindowAppearVarSend( &modalControl, &wfmFileName, &tblFileName, &procedureName, &hdl ）
　│　　&modalControl,　　　　　　　　　　│
　│　　&wfmFileName, 　　　　　　　　　　│　　　　　〔ダイアログボックス〕
　│　　&tblFileName, 　　　　　　　　　　│　　　　　┌───────────────┬─┐
　│　　&procedureName, 　　　　　　　　　│　　　　　│　　　　　　　　　　　　　　　│×│または［Esc］
　│　　&hdl　　　　　　　　　　　　　　　│⇒⇒⇒⇒⇒│　　　　　　　　　　　　　　　└┬┤
　│　　) 　　　　　　　　　　　　　　　　│モーダル　│HDLVARが値を自動取得する変数　　││
　│　　　　　　　　　　　　　　　　　　　│　で　　　│　　　　　　　　　　　　　　　　││
　│手続き定義終了　　　　　　　　　　　　│オープン　│&HDLVARmReferWfmHdl 　　　　　　││
　└───────────────────┘　　　　　│&HDLVARmReferWfmFileName　　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│　　　　　　　　　　　　　　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│&HDLVARmDefineVariableList　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│&HDLVARmReturnVariableList　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│&HDLVARmSendProcedureName 　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│　　　　　　　　　　　　　　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│　　　　　　　　　　　　　　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│［ＯＫ］［キャンセル］［適用］　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　│　│　　　　│　　　　　│　　　││
　　　　　　　　　　　　　　　　　　　　　　　　　　　└─┼────┼─────┼───┼┘
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　│　　　　│　　　　　│　　　│
　　　　　　　　　　　　　　　　　　　　　　　　　　　　（１）　　（０）　　　（２）（未定義値）
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　│　　　　│　　　　　│　　　│
　　　　　　　　　　　　　┌───────────────┘　　　　│　　　　　│　　　│
　　　　　　　　　　　　　│　┌──────────────────┘　　　　　│　　　│
　　　　　　　　　　　　　│　│　┌──────────────────────┘　　　│
　　　　　　　　　　　　　│　│　│　┌────────────────────────┘
　　　　　　　　　　　　　│　│　│　│
　　　　　　　　　　　　　└─┴┬┴─┘
　　　　　　　　　　　　　　　　│
　　　　　　　　　（引数：０，１，２，未定義値　※［ＯＫ］ボタンだけのダイアログボックスの場合には〔注〕を参照）
　〔主ウィンドウ〕　　　　　　　│
　┌──────────────┼────┐
　│手続き定義開始　　　　　　　│　　　　│
　│cmdObjectNameClickReturn( 整数 &exit) │
　│　　　　　　　　　　　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│
　│　if ( &exit )　　　　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│
　│　　**［ＯＫ］／［適用］の処理　　　　│
　│　else　　　　　　　　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│
　│　　**［キャンセル］の処理　　　　　　│
　│　end 　　　　　　　　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│
　│　　　　　　　　　　　　　　　　　　　│
　│手続き定義終了　　　　　　　　　　　　│
　└───────────────────┘

　※〔注〕
　［ＯＫ］ボタンだけのダイアログボックスの場合には、［名札　メイン］で局所変数のオプション変数：&HDLVARmOkOnly を宣言します。

　　変数宣言　局所，整数｛ &HDLVARmOkOnly = 1 ｝
　　
　こうすると、［×］［Esc］［閉じる］等は、引数に−１（マイナス・イチ）が引き渡されます。※INF Framework Rev.114 仕様変更


　■パラメータ：&HDLVARmStoreParameter　値を渡す局所変数の指定

　主ウィンドウ側の一般手続き：cmdObjectNameClick( )にてシステム変数：&HDLVARmStoreParameter に変数名とデータ型を指定します。
　ダイアログボックス側に変数を渡さない場合には、未定義値にします。

　【書式】

　データ型｛ 変数名，変数名，… ｝データ型｛ 変数名，変数名，… ｝
　　または
　データ型｛ 変数名，変数名，… ｝,データ型｛ 変数名，変数名，… ｝

　データ型は 文字列｜数値｜通貨｜整数｜長整数｜実数｜日時｜時間 です。これ以外のキーワードは無効です。
　変数名はコンマ（，）で区切ります。コンマは全角半角のどちらでもＯＫです。
　書式は、[変数宣言]コマンドのパラメータからスコープ（[種別]）を除いたものと同じです。
　配列変数を指定する場合には、要素数も指定する。

　１行で代入する場合

　　&HDLVARmStoreParameter = "整数　｛ &mIndex ｝文字列　｛ &mFieldName, &mFieldNameDim[10] ｝"

　複数行で代入する場合

　　&HDLVARmStoreParameter = "整数　｛ &mFieldIndex ｝"
　　&HDLVARmStoreParameter = &HDLVARmStoreParameter + "文字列　｛ &mFieldName, &mFieldNameDim[10] ｝"


　■パラメータ：&HDLVARmReturnParameter　値を返す局所変数の指定

　主ウィンドウ側の cmdObjectNameClick( )で変数名を指定します。
　ダイアログボックスの変数値を取得しない場合には、未定義値にします。

　[ＯＫ]ボタンを実行してダイアログボックスを閉じる時、&HDLVARmReturnParameter で指定したダイアログボックス側のの局所変数の値が主ウィンドウ側に代入されます。
　[適用]ボタンを実行した場合には、ダイアログボックスは閉じられませんが、[ＯＫ]ボタンを実行した時と同じ動作をします。
　[キャンセル]・[×]ボタンを実行してダイアログボックスを閉じた場合には、何もしません。
　ダイアログボックスのオプション変数：&HDLVARmOkOnly = 1 の時、[×][Esc][閉じる]等は、[ＯＫ]ボタンを実行した時と同じ動作をします。※INF Framework Rev.114 仕様変更

　【書式】

　変数名，変数名，…

　変数名はコンマ（，）で区切ります。コンマは全角半角のどちらでもＯＫです。

　　&HDLVARmReturnParameter = "&mFieldIndex, &mFieldName"

　受け取る変数名が異なる場合、主ウィンドウの変数名とダイアログボックスの変数名をセミコロン（；）で区切ります。セミコロンは全角半角のどちらでもＯＫです。

　　&HDLVARmReturnParameter = "&mFieldIndexDestination；&mFieldIndexSource, &mFieldNameDestination；&mFieldNameSource"

　■手続きの引数

　値渡し　整数　　&modalControl　… 1:モーダルのダイアログボックス 0:モードレスのダイアログボックス
　値渡し　文字列　&wfmFileName 　… フルパスのフォームファイル名( .wfm )
　値渡し　文字列　&tblFileName 　… フルパスの表ファイル名( .tbl )
　値渡し　文字列　&procedureName … ダイアログボックスを閉じた時、主ウィンドウ側の[ﾀｲﾏｰ2]ｲﾍﾞﾝﾄで実行する手続き名
　参照渡　整数　　&hdl 　　　　　… モードレスのダイアログボックスの場合、HDLLNCprcWindowAppear( )のハンドル番号が返ります

　手続き実行　HDLVARprcWindowAppearVarSend( &modalControl, &wfmFileName, &tblFileName, &procedureName, &hdl )

　引数変数への代入例

　　&modalControl = 1 または &modalControl = 0

　　&procedureName = "cmdObjectNameClickReturn"　※主ウィンドウ側で手続きを実行しない場合には未定義値

　　&wfmFileName = #一括パス + "filename.wfx"
　　&tblFileName = #u　　※NULLフォームの場合には未定義値

　　&hdl は変数を宣言していればＯＫで、代入は不要


　■主ウィンドウ側の手続きのサンプル

　　オブジェクト名：cmdObjectName
　　標題　　　　　：ダイアログボックスを開く

　　　　機能名      機能パラメータリスト
　［１］表示
　［２］手続き実行  cmdObjectNameClick
　［３］なし
　［４］なし

　手続き定義開始　cmdObjectNameClick( )
　　変数宣言　自動，文字列｛ &icon, &title = "cmdObjectNameClick( )", &msg ｝
　　変数宣言　自動，文字列｛ &wfmFileName, &tblFileName, &procedureName ｝
　　変数宣言　自動，整数　｛ &hdl, &modalControl = 1 ｝

　　　** ダイアログボックスに渡す局所変数を指定します
　　&HDLVARmStoreParameter  = "整数　｛ &mFieldIndex ｝"
　　&HDLVARmStoreParameter  = &HDLVARmStoreParameter + "文字列　｛ &mFieldName ｝"

　　** 主ウィンドウに返す局所変数を指定します
　　&HDLVARmReturnParameter = "&mFieldIndex, &mFieldName"

　　** ダイアログボックスを開くモードを指定します ※0:通常のウィンドウ 1:モーダルのウィンドウ
　　&modalControl = #cond( 1 + #配列要素数( "INFmModalControl" ), #変数( "INFmModalControl" ), 1, 1 )

　　** ダイアログボックスのフォームファイル名( .wfm )と表ファイル名( .tbl )を指定します
　　&wfmFileName　 = #一括パス名 + "FileName.wfm"
　　&tblFileName　 = #一括パス名 + "FileName.tbl" /* nullフォームの場合には未定義値 */

　　** ダイアログボックスを閉じた時、主ウィンドウの［タイマー2］イベントで実行する一般手続き名を指定します
　　&procedureName = "cmdObjectNameClickRETURN"

　　手続き実行　HDLVARprcWindowAppearVarSend( &modalControl, &wfmFileName, &tblFileName, &procedureName, &hdl )

　手続き定義終了

　手続き定義開始　cmdObjectNameClickRETURN( 整数 &exit )
　　変数宣言　自動，文字列｛ &icon, &title = "cmdObjectNameClickRETURN( )", &msg ｝

　　if　( #変数( "mOnReturnDebug" ) )
　　　&msg = "デバッグ情報"
　　　&msg = &msg + "\n\n※" + #cond( &exit = 1, "［ＯＫ］", &exit = 2, "［適用］", 1, "［キャンセル］/［×］" ) + "ボタンを実行しました"
　　　&msg = &msg + "\n\n&exit = " + #str( &exit )
　　　&icon = "i"
　　　手続き実行　INFprcMsgPause( &icon, &title, &msg )
　　end

　　if　( &exit )　/* &exit が 1(ＯＫ) または 2(適用) */

　　　＊［ＯＫ］または［適用］の場合の処理

　　else　/* &exit が 0(ｷｬﾝｾﾙ・×) */

　　　＊［キャンセル］または［×］の場合の処理

　　end

　手続き定義終了


　■ダイアログボックス側に用意するコマンドボタン

　ダイアログボックス側に配置する[キャンセル]、[ＯＫ]、[適用]のコマンドボタンは次のように設定します。
　いずれのボタンもよく似ていて、機能名３の機能ﾊﾟﾗﾒｰﾀﾘｽﾄの一般手続き：HDLVARcmdButtonClick の引数だけが異なります。

　［キャンセル］ボタン
　　　　機能名      機能パラメータリスト
　［１］実行条件    ( &HDLVARmReferWfmHdl <> 0 )
　［２］表示
　［３］手続き実行  HDLVARcmdButtonClick, 0
　［４］なし


　　［ＯＫ］ボタン
　　　　機能名      機能パラメータリスト
　［１］実行条件    ( &HDLVARmReferWfmHdl <> 0 )
　［２］表示
　［３］手続き実行  HDLVARcmdButtonClick, 1
　［４］なし


　　［適用］ボタン
　　　　機能名      機能パラメータリスト
　［１］実行条件    ( &HDLVARmReferWfmHdl <> 0 )
　［２］表示
　［３］手続き実行  HDLVARcmdButtonClick, 2
　［４］なし

　コマンドボタンで一般手続き：HDLVARcmdButtonClick を実行しないで、
　任意の一般手続きから実行することも可能です。

　　手続き実行　HDLVARcmdButtonClick( 1 )
　　手続き実行　HDLVARcmdButtonClick( &整数 )

　ダイアログボックス側に［キャンセル］、［ＯＫ］、［適用］のコマンドボタンを実行するためには、フォームのワークスペースに INFcmdCommon が必要です。
　コマンドボタン：INFcmdCommon は作成するだけでＯＫです。


　■INF_Framework.cmx Rev.272 / Rev.273 におけるブラシアップ

　ブラシアップの内容は、

　◇変数：&HDLVARmStoreParameter　※HDLVARprcMacroVarRun / HDLVARprcMacroStoreRun / OnErrorHDLVARprcMacroStoreRun
　・宣言する変数のデータ型が不一致した場合のエラー処理　Rev.273 fixed
　・配列変数の要素数が不適切な場合のメッセージ表示　　　Rev.273 fixed
　・数字で始まる変数名を指定した場合のメッセージ表示　　Rev.273 fixed

　◇変数：&HDLVARmReturnParameter　※HDLVARprcVariableReturn / OnErrorHDLVARprcVariableReturn
　・値を返す変数のデータ型が不一致した場合のエラー処理　Rev.273 fixed
　・値を返す変数が見つからない場合のエラー処理　　　　　Rev.273 fixed

　◇引数：&procedureName( &HDLVARmProcedureParameter )　※INFprcEventTimerSecondaryRun / OnErrorINFmMacroEval Rev.272
　・指定した手続き名に整数型の引数が無い場合のエラーメッセージ　Rev.272 fixed

　以上です。