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:

[Note] 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.