$ZPEEK()

$ZPEEK()
Prev	Chapter 7. Functions	Next

Provides a way to examine memory in the current process address space. Use of this function requires information about GT.M internals, which may change from release to release. Contact FIS support for information on techniques for using $ZPEEK() in largely release independent ways.

The $ZPEEK() function returns the contents of the memory requested as a string depending on the requested (or defaulted) formatting.

The format of the $ZPEEK() function is:

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

mnemonic specifies the memory area $ZPEEK() is to access. Some mnemonics have arguments separated from the mnemonic by a colon (":"). The mnemonics are case independent. Possible mnemonics, their possible abbreviations and their arguments are:
- CSA[REG] - returns a value from the sgmnt_addrs (process private) control block. Takes a case independent region name as an argument.
- FH[REG] - returns a value from the sgmnt_data (shared file header) control block. Takes a case independent region name as an argument..
- GDR[REG] - returns a value from the gd_region (process private) control block. Takes a case independent region name as an argument.
- GLF[REPL] - returns a value from the jnlpool.gtmsrc_lcl_array[n] control block. Takes a numeric index (n) as an argument.
- GRL[REPL] - returns a value from the recvpool.gtmrecv_local control block. No argument allowed. Only available when run on a non-primary instance.
- GSL[REPL] - returns a value from the jnlpool.gtmsource_local_array[n] control block. Takes a numeric index (n) as an argument.
- JBF[REG]:region[ -obtains fields in shared jnl_buffer structure.
- JNL[REG]:region[ - obtains fields in the jnl_private_control structure.
- JPC[REPL] - returns a value from the jnlpool.jnlpool_ctl control block. No argument allowed.
- NL[REG] - returns a value from the node_local (shared) control block. Takes a case independent region name as an argument.
- NLREPL - returns a value from the node_local (shared) control block associated with replication. No argument allowed.
- PEEK - returns a value based on the supplied argument. Argument is the base address of the value to obtain in 0xhhhhhhh format where the h's are hex digits.
- RIH[REPL] - returns a value from the jnlpool.repl_inst_filehdr control block. No argument allowed.
- RPC[REPL] - returns a value from the recvpool.recvpool_ctl control block. No argument allowed. Only available when run on a non-primary instance.
- UHC[REPL] - returns a value from the recvpool.upd_helper_ctl control block. No argument allowed. Only available when run on a non-primary instance.
- UPL[REPL] - returns a value from the recvpool.upd_proc_local control block. No argument allowed. Only available when run on a non-primary instance.
offset (first integer expression) is a numeric value that specifies the offset from the address supplied or implied by the the mnemonic and argument. Specifying a negative offset results in a BADZPEEKARG error. Specifying too large an offset such that unavailable memory is specified results in a BADZPEEKRANGE error.
length (second integer expression) is a numeric value that specifies the length of the field to obtain. Specifying a negative legnth results in a BADZPEEKARG error. Specifying a length that exceeds the maximum string length results in a MAXSTRLEN error. Specifying too large a length such that unavailable memory is specified results in a BADZPEEKRANGE error.
format is an optional single case independent character formatting code for the retrieved data. The formatting codes are:
- C : returns a character representations of the memory locations; this is the DEFAULT if the fourth argument is not specified.
- I : returns a signed integer value - negative values have a preceding minus sign (-); the length can be 1, 2, 4, or 8 bytes.
- U : returns an unsigned integer value - all bits are part of the numeric value; the length can be 1, 2, 4, or 8 bytes.
- S : returns a character representation of the memory locations and the first NULL character found terminates the returned string; that is: the specified length is a maximum.
- T: Selects a $HOROLOG format for a field of 4 or 8 bytes which is intended for use on fields in UNIX time format (seconds since 01/01/1970)
- X : returns a hexadecimal value as 0xXXXXXX where XXXXXX is twice the specified length in bytes, so requested length 1 returns 0xXX and length 4 returns 0xXXXXXXXX; the length can be 1, 2, 4, or 8 bytes.
- Z : returns a hexadecimal representation of the memory locations as 'X' does, without regard to endianness, and with no length restriction other than max string length.
- $ZPEEK() function generates an UNDEF error when VIEW UNDEF is not set and a format parameter is specified but is undefined.

	Notes
$ZPEEK() has no UTF-8 checking. It is possible for values returned by the 'C' and 'S' codes to have invalid UTF-8 values in them. Take care when processing values obtained by these codes to either use "VIEW NOBADCHAR" when dealing with such values and/or use the $Zxxx() flavors of functions like $ZPIECE(), $ZEXTRACT(),etc which also do not raise BADCHAR errors when encountering invalid UTF-8 encoded strings. Note that $ZPEEK() with 8 byte numeric formatting can return numeric string values that exceed GT.M's current limit of 18 digits of precision. If the values are used as strings, the extra digits are preserved, but if used arithmetically, the lower precision digits can be lost. When values from replication structures are requested and the structures are not available due to replication not running or, in the case of the gtmrecv.* control block base options, if not running on a non-primary instance where the gtmrecv.* control are available, a ZPEEKNOREPLINFO error is raised. The JNL[REG] and JBL[REG] mnemonics and characteristics are defined by the running the GTMDefinedTypesInit.m utility, which produces a cross-index in the form: gtmtypfldindx(<structure-name>.<field-mnemonic>)=<n> where gtmtypes(<structure-name>,<n>,*) nodes contain the field characteristics When $ZGBLDIR is set to a global directory specifying a replication instance and replication has started, the Replication Journal Pool for that instance becomes the source of data reported by $ZPEEK(). If a global directory does not specify a Replication Instance, the gtm_repl_instance environment variable determines the Instance for its replicated regions. The mnemonics GLF, GSL, JPC, NLREPL, and RIH require a jnlpool. $VIEW("JNLPOOL") returns the Instance for the current Replication Jounal Pool.

Notes

$ZPEEK() has no UTF-8 checking. It is possible for values returned by the 'C' and 'S' codes to have invalid UTF-8 values in them. Take care when processing values obtained by these codes to either use "VIEW NOBADCHAR" when dealing with such values and/or use the $Zxxx() flavors of functions like $ZPIECE(), $ZEXTRACT(),etc which also do not raise BADCHAR errors when encountering invalid UTF-8 encoded strings.
Note that $ZPEEK() with 8 byte numeric formatting can return numeric string values that exceed GT.M's current limit of 18 digits of precision. If the values are used as strings, the extra digits are preserved, but if used arithmetically, the lower precision digits can be lost.
When values from replication structures are requested and the structures are not available due to replication not running or, in the case of the gtmrecv.* control block base options, if not running on a non-primary instance where the gtmrecv.* control are available, a ZPEEKNOREPLINFO error is raised.
The JNL[REG] and JBL[REG] mnemonics and characteristics are defined by the running the GTMDefinedTypesInit.m utility, which produces a cross-index in the form:
```
gtmtypfldindx(<structure-name>.<field-mnemonic>)=<n>
```
where gtmtypes(<structure-name>,<n>,*) nodes contain the field characteristics
When $ZGBLDIR is set to a global directory specifying a replication instance and replication has started, the Replication Journal Pool for that instance becomes the source of data reported by $ZPEEK(). If a global directory does not specify a Replication Instance, the gtm_repl_instance environment variable determines the Instance for its replicated regions. The mnemonics GLF, GSL, JPC, NLREPL, and RIH require a jnlpool. $VIEW("JNLPOOL") returns the Instance for the current Replication Jounal Pool.

Prev	Up	Next
$ZPIece()	Home	$ZPrevious()