The System Management utilities are:

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:

    1. 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()”.

    2. 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.

    3. 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.

    4. 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

"sgmnt_data.asyncio"

TRUE (1) if the region has asynchronous I/O enabled and FALSE (0) if it does not

Block size

"sgmnt_data.blk_size"

Integer number of bytes

Commit wait spin count

"sgmnt_data.wcs_phase2_commit_wait_spincnt"

Integer count

Current transaction

"sgmnt_data.trans_hist.curr_tn"

Integer count

Defer allocate

"sgmnt_data.defer_allocate"

Integer - 1 means DEFER_ALLOCATE, 0 means NODEFER_ALLOCATE

Encryption key hash

"sgmnt_data.encryption_hash"

String of binary bytes

Extension size

"sgmnt_data.extension_size"

Integer number of blocks

Flush trigger

"sgmnt_data.flush_trigger"

Integer number of blocks (not meaningful for MM)

Journal align size

"sgmnt_data.alignsize"

Integer number of bytes

Journal autoswitch limit

"sgmnt_data.autoswitchlimit"

Integer number of bytes for maximum size of each journal file

Journal before imaging

"sgmnt_data.jnl_before_image"

Integer - 1 means BEFORE image journaling, 0 means NOBEFORE (meaningful only if journaling is on)

Journal buffer size

"sgmnt_data.jnl_buffer_size"

Integer number of journal buffers

Journal epoch interval

"sgmnt_data.epoch_interval"

Integer number of seconds

Journal next write offset

"jnl_buffer.dskaddr"

Integer number of bytes from beginning of journal file

Journal next epoch time

"jnl_buffer.next_epoch_time"

Integer number of seconds since January1, 1970 00:00:00 UTC

Journal state

"sgmnt_data.jnl_state"

Integer 0 means disabled, 1 means enabled but off, 2 means on

Journal SYNCIO

"sgmnt_data.jnl_sync_io"

Integer - 1 means SYNC_IO, 0 means NOSYNC_IO

Journal yield limit

"sgmnt_data.yield_lmt"

Integer count

Lock space

"sgmnt_data.lock_space_size"

Integer number of bytes

Maximum key size

"sgmnt_data.max_key_size"

Integer number of bytes

Maximum record size

"sgmnt_data.max_rec_size"

Integer number of bytes

Mutex hard spin count

"sgmnt_data.mutex_spin_parms.mutex_hard_spin_count"

Integer count

Mutex sleep spin count

"sgmnt_data.mutex_spin_parms.mutex_sleep_spin_count"

Integer count

Number of global buffers (dirty)

"node_local.wcs_active_lvl"

Integer count

Number of global buffers (total)

"sgmnt_data.n_bts"

Integer count

Number of processes accessing the database

"node_local.ref_cnt"

Integer count (always greater than zero, because the process running %PEEKBYNAME has the database open)

Region open

"gd_region.open"

Boolean

Region replication sequence number

"sgmnt_data.reg_seqno"

Integer count

Spanning nodes absent

"sgmnt_data.span_node_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

"sgmnt_data.wcs_wterror_invoked_cntr"

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

"node_local.wcs_wip_lvl"

Integer count of of blocks for which GT.M has issued writes that have not yet been recognized as complete

Writes per flush

"sgmnt_data.n_wrt_per_flu"

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

"jnlpool_ctl_struct.instfreeze_environ_inited"

Integer 1 means Instance Freeze is enabled; 0 means Instance Freeze is disabled

Journal sequence number

"jnlpool_ctl_struct.jnl_seqno"

Integer

Journal sequence number to send to receiving instance in replication file slot

"gtmsource_local_struct.read_jnl_seqno",i where i is the slot number in the replication instance file

Integer

Name of receiving instance in replication instance file slot

"gtmsource_local_struct.secondary_instname",i where i is the slot number in the replication instance file

String of text

Name of this instance

"repl_inst_hdr.inst_info.this_instname"

String of text

Supplementary Replication

"repl_inst_hdr.is_supplementary"

Integer - 1 means supplementary instance; 0 means not supplementary instance

Updates disabled

"jnlpool_ctl_struct.upd_disabled"

Integer - 1 means updates disabled; 0 means updates permitted

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

When invoked as an interactive utility program using DO, ^%YGBLSTAT, prompts for:

When invoked from a shell, the command line is:

$ mumps -run %YGBLSTAT [--help] [--pid pidlist] [--reg reglist] [--stat statlist] 

where:

$$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:

$$ORDERPID^%YGBLSTAT(expr1[,expr2[,expr3]]) reports PIDs of processes that have opted in and recorded statistics. Its arguments are as follows:

The low level API implemented by $$SHOW^%YGBLSTAT(glvn[,strexp]) reports raw statistics of a process and has arguments as follows:

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,CF
T:0,CQS:0,CQT:0,CYS:0,CYT:0,BTD:4
GTM>
loading table of contents...