ZSHow

The ZSHOW command displays information about the current GT.M environment.

The format of the ZSHOW command is:

ZSH[OW][:tvexpr][expr[:glvn][,...]]

ZSHOW Information Codes

A ZSHOW argument is an expression containing codes selecting one or more types of information.

B: displays active ZBREAK breakpoints

D: displays device information

G: displays the access statistics for global variables and access to database file since process startup

I: displays the current values of all intrinsic special variables

L: displays GT.M LOCKs and ZALLOCATEs held by the process

R: displays the GT.M invocation stack and an MD5 checksum of M source code for each routine on the stack.

S: displays the GT.M invocation stack

V: displays local and alias variables

* displays all possible types of ZSHOW information

Codes may be upper- or lower-case. Invalid codes produce a run-time error. Multiple occurrences of the same code in one ZSHOW argument only produce one output instance of the corresponding information. The order of the first appearance of the codes in the argument determines the order of the corresponding output instances.

If you are using a local variable destination and place another code ahead of "V", the effect is to have the results of the earlier code also appear in the results of the "V" code.

If the wildcard (*) occurs in the list, ZSHOW uses the default order (ZSHOW "IVBDLGR" ):

  • intrinsic special variables

  • local variables

  • ZBREAK information

  • device information

  • LOCK and ZALLOCATE information

  • Access statistics for global variables and database files(s).

  • GT.M invocation stack and an MD5 checksum of M source code for each routine on the stack.

  • the GT.M stack

If G occurs in the list, the statistics are displayed in the following order in a comma-separated list where each item has its mnemonic followed by a colon and a counter. GT.M maintains the counter in DECIMAL. Each counter has 8-byte (can get as high as 2**64). If these counters exceed 18 decimal digits (somewhere between 2**59 and 2**60), which is the current GT.M numeric representation precision threshold, their use in arithmetic expressions in GT.M results in loss of precision. The mnemonics are:

SET : # of SET operations (TP and non-TP) 
KIL : # of KILl operations (kill as well as zwithdraw, TP and non-TP) 
GET : # of GET operations (TP and non-TP) 
DTA : # of DaTA operations (TP and non-TP) 
ORD : # of $ORDer() operations (TP and non-TP). The count of $Order(xxx,1) operations are reported under this item. 
ZPR : # of $ZPRevious() (reverse order) operations (TP and non-TP). The count of $Order(xxx,-1) operations are reported under this item. 
QRY : # of $QueRY() operations (TP and non-TP) 
LKS : # of LocK calls (mapped to this db) that Succeeded 
LKF : # of LocK calls (mapped to this db) that Failed 
CTN : Current Transaction Number of the database for the last committed read-write transaction (TP and non-TP) 
DRD : # of Disk ReaDs from the database file (TP and non-TP, committed and rolled-back).This does not include reads that are satisfied by buffered globals for databases that use the BG (Buffered Global) access method. GT.M always reports 0 for databases that use the MM (memory-mapped) access method as this has no real meaning in that mode. 
DWT : # of Disk WriTes to the database file (TP and non-TP, committed and rolled-back). This does not include writes that are satisfied by buffered globals for databases that use the BG (Buffered Global) access method. GT.M always reports 0 for databases that use the MM (memory-mapped) access method as this has no real meaning in that mode.
NTW : # of Non-TP committed Transactions that were read-Write on this database 
NTR : # of Non-TP committed Transactions that were Read-only on this database 
NBW : # of Non-TP committed transaction induced Block Writes on this database 
NBR : # of Non-TP committed transaction induced Block Reads on this database 
NR0 : # of Non-TP transaction Restarts at try 0 
NR1 : # of Non-TP transaction Restarts at try 1 
NR2 : # of Non-TP transaction Restarts at try 2 
NR3 : # of Non-TP transaction Restarts at try 3 
TTW : # of TP committed Transactions that were read-Write on this database 
TTR : # of TP committed Transactions that were Read-only on this database 
TRB : # of TP read-only or read-write transactions that got Rolled Back (incremental rollbacks are not counted) 
TBW : # of TP transaction induced Block Writes on this database 
TBR : # of TP transaction induced Block Reads on this database 
TR0 : # of TP transaction Restarts at try 0 (counted for all regions participating in restarting TP transaction)
TR1 : # of TP transaction Restarts at try 1 (counted for all regions participating in restarting TP transaction)
TR2 : # of TP transaction Restarts at try 2 (counted for all regions participating in restarting TP transaction)
TR3 : # of TP transaction Restarts at try 3 (counted for all regions participating in restarting TP transaction)
TR4 : # of TP transaction Restarts at try 4 and above (restart counted for all regions participating in restarting TP transaction) 
TC0 : # of TP transaction Conflicts at try 0 (counted only for that region which caused the TP transaction restart)
TC1 : # of TP transaction Conflicts at try 1 (counted only for that region which caused the TP transaction restart)
TC2 : # of TP transaction Conflicts at try 2 (counted only for that region which caused the TP transaction restart)
TC3 : # of TP transaction Conflicts at try 3 (counted only for that region which caused the TP transaction restart)
TC4 : # of TP transaction Conflicts at try 4 and above (counted only for that region which caused the TP transaction restart)
DFL : # of times a process flushes the entire set of dirty database global buffers in shared memory to disk.
DFS : # of times a process does an fsync of the database file. For example: a) after writing an epoch journal record, b) as part of database file extension c) during database rundown d) as part of mupip reorg -truncate etc.
JFL : # of times a process flushes all dirty journal buffers in shared memory to disk. For example: when switching journal files etc.
JFS : # of times a process does an fsync of the journal file. For example: when writing an epoch record, switching a journal file etc.
JBB : # of bytes written to the journal buffer in shared memory.
JFB : # of bytes written to the journal file on disk. For performance reasons, GT.M always aligns the beginning of these writes to file system block size boundaries. On Unix, JFB counts all bytes including those needed for alignment in order to reflect the actual IO load on the journal file. Since the bytes required to achieve alignment may have already been counted as part of the previous JFB, processes may write the same bytes more than once, causing the JFB counter to typically be higher than JBB.
JFW : # of times a process invokes a write system call for a journal file.
JRL : # of logical journal records (e.g. SET, KILL etc.)
JRP : # of PBLK and AIMG journal records written to the journal file (these records are seen only in a -detail journal extract)
JRE : # of regular EPOCH journal records written to the journal file (only seen in a -detail journal extract); these are written every time an epoch-interval boundary is crossed while processing updates
JRI : # of idle EPOCH journal records written to the journal file (only seen in a -detail journal extract); these are written when a burst of updates is followed by an idle period, around 5 seconds of no updates after the database flush timer has flushed all dirty global buffers to the database file on disk
JRO : # of all journal records other than logical, PBLK, AIMG and EPOCH records written to the journal file (for example, PINI, PFIN, and so on.)
JEX : # of times a process extends the journal file
DEX : # of times a process extends the database file

[NT]B[WR] mnemonics are satisfied by either disk access or, for databases that use the BG (buffered global) access method, global buffers in shared memory.

If an operation is performed inside a TP transaction, and not committed as a consequence of a rollback, or an explicit or implicit restart, GT.M still counts it.

KILL/GET/DATA/QUERY/ORDER/ZPREVIOUS operations on globals that never existed are not counted, while the same operations on globals that once existed but have since been killed are counted.

Name-level ORDER/ZPREVIOUS operations (for example, $ORDER(^a) with no subscripts) increment the count for each transition into a region as they process the global directory map up to the point they find a global with data .

[Note] Note

The use of comma-separated pieces for ZSHOW "G" allows for future releases of GT.M to provide additional data while facilitating upward compatibility of application code. Since FIS reserves the right to change the order in which statistics are reported in future versions of GT.M, application programs should use the names (mnemonics) when picking pieces from the string instead of relying on field position or ordering.

In addition, "G" also displays a line containing aggregated statistics (GLD:*,REG:* line) for all database files for the global directory and region name. If two or more regions (in the same or different global directories) map to the same physical database file, the ZSHOW "G" reports identical statistics for those two regions, but counts them only once across all database files in this line. It always reports the value for CTN as 0 because this statistic makes sense only for individual database files.

ZSHOW "G" can be used for a benchmark exercise. A process can make periodic commands to ZSHOW "G" and store the returned strings in a local variable - a fast storage mechanism in GT.M - for subsequent analysis.

Alternatively, since the $ZJOBEXAM() function by default performs a ZSHOW "*" which in turn automatically includes the "G" information code, invoking MUPIP INTRPT commands periodically on a particular process causes it to additionally record all global access statistics in the $ZJOBEXAM dump file.

ZSHOW "G" reports process private global access statistics only for regions whose corresponding segments have an access method of BG or MM in the global directory. For regions with other access methods, for example GT.CM GNP, which maps a region/segment to a remote database file, ZSHOW "G" does not report any process private statistics even though aggregated statistics (across all processes) will continue to be gathered in the remote database file header.

If "L" occurs in the list, ZSHOW displays the current active M LOCKs and their corresponding LEVEL. On a active M lock, a LOCK+ increases LEVEL by 1 and LOCK- decreases the LEVEL by 1. GT.M increments MLG (M Locks Granted) by 1 for every LOCK successful LOCK acquiring action. GT.M treats LOCKs grouped into a single action by specifying them within parentheses as a single lock action. For example, LOCK (^SUCCESS1,^SUCCESS2) increments MLG by 1.

GT.M increment MLT (M Locks Timeout) by 1 for every failed (timeout) attempt to LOCK a resource.

Every user level lock request in turn translates to one or more calls to the database lock code (depending on the timeout and the number of lock names specified in the same lock command) which increments the LKS and/or LKF statistics of the ZSHOW "G" output appropriately.

In UTF-8 mode, the ZSHOW command exhibits byte-oriented and display-oriented behavior as follows:

  • ZSHOW targeted to a device (ZSHOW "*") aligns the output according to the numbers of display columns specified by the WIDTH deviceparameter.

  • ZSHOW targeted to a local (ZSHOW "*":lcl) truncates data exceeding 2048KB at the last character that fully fits within the 2048KB limit.

  • ZSHOW targeted to a global (ZSHOW "*":^CC) truncates data exceeding the maximum record size for the target global at the last character that fully fits within that record size.

  • ZSHOW "L" displays the following M-lock statistics in one line just before displaying the LOCKs held by the process.

Examples of ZSHow

Example:

GTM>ZSHOW "db"

This command displays all devices with deviceparameters reflecting their current characteristics followed by any current ZBREAK locations with their corresponding actions.

Example:

GTM>ZSHOW "dbd"

This command displays the same output as the previous example.

Example:

GTM>ZSHOW "ax"

This command generates a run-time error.

Example:

LAB1  DO LAB2
      Quit
LAB2  Do LAB3
      Quit
LAB3  ZSHow
      Quit

Produces the results:

LAB3^RTN
LAB2^RTN
LAB1^RTN

Example:

GTM>ZSHOW "G"

For process that has access to two database files produces results like the following:

GLD:*,REG:*,SET:205,KIL:0,GET:1,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,CTN:0,DRD:9,DWT:15,
NTW:203,NTR:4,NBW:212,NBR:414,NR0:0,NR1:0,NR2:0,NR3:0,TTW:1,TTR:0,TRB:0,TBW:2,TBR:6,
TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0

GLD:/home/gtmuser1/.fis-gtm/V5.4-002B_x86/g/mumps.gld,REG:DEFAULT,SET:205,KIL:0,GET:1,
DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,CTN:411,DRD:9,DWT:15,NTW:2
03,NTR:4,NBW:212,NBR:414,NR0:0,NR1:0,NR2:0,NR3:0,TTW:1,TTR:0,TRB:0,TBW:2,TBR:6,TR0:0,
TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0

GLD:/tmp/tst/test.gld,REG:DEFAULT,SET:205,KIL:0,GET:1,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,
CTN:411,DRD:9,DWT:15,NTW:203,NTR:4,NBW:212,NBR:414,NR0:0,NR1:0,NR2:0,NR3:0,TTW:1,TTR:0,TRB:0,
TBW:2,TBR:6,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0

Example:

GTM>ZSHOW "G"

Assuming that a GT.M process uses the global directory "/tmp/x1.gld" and opens two regions REG1 and REG2 corresponding to two database files, the above command produces results like the following:

GLD:*,REG:*,SET:0,KIL:0,GET:0,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,CTN:0,DRD:0,DWT:0,NTW:0,
NTR:0,NBW:0,NBR:0,NR0:0,NR1:0,NR2:0,NR3:0,TTW:0,TTR:0,TRB:0,
TBW:0,TBR:0,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0

GLD:/tmp/x1.gld,REG:REG1,SET:0,KIL:0,GET:0,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,CTN:0,DRD:0,
DWT:0,NTW:0,NTR:0,NBW:0,NBR:0,NR0:0,NR1:0,NR2:0,NR3:0,TTW:0,
TTR:0,TRB:0,TBW:0,TBR:0,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0
GLD:/tmp/x1.gld,REG:REG2,SET:0,KIL:0,GET:0,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,CTN:0,DRD:0,
DWT:0,NTW:0,NTR:0,NBW:0,NBR:0,NR0:0,NR1:0,NR2:0,NR3:0,TTW:0,
TTR:0,TRB:0,TBW:0,TBR:0,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0

Example:

GTM>ZSHOW "G":zgbl

This example redirects the output of ZSHOW "G" into a local variable zgbl:

zgbl("G",0)="GLD:*,REG:*,SET:0,KIL:0,GET:0,DTA:0,ORD:0,
ZPR:0,QRY:0,LKS:0,LKF:0,CTN:0,DRD:0,DWT:0,NTW:0,NTR:0,NBW:0,NBR:0,NR0:0,NR1:0,NR2:0,NR3:0,TTW:0,
TTR:0,TRB:0,TBW:0,TBR:0,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0"
zgbl("G",1)="GLD:/tmp/x1.gld,REG:REG1,SET:0,KIL:0,GET:0,DTA:0,ORD:0,ZPR:0,QRY:0,
LKS:0,LKF:0,CTN:0,DRD:0,DWT:0,NTW:0,NTR:0,NBW:0,NBR:0,NR0:0,NR1:0,NR2:0,
NR3:0,TTW:0,TTR:0,TRB:0,TBW:0,TBR:0,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0"
zgbl("G",2)="GLD:/tmp/x1.gld,REG:REG2,SET:0,KIL:0,GET:0,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,
LKF:0,CTN:0,DRD:0,DWT:0,NTW:0,NTR:0,NBW:0,NBR:0,NR0:0,NR1:0,NR2:0,
NR3:0,TTW:0,TTR:0,TRB:0,TBW:0,TBR:0,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0"

Example:

GTM>LOCK ^FAIL:10

GTM>lock (^SUCCESS1,^SUCCESS2)

GTM>zshow "L"
MLG:1,MLT:1
LOCK ^SUCCESS1 LEVEL=1
LOCK ^SUCCESS2 LEVEL=1

This output shows that a process locked ^SUCCESS1 and ^SUCCESS2 and another the lock on ^FAIL failed due to time out.

Note that even though two lock resources ^SUCCESS1 and ^SUCCESS2 were specified in the LOCK command that succeeded, GT.M increments the MLG counter by only 1 because they are part of the same LOCK command. A ZSHOW "L":var by the same process (redirecting the output of ZSHOW into a local or global variable) would result in <var> holding the following contents.

var("L",0)="MLG:1,MLT:1"
var("L",1)="LOCK ^SUCCESS1 LEVEL=1"
var("L",2)="LOCK ^SUCCESS2 LEVEL=1"

Example:

GTM>ZSHOW "L":var
GTM>ZWRITE var
var("L",0)="MLG:1,MLT:1"
var("L",1)="LOCK ^SUCCESS1 LEVEL=1"
var("L",2)="LOCK ^SUCCESS2 LEVEL=1"

This example shows how ZSHOW "L" redirects it output into a local variable var.

Example:

Suppose a process runs LOCK (^SUCCESS1,^SUCCESS2) which succeeds and a LOCK +^FAIL:1 which times out due to another process holding that lock. A ZSHOW "L" at this point displays the following output.

ZSHOW Destination Variables

ZSHOW may specify an unsubscripted or subscripted global or local variable name (glvn) into which ZSHOW places its output. If the argument does not include a global or local variable name, ZSHOW directs its output to the current device.

When ZSHOW directs its output to a variable, it adds two levels of descendants to that variable. The first level subscript contains a one-character string from the set of upper-case ZSHOW action codes, identifying the type of information. ZSHOW implicitly KILLs all descendants of the first level nodes. ZSHOW stores information elements at the second level using ascending integers, starting at 1.

When a ZSHOW "V" directs its output to a local variable (lvn), the result does not contain a copy of the descendants of the resulting "V" node.

Example:

GTM>Kill  Set b(1,"two")="test" ZSHow "v":a ZWRite
a("V",1)="b(1,""two"")=""test"""
b(1,"two")="test"
GTM>

This ZSHow stores all local variables in the local variable a. Note that ZSHOW does not replicate a("V") and a("V",1).

Example:

GTM>KILL  SET a(1,"D",3,5)="stuff",a(1,"X",2)="",a(1)=1
GTM>ZSHow "d":a(1)

GTM>ZWRite
a(1)=1
a(1,"D",1)="/dev/pts/1 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24 
                 EDIT "
a(1,"X",2)="" 
GTM>

This ZSHOW stores the current open device information under a(1). Notice how the ZSHOW overlays the prior value of a(1,"D",3,5).

Example:

GTM>KILL ^ZSHOW
                
GTM>ZB -*,lab^rout ZSH "B":^ZSHOW

GTM>ZWRite ^ZSHOW
^ZSHOW("B",1)="LAB^ROUT"
GTM>

This ZSHOW stores the current ZBREAK information under the global variable ^ZSHOW.

Use of ZSHOW

Use ZSHOW as

  • a debugging tool to display information on the environment.

  • an error-handling tool to capture context information after an unpredictable error with output directed to a sequential file or a global.

  • part of a context-switching mechanism in a server program that must manage multiple contexts.

  • a development tool to determine the external call table entries available from the current process.

To minimize confusing data interactions, limit instances of directing ZSHOW output into variables holding other kinds of information and directing ZSHOW "V" output into local variables. For a comparison of ZSHOW "V" and ZWRITE, refer to “ZWRite”.