$ZPEEK()

$ZPEEK()
Prev	Chapter 7. Functions	Next

Provides a way to examine memory in the current process address space. It is intended as a tool to make it more convenient for FIS to access information in the address space of processes more efficiently than by calling out to external functions. It is documented here for completeness. While FIS normally maintains stability of GT.M functionality from release to release, this function is not designed for non-FIS usage, and FIS may change or eliminate this function at any time.

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.
- 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 whatever is being fetched 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 be fetched. 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.
- 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.

	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.

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.

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