The System Management utilities are:
The %DUMPFHEAD utility provides a programmatic interface to the functionality of MUPIP DUMPFHEAD. This routine reads the database file header directly, rather than opening it as a database and reading values mapped into memory. This means it is lighter weight in some seneses than ^%PEEKBYNAME, but it also means that the information it retrieves is more limited, and possibly less current.
Utility Labels
getfields^%DUMPFHEAD(fldarray,dbname) : Retrieve the file header fields provided by the MUPIP DUMPFHEAD command for the database file specified by the second parameter into the array passed by reference to the first parameter.
The first parameter is a required pass-by-reference variable that the caller uses to retrieve data.
The second parameter is the path and name for the database file on which to report information.
The format of the output array is fdump(sgmnt_data.<FIELD NAME>)=<value>; refer to the ^%PEEKBYNAME and its documentation for additional information on the names and values.
The $ETRAP handler simply QUITs as it defers error handling to the caller. Application developers should define an appropriate $ETRAP prior to calling %DUMPFHEAD.
Example:
$gtm -run ^%XCMD 'do getfields^%DUMPFHEAD(.fields,"mumps.dat") zwrite fields'
The %FREECNT utility displays the number of free and total blocks in the database files associated with all regions in the current global directory.
Example:
GTM>DO ^%FREECNT Region Free Total Database file ------ ---- ----- ------------- DEFAULT 81 100 ( 81.0%) /home/gtmuser1/.fis-gtm/V5.4-002B_x86/g/gtm.dat GTM>
The ^%XCMD utility XECUTEs input from the shell command line and returns any error status (truncated to a single byte on UNIX) generated by that code.
LOOP%XCMD Utility Label
LOOP^%XCMD [--before=/<XECUTE_code>/] --xec=/<XECUTE_code>/ [--after=/<XECUTE_code>/]
LOOP^%XCMD: XECUTEs the arguments specified in --xec=/arg1/ as GT.M code for each line of standard input that it reads. The currently read line is stored in the variable %l; its line number is stored in %NR (starts from 1). It returns any error status (truncated to a single byte on UNIX) generated by that code.
--before=/arg0/ specifies the GT.M code that LOOP^%XCMD must XECUTE before executing --xec.
--after=/arg2/ specifies the GT.M code that LOOP^%XCMD must XECUTE after executing the last --xec.
For all qualifiers, always wrap GT.M code specified two forward slashes (/) to denote the start and end of the GT.M code. FIS strongly recommends enclosing the GT.M code within single quotation marks to prevent inappropriate expansion by the shell. LOOP^%XCMD's command line parser ignores these forward slashes.
Example:
/usr/lib/fis-gtm/V5.4-002B_x86/gtm -run %XCMD 'write "hello world",!'
produces the following output:
"hello world"
Example:
$ ps -ef | $gtm_exe/mumps -run LOOP^%XCMD --before='/set user=$ztrnlnm("USER") write "Number of processes owned by ",user," : "/' --xec='/if %l[user,$increment(x)/' --after='/write x,\!/'
Number of processed owned by jdoe: 5
$
$ cat somefile.txt | $gtm_exe/mumps -run LOOP^%XCMD --before='/write "Total number of lines : "/' --xec='/set total=$increment(x)/' --after='/write total,\!/'
Total number of lines: 9
$
$ cat somefile.txt | $gtm_exe/mumps -run LOOP^%XCMD --after='/write "Total number of lines : ",%NR,\!/'
Total number of lines: 9
$
$ $gtm_exe/mumps -run LOOP^%XCMD --before='/set f="somefile.txt" open f:readonly use f/' --after='/use $p write "Total number of lines in ",f,": ",%NR,\!/'
Total number of lines in somefile.txt: 9
$
%PEEKBYNAME() provides a stable interface to $ZPEEK() that uses control structure field names. $ZPEEK() provides a read-only mechanism to access selected fields in selected control structures in the address space of a process, including process private memory, database shared memory segments and Journal Pools. Although application code can call $ZPEEK() directly, such direct access must use numeric arguments that can vary from release to release. Access by name using %PEEKBYNAME makes application code more stable across GT.M releases. For more information, refer to “$ZPEEK()”. FIS intends to maintain the stability of a name from release to release where that name refers to the same data item; however we may add or obsolete names, or modify the type and size associated with existing names at our discretion, to reflect changes in the implementation. The format of the %PEEKBYNAME() function is:
%PEEKBYNAME(field[,regindex][,format])
The first expression specifies the memory location to access in the format:
CONTROL_BLOCK[.FIELD].*(For example,"gd_region.max_key_size").-
The optional second expression specifies a region name, structure index or a base address associated with the first (field name) argument. The choice is governed by the following rules applied in the following order:
If the value is a hex value in the form of
0xhhhhhhhh[hhhhhhhh], then PEEKBYNAME uses it as the base address of the data to fetch. Also in this case, the offset, length, and type are taken from the field specified in the first expression (field). For more information, see the description of the "PEEK" mnemonic in “$ZPEEK()”.If the first expression refers to one of the region-related structures supported by the $ZPEEK() function, PEEKBYNAME treats this second expression as a region name.
If the first expression refers to one of the replication related structures supported by the $ZPEEK() function that are indexed, PEEKBYNAME treats this second expression as a numerical (base 10) index value.
For those structures supported by the $ZPEEK() function that do not accept an argument, this second expression must be NULL or not specified.
The optional third expression specifies the output format in one character as defined in the "format" argument in the $ZPEEK() documentation. This argument overrides the automatic format detection by the %PEEKBYNAME utility.
Examples:
; Print the maximum key size for the DEFAULT region
GTM>write $$^%PEEKBYNAME("gd_region.max_key_size","DEFAULT")
64
; Print the journaling state (non-zero value means it is on)
GTM>write $$^%PEEKBYNAME("gd_region.jnl_state","DEFAULT")
0
; Save the base address of the database file header
GTM>set base=$$^%PEEKBYNAME("sgmnt_addrs.hdr","DEFAULT")
; Print the file header label
GTM>write $$^%PEEKBYNAME("sgmnt_data.label",base)
GDSDYNUNX03
LISTALL^%PEEKBYNAME
Prints all the field mnemonics acceptable as the first argument to %PEEKBYNAME().
LIST^%PEEKBYNAME(.output)
Populates output variable with the type and size information indexed by the field mnemonics for all %PEEKBYNAME()-acceptable fields. For example, output("gd_region.jnl_file_name")="unsigned-char,256".
Labels for Selected Fields
Below are selected fields for which you may find %PEEKBYNAME to be a useful alternative to running a DSE or MUPIP command in a PIPE device, and parsing the output. If there is a field that you wish to access using %PEEKBYNAME, please send questions to your GT.M support channel. We will get you an answer, and if it seems to us to be of general interest, we will add it to the %PEEKBYNAME user documentation.
Region Parameters
Calls to %PEEKBYNAME with the listed string as value of the first parameter, and the region name as the value of the second parameter, return the value. For example:
GTM>write $$^%PEEKBYNAME("sgmnt_data.n_bts","DEFAULT") ; How many global buffers there are
1000
GTM>write $$^%PEEKBYNAME("node_local.wcs_active_lvl","DEFAULT") ; How many of them are dirty
0
GTM>for i=1:1:10000 set ^x($$^%RANDSTR(8))=$$^%RANDSTR(64)
GTM>write $$^%PEEKBYNAME("node_local.wcs_active_lvl","DEFAULT") ; And now, how many of them are dirty
377
GTM>
When using the following, remember to write code that allows for values other than those listed, e.g., if writing code to check whether before image journaling is in use, make sure it can deal with values other than 0 and 1, because a future release of GT.M can potentially introduce a new return value for a field.
|
Parameter |
^%PEEKBYNAME() Parameter |
Value |
|---|---|---|
|
Asynchronous I/O |
|
TRUE (1) if the region has asynchronous I/O enabled and FALSE (0) if it does not |
|
Block size |
|
Integer number of bytes |
|
Commit wait spin count |
|
Integer count |
|
Current transaction |
|
Integer count |
|
Defer allocate |
|
Integer - 1 means DEFER_ALLOCATE, 0 means NODEFER_ALLOCATE |
|
Encryption key hash |
|
String of binary bytes |
|
Extension size |
|
Integer number of blocks |
|
Flush trigger |
|
Integer number of blocks (not meaningful for MM) |
|
Journal align size |
|
Integer number of bytes |
|
Journal autoswitch limit |
|
Integer number of bytes for maximum size of each journal file |
|
Journal before imaging |
|
Integer - 1 means BEFORE image journaling, 0 means NOBEFORE (meaningful only if journaling is on) |
|
Journal buffer size |
|
Integer number of journal buffers |
|
Journal epoch interval |
|
Integer number of seconds |
|
Journal next write offset |
|
Integer number of bytes from beginning of journal file |
|
Journal next epoch time |
|
Integer number of seconds since January1, 1970 00:00:00 UTC |
|
Journal state |
|
Integer 0 means disabled, 1 means enabled but off, 2 means on |
|
Journal SYNCIO |
|
Integer - 1 means SYNC_IO, 0 means NOSYNC_IO |
|
Journal yield limit |
|
Integer count |
|
Lock space |
|
Integer number of bytes |
|
Maximum key size |
|
Integer number of bytes |
|
Maximum record size |
|
Integer number of bytes |
|
Mutex hard spin count |
|
Integer count |
|
Mutex sleep spin count |
|
Integer count |
|
Number of global buffers (dirty) |
|
Integer count |
|
Number of global buffers (total) |
|
Integer count |
|
Number of processes accessing the database |
|
Integer count (always greater than zero, because the process running %PEEKBYNAME has the database open) |
|
Region open |
|
Boolean |
|
Region replication sequence number |
|
Integer count |
|
Spanning nodes absent |
|
Integer - 1 means that no global variable nodes span multiple database blocks, 0 means GT.M does not know (in the past, at least one global variable node spanned multiple blocks, but it may since have been overwritten or KILL'd) |
|
Write errors |
|
Integer count of errors trying to write database blocks - barring problems with the storage subsystem, hitting an asynchronous write limit constitute the primary (probably only) cause |
|
Writes in progress |
|
Integer count of of blocks for which GT.M has issued writes that have not yet been recognized as complete |
|
Writes per flush |
|
Integer count of database blocks written each time a process encounters a circumstance calling for a flush |
Replication Parameters
Calls to %PEEKBYNAME with the listed parameter as the first or only parameter return replication fields as described. For example:
GTM>write $$^%PEEKBYNAME("repl_inst_hdr.inst_info.this_instname") ; Name of this instance
Collegeville
GTM>write $$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",0) ; Name of instance in slot 0 of replication instance file
Malvern
GTM>set x=$$^%PEEKBYNAME("jnlpool_ctl_struct.jnl_seqno") ; Sequence number in Journal Pool of Collegeville
GTM>set y=$$^%PEEKBYNAME("gtmsource_local_struct.read_jnl_seqno",0) ; Next sequence number to send to Malvern
GTM>write x-y ; Current replication backlog from Collegeville to Malvern
2
GTM>
|
Replication Parameter |
^%PEEKBYNAME() Parameter |
Value |
|---|---|---|
|
Instance Freeze |
|
Integer 1 means Instance Freeze is enabled; 0 means Instance Freeze is disabled |
|
Journal sequence number |
|
Integer |
|
Journal sequence number to send to receiving instance in replication file slot |
|
Integer |
|
Name of receiving instance in replication instance file slot |
|
String of text |
|
Name of this instance |
|
String of text |
|
Supplementary Replication |
|
Integer - 1 means supplementary instance; 0 means not supplementary instance |
|
Updates disabled |
|
Integer - 1 means updates disabled; 0 means updates permitted |
![[Note]](images/note.jpg) |
Note |
|---|---|
%PEEKBYNAME opens the -READ_ONLY help database as part of its operation, and in so doing causes each process using it to create a private semaphore. In addition, the first process to access a database creates an ftok related semaphore, which in the case of a -READ_ONLY database remains until deleted by a MUPIP RUNDOWN. |
Labels in the ^%YGBLSTAT utility program gather and report statistics, offering both a high level API and a low level API. While we intend to preserve backward compatibility of the high level API in future GT.M releases, we may change the low level API if and, when, we change the underlying implementation. A call to a label in ^%YGBLSTAT does not in any way slow the execution of other processes. Because the gathering of statistics is not instantaneous, and processes concurrently open database files as well as close them on exit and may turn their participation in statistics monitoring on and off, statistics typically do not show a single moment in time, as they change during the short time interval over which they are gathered.
In the following, an omitted response or argument is equivalent to "*".
The high level API implemented by $$STAT^%YGBLSTAT(expr1[,expr2[,expr3[,expr4]]]) reports global variable statistics and has arguments as follows:
expr1 (treated as an intexpr - coercing an expr to an integer is equivalent to +(expr)) specifies the PID of a process on which to report; if such a process does not exist, has not opted in, or no database file mapped by expr3 and expr4 includes statistics for such a process, the function returns an empty string. Specifying "*" as the value of expr1 returns the aggregate statistic(s) specified by expr2 for all processes whose statistics are included in the database file(s) of the region(s) specified by expr4 within the global directory specified by expr3, or the empty string if there are no statistics to report for any process.
-
expr2 specifies the statistic(s) to report as follows:
If expr2 is a single statistic, for example, "LKF", the function returns the requested value as an integer
If expr2 is a series of comma-separated names of statistics, for example., "GET,DTA", the function returns a string with each requested statistic in ZSHOW "G" order, for example, "GET:3289,DTA:598...", rather than in the order in which they appear within the specifying argument.
If expr2 is omitted, or consists of the string "*", the return value reports all statistics formatted like the ZSHOW "G" statistics for a single region, for example, "SET:563,KIL:39,GET:3289,DTA:598...
The ^%YGBLSTAT utility uses the local variable structure %YGS. You application code may hide %YGS with NEW but must not modify nodes within it.
expr3 specifies a global directory file name (producing a ZGBLDIRACC error if such a global directory is not accessible); if unspecified, the utility defaults this value to $ZGBLDIR of the invoking process.
expr4 specifies the name of a region (producing a NOREGION error if no such region exists in the global directory expr3); if expr4 is unspecified, or the string "*", the function returns statistics for the process or processes summed across all regions of the global directory explicitly or implicitly specified by expr3.
When invoked as an interactive utility program using DO, ^%YGBLSTAT, prompts for:
the process id (respond * for all processes).
a comma separated list of the statistics desired (respond * for all statistics).
the global directory to use.
region (respond * to report statistics summed across all regions).
When invoked from a shell, the command line is:
$ mumps -run %YGBLSTAT [--help] [--pid pidlist] [--reg reglist] [--stat statlist]
where:
pidlist is a single pid, or "*" (quoted to protect it from expansion by the shell) for all processes currently sharing statistics.
reglist is a single region name in the global directory specified by $gtmgbldir, or "*" to report statistics summed across all regions.
statlist is one or more comma separated statistics, or "*".
When statlist specifies a list of statistics, %YGBLSTAT reports them in the same order in which ZSHOW "G" reports those statistics, rather than in the order in which they appear within the specifying argument.
$$IN^%YGBLSTAT(expr1[,expr2[,expr3]]) reports whether a process that has opted in. There is an assumption that only GT.M processes opt in. Its arguments are as follows:
expr1 coerced to an intexpr specifies a PID. If the PID is invalid or has not opted in, the function returns an empty string, which coerces to FALSE if treated as a Boolean.
expr2 specifies a global directory file name (producing a ZGBLDIRACC error if such a global directory is not accessible); if unspecified or the empty string, the utility defaults this value to the $ZGBLDIR of the invoking process.
expr3 evaluates to the name of a region (producing a NOREGION error if no such region exists in the global directory specified by expr2); if expr3 is unspecified, or the string "*", the function returns whether the process has opted in to any region of the global directory specified by expr2.
$$ORDERPID^%YGBLSTAT(expr1[,expr2[,expr3]]) reports PIDs of processes that have opted in and recorded statistics. Its arguments are as follows:
expr1 coerced to an intexpr specifies a PID such that the function returns the next PID after expr1 of a process that has opted in to be monitored and which has recorded statistics in any region(s) specified by expr3 from the global directory specified by expr2, or the empty string if expr1 is the last PID. A value of the empty string ("") for expr1 returns the first monitored PID meeting the specifications in expr2 and expr3.
expr2 specifies a global directory file name (producing a ZGBLDIRACC error if such a global directory is not accessible); if unspecified or the empty string, the utility defaults this value to the $ZGBLDIR of the invoking process.
expr3 evaluates to the name of a region (producing a NOREGION error if no such region exists in the global directory specified by expr2); of expr3 is unspecified, or the string "*", the function returns the PID for the next process after expr1 for any region of the global directory specified by expr2.
Applications should not rely on GT.M returning the PIDs in a sorted or other predictable order: the order in which PIDs are returned is at the discretion of the implementation, and may change from release to release.
The low level API implemented by $$SHOW^%YGBLSTAT(glvn[,strexp]) reports raw statistics of a process and has arguments as follows:
glvn specifies a node containing raw statistics for a process
-
the raw data is stored in uniquely managed database files as ^%YGS(expr1,expr2) where:
expr1 evaluates to the name of a region in the current global directory (or the global directory of an extended reference), producing an UNDEF error, or, in NOUNDEF mode, an empty string, if no such region exists
expr2 coerced to an intexpr is a PID.
The data in the node is a series of binary bytes which are the raw statistics shared by a process
strexp specifies statistics to report with the same interpretation as the expr2 parameter of $$STAT^%YGBLSTAT.
$$SHOW^%YGBLSTAT() reports a zero value for any statistic whose name is unrecognized. This facilitates application code written for a version of GT.M that includes a statistic, but which also needs to run on an earlier version without that statistic
Because a process sharing statistics can exit, deleting its node, between the time a monitoring process decides to access its statistics, e.g., finding it using $$ORDERPID^%YGBLSTAT() or $ORDER(^%YGS()), and the time the monitoring process performs the database access, any direct access to ^%YGBLSTAT should be wrapped in $GET().
As raw statistics are binary data, processes in UTF-8 mode that gather and monitor statistics should use code with appropriate BADCHAR handling. Note that processes sharing statistics and processes gathering statistics for monitoring and reporting need not run in the same UTF-8/M mode. Statistics sharing by processes is identical in M and UTF-8 modes. FIS suggests that processes gathering statistics run in M mode
FIS strongly recommends that except as documented here for sharing and gathering statistics, you not access statistics database files except under the direction of your GT.M support channel.
As they do for unshared statistics, shared statistics reflect all database actions for a TP transaction, including those during RESTARTs. Because the sharing of statistics is not a database operation that modifies the relative time stamps GT.M uses to maintain serialized operation preserving the Consistency and Isolation aspects of ACID operation, statistics generated by a sharing process inside a transaction (TSTART/TCOMMIT) do not cause transaction restarts as a consequence of updates to shared statistics by other processes.
Example:
GTM>view "statshare"
GTM>for i=1:1:10 set ^A(i)=i
GTM>write $$STAT^%YGBLSTAT("*","","","DEFAULT") ; returns all statistics for the DEFAULT region
SET:10,KIL:0,GET:1,DTA:0,ORD:0,ZPR:0,QRY:0,LKS:0,LKF:0,CTN:100030,DRD:5,DWT:4,NTW:10,NTR:1,NBW:13,NBR:22,NR0:0,NR1:0,NR2:0,NR3:0,TTW:0,TTR:1,TRB:0,TBW:0,TBR:4,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0,ZTR:0,DFL:0,DFS:0,JFL:0,JFS:0,JBB:0,JFB:0,JFW:0,JRL:0,JRP:0,JRE:0,JRI:0,JRO:0,JEX:0,DEX:0,CAT:15,CFE:0,CFS:0,CFT:0,CQS:0,CQT:0,CYS:0,CYT:0,BTD:4,WFR:0,BUS:0,BTS:0,STG:0,KTG:0,ZTG:0,DEXA:0,GLB:0,JNL:0,MLK:0,PRC:0,TRX:0,ZAD:0,JOPA:0,AFRA:0,BREA:0,MLBA:0,TRGA:0,WRL:0,PRG:0,WFL:0,WHE:0,INC:0
GTM>