$ZPEEK()

$ZPEEK()
前	第7章. 関数	次

現在のプロセス・アドレス空間のメモリを調べる方法を提供します。この関数を使用するには、GT.M 内部構造に関する情報が必要で、リリース間で変更される可能性があります。主に独立した方法で$ZPEEK() を使用する方法については、FISサポートにお問い合わせください。

$ZPEEK() 関数は、要求された（またはデフォルトの）書式設定に応じて、要求されたメモリの内容を文字列として返します。

$ZPEEK() 関数の書式は次のとおりです：

$ZPEEK("mnemonic[:argument]",offset,length[,format])

mnemonic は $ZPEEK() がアクセスするメモリ領域を指定します。mnemonic の中には mnemonic からコロン（ " : "）で区切られた引数があります。mnemonic は大文字小文字を区別しません。可能なmnemonic 、可能な略語とその引数は次のとおりです：
- CSA[REG] - sgmnt_addrs（プロセス・プライベート）コントロールブロックから値を返します。大文字と小文字を区別しない領域名を引数として取ります。
- FH[REG] - sgmnt_data（共有ファイルヘッダ）コントロールブロックから値を返します。大文字と小文字を区別しない領域名を引数として取ります。
- GDR[REG] - gd_region（プロセス・プライベート）コントロールブロックから値を返します。大文字と小文字を区別しない領域名を引数として取ります。
- GLF[REPL] - jnlpool.gtmsrc_lcl_array[n] コントロールブロックから値を返します。引数として数値インデックス（n）をとります。
- GRL[REPL] - recvpool.gtmrecv_local コントロールブロックから値を返します。引数は使用できません。プライマリ以外のインスタンスで実行されている場合にのみ使用できます。
- GSL[REPL] - jnlpool.gtmsource_local_array[n] コントロールブロックから値を返します。引数として数値インデックス（n）をとります。
- JBF[REG]:region[ - 共有 jnl_buffer構造体のフィールドを取得します。
- JNL[REG]:region[ - jnl_private_control 構造体のフィールドを取得します。
- JPC[REPL] - jnlpool.jnlpool_ctl コントロールブロックから値を返します。引数は使用できません。
- NL[REG] - node_local（共有）コントロール・ブロックから値を返します。大文字と小文字を区別しない領域名を引数として取ります。
- NLREPL - 複製に関連付けられたnode_local（共有）コントロールブロックから値を返します。引数は使用できません。
- PEEK - 指定された引数に基づいて値を返します。引数は 0xhhhhhhh 形式で取得する値のベースアドレスで、h は16進数です。
- RIH[REPL] - jnlpool.repl_inst_filehdrコントロールブロックから値を返します。引数は使用できません。
- RPC[REPL] - recvpool.recvpool_ctlコントロールブロックから値を返します。引数は使用できません。プライマリ以外のインスタンスで実行されている場合にのみ使用できます。
- UHC[REPL] - recvpool.upd_helper_ctl コントロールブロックから値を返します。引数は使用できません。プライマリ以外のインスタンスで実行されている場合にのみ使用できます。
- UPL[REPL] - recvpool.upd_proc_localコントロールブロックから値を返します。引数は使用できません。プライマリ以外のインスタンスで実行されている場合にのみ使用できます。
offset （最初の整数式）は、mnemonic(ニーモニック)と引数によって供給または暗示されるアドレスからのオフセットを指定する数値です。負のオフセットを指定すると、BADZPEEKARGエラーが発生します。使用できないメモリが指定されているような大きすぎるオフセットを指定すると、BADZPEEKRANGEエラーが発生します。
length （2番目の整数式）は、取得するフィールドの長さを指定する数値です。負の legnth を指定すると、BADZPEEKARGエラーが発生します。最大文字列長を超える長さを指定すると、MAXSTRLENエラーが発生します。使用できないメモリーが指定されるように長すぎる長さを指定すると、BADZPEEKRANGEエラーが発生します。
format は、検索されたデータのオプションの単一のケースに依存しない文字書式コードです。コードのフォーマットは次のとおりです：
- C ：メモリ位置の文字表現を返します。 4番目の引数が指定されていない場合、これはDEFAULTです。
- I ：符号付き整数値を返します - 負の値はマイナス記号（ - ）になります。長さは1, 2, 4, 8バイトです。
- U ：符号なし整数値を返します - すべてのビットは数値の一部です。長さは1, 2, 4, 8バイトです。
- S ：メモリ位置の文字表現を返し、見つかった最初のNULL文字が返された文字列を終了します；すなわち、指定された長さは最大です。
- T：4または8バイトのフィールドの $HOROLOG形式を選択します。これは、UNIXの時刻形式（1970年1月1日以降の秒数）のフィールドで使用するためのものです。
- X ：0xXXXXXXという16進数の値を返します。XXXXXXは指定された長さの2倍のバイト数であるため、要求される長さ 1 は 0xXXを返し、長さ4は0xXXXXXXXXを返します。長さは1, 2, 4, 8バイトです。
- Z ：エンディアン性(最上位のバイトと最下位のバイトのどちらが先にくるか) に関係なく、最大文字列長以外の長さ制限がない、 'X' のようなメモリ位置の16進表現を返します。
- $ZPEEK() 関数は、VIEW UNDEFが設定されておらず、フォーマット・パラメータが指定されているが未定義のときにUNDEFエラーを生成します。

	注意点
$ZPEEK() にはUTF-8チェックがありません。 'C' と 'S' コードから返された値に無効なUTF-8値が含まれている可能性があります。"VIEW NOBADCHAR" を使用するかどうかについて、これらのコードによって得られた値を処理するとき、そのような値を扱う、あるいは/または、$ZPIECE()や $ZEXTRACT()のような $Zxxx()風の関数を使うときは、注意してください。例えば、それは、無効なUTF-8エンコード文字列に遭遇したときにBADCHARエラーも発生しません。 8バイトの数値書式の$ZPEEK() は、GT.Mの現在の制限である18桁の精度を超える数値文字列の値を返すことができることに注意してください。値を文字列として使用すると余分な数字は保持されますが、算術演算を使用すると精度の低い数字が失われる可能性があります。レプリケーション構造からの値が要求され、レプリケーションが実行されていないために構造が利用できない場合や、gtmrecv.* コントロールブロックの基本オプションの場合、gtmrecv.コントロールが使用可能な非プライマリ・インスタンスで実行されていない場合は、ZPEEKNOREPLINFOエラーが発生します。 JNL[REG] および JBL[REG] のニーモニックと特性は、GTMDefinedTypesInit.m ユーティリティを実行することによって定義されます。このユーティリティは、次の形式で相互索引(cross-index)を生成します： gtmtypfldindx(<structure-name>.<field-mnemonic>)=<n> gtmtypes(<structure-name>,<n>,) ノードにはフィールドの特性が含まれています。

注意点

$ZPEEK() にはUTF-8チェックがありません。 'C' と 'S' コードから返された値に無効なUTF-8値が含まれている可能性があります。"VIEW NOBADCHAR" を使用するかどうかについて、これらのコードによって得られた値を処理するとき、そのような値を扱う、あるいは/または、$ZPIECE()や $ZEXTRACT()のような $Zxxx()風の関数を使うときは、注意してください。例えば、それは、無効なUTF-8エンコード文字列に遭遇したときにBADCHARエラーも発生しません。
8バイトの数値書式の$ZPEEK() は、GT.Mの現在の制限である18桁の精度を超える数値文字列の値を返すことができることに注意してください。値を文字列として使用すると余分な数字は保持されますが、算術演算を使用すると精度の低い数字が失われる可能性があります。
レプリケーション構造からの値が要求され、レプリケーションが実行されていないために構造が利用できない場合や、gtmrecv.* コントロールブロックの基本オプションの場合、gtmrecv.*コントロールが使用可能な非プライマリ・インスタンスで実行されていない場合は、ZPEEKNOREPLINFOエラーが発生します。
JNL[REG] および JBL[REG] のニーモニックと特性は、GTMDefinedTypesInit.m ユーティリティを実行することによって定義されます。このユーティリティは、次の形式で相互索引(cross-index)を生成します：
```
gtmtypfldindx(<structure-name>.<field-mnemonic>)=<n>
```
gtmtypes(<structure-name>,<n>,*) ノードにはフィールドの特性が含まれています。

前	上	次
$ZPiece()	ホーム	$ZPrevious()