$View()

Returns information about an environmental factor selected by the arguments. In GT.M, the first argument contains a keyword identifying the environmental factor and, where appropriate, subsequent arguments select among multiple possible occurrences of that factor.

The format for the $VIEW() function is:

$V[IEW](expr1[,expr2])

Argument Keywords of $VIEW()

$VIEW() provides a means to access GT.M environmental information. When GT.M permits modification of the factors accessible with $VIEW(), the VIEW command generally provides the means for effecting the change.

$VIEW() Argument Keywords

ARG 1

ARG 2

RETURN VALUE

"BADCHAR"

none

In UTF-8 mode processes, enables or disable the generation of an error when character-oriented functions encounter malformed byte sequences (illegal characters). The default is 1.

"BREAKMSG"

none

Value of the break message mask; GT.M defaults this to 31.

"DEVICE"

Device name

Device type (FIFO, NULL, PIPE, RMS, SOCKET, or TERMINAL) and device status (OPEN or CLOSED) separated by a colon (":")

"FREEBLOCKS"

region

Number of free database blocks in a given region.

"FREEZE"

region

Process-id of a process that has frozen the database associated with the region specified (using DSE or MUPIP).

If the region is currently not frozen, returns zero.

"FULL_BOOLEAN"

none

Returns a string describing the current compiler setting. The default is "GT.M Boolean short-circuit". $VIEW("FULL_BOOLEAN") reports "Standard Boolean evaluation side effects" when it is not explicitly set, but that mode of operation is required by the setting of gtm_side_effects, and "Standard Boolean side-effect warning" when warnings have been specified. The function reports "Extended Boolean evaluation without short-circuiting" when "EXTENDED_BOOLEAN" behavior is enabled.

"GDSCERT"

none

Truth Value indicating whether Database block certification is currently enabled or disabled.

To enable or disable Database block certification, use the VIEW "GDSCERT" command.

"GVACCESS_METHOD"

region

Access method of the region.

"GVFILE"

region

Name of the database associated with the region.

"GVFIRST"

none

Name of the first database region in the current global directory; functionally equivalent to $VIEW("GVNEXT","").

"GVNEXT"

region

Name of the next database region after the given one in alphabetical order (or M collation sequence); "" for region starts with the first region. A return value of "" means that the global directory defines no additional regions.

"GVSTAT"

region

A read-only process cannot update the database including the database file header where GVSTATS are stored. Another process with write access to a database, such as MUPIP RUNDOWN, can flush its read statistics from the associated shared memory to GVSTATS.

"ICHITS"

none

Number of indirection cache hits since GT.M process startup.

Indirection cache is a pool of compiled expressions that GT.M maintains for indirection and XECUTE.

"ICMISS"

none

Number of indirection cache misses since GT.M process startup.

"JNLACTIVE"

region

can return the following values:

  • -1 (internal error)

  • 0 journaling is disabled

  • 1 journaling is enabled but closed (OFF)

  • 2 journaling is enabled and open (ON)

"JNLFILE"

region

Journal file name associated with the region.

"JNLPOOL"

replication instance file

Returns the replication instance file name for the current Journal Pool and an empty string when there is no Journal Pool. Specifying a second expression for $VIEW("JNLPOOL") provides a means of iterating through active Journal Pools. If the second expression is an empty string, the function returns the replication instance file name associated with the instance first attached by the process or. if the process has not previously engaged with any instance, the string "*". If the file name specified in the second expression does not match the replication instance file name for any of the active Journal Pools the function returns the string "*". Otherwise, the function returns the file name of the Journal Pool attached after the Journal Pool with the specified file name. Note the two argument form of $VIEW("JNLPOOL") does not change the current Replication Instance. Note also that the current Journal Pool may not be associated with the last global accessed by an extended reference.

"JNLTRANSACTION"

none

Index showing how many ZTSTART transaction fences have been opened (and not closed).

"LABELS"

none

Truth value showing whether label case sensitivity is ON (1 for "LOWER") or OFF (0 for "UPPER"); GT.M defaults to 1.

"LINK"

none

Returns the current relink recursive setting of ZLINK.

"LV_CREF"

local variable name (lvn)

returns the number of references by alias containers to the array associated with an unsubscripted local variable name specified as a second expr (for example a quoted string); it returns a zero for a variable without any associated alias container.

"LV_GCOL"

none

returns the number of data-spaces recovered during a local variable data-space garbage collection it triggers; such collections normally happen automatically at appropriate times.

"LV_REF"

local variable name (lvn)

returns the total number of references to the data-space associated with an unsubscripted local variable name specified as a second expr (for example a quoted string).

"LVNULLSUBS"

none

Truth value showing whether null subscripts are permitted in local arrays (1 for "LVNULLSUBS") or not (0 for "NOLVNULLSUBS"); GT.M defaults to 1.

"NOISOLATION"

global

The current isolation-status of the specified global variable which must have a leading "^" in its specification.

This function returns 1 if GT.M has been instructed to not enforce the ACID property of Isolation (that is, "NOISOLATION" has been specified) and 0 otherwise.

By default, GT.M ensures Isolation, that is, a $VIEW command will return 0. The isolation-status of a global variable can be turned on and off by the VIEW "NOISOLATION" command.

"PATCODE"

none

Name of the active patcode table; GT.M defaults this to "M".

"POOLLIMIT"

region

The current limit on global buffers for the region .

"PROBECRIT"

region

Acquires and releases a critical section for the region (the "probe"), returning a string containing following fields, some of of which always have zero (0) values because they are no longer used:

  • CPT - nanoseconds for the probe to get the critical section

  • CFN - 0

  • CQN - 0

  • CYN - 0

  • CQF - 0

  • CQE - 0

  • CAT - total of critical section acquisitions successes

"REGION"

gvn

Name of the region(s) holding the specified gvn.

If gvn spans more than one region, this function returns region name in an order where the first region is the region to which the unsubscripted global variable name maps; and other regions are in the order in which they would be encountered by traversing the subscripts of gvn in order (with duplicates removed).

gvn is a subscripted or unsubscripted global variable name in the same form as that generated by $NAME(). You can use $NAME() inside $VIEW() to ensure that subscripts are in a correct form, for example, $VIEW("REGION",$NAME(^abcd(1,2E4))) instead of $VIEW("REGION","^abcd(1,20000)").

"RTNCHECKSUM"

routine name

Source code check-sum for the most recently ZLINK'd version of the specified routine name (these check-sums use a 128 bit hash based on the MurmurHash3 algorithm).

"RTNNEXT"

routine name

Name of the next routine in the image after the given one; "" (empty string) for routinename starts with the first routine in ASCII collating sequence and a return value of the empty string indicates the end of the list.

"SPSIZE"

none

Returns a string with two comma separated values: Number of bytes currently allocated as process working storage: GT.M manages this space as what is commonly called a heap, and uses the term stringpool to refer to it. The GT.M garbage collector reclaims unused space from the stringpool from time to time, and GT.M automatically expands the stringpool as needed by the application program; Number of bytes currently used by the process.

"STATSHARE"

region

Returns 0 when the process has sharing disabled, 1 when it has sharing enabled, and 2 when sharing is enabled selectively for regions. For a process to store statistics in the stats db, the database must be enabled for sharing and the process must have opted in to share. VIEW "STATSHARE" with no region argument enables sharing for all regions and VIEW "STATSHARE":"REGION_NAME" enables sharing selectively for a region. $VIEW("STATSHARE","REGION_NAME") returns whether a process has opted to share statistics for a region.

"STKSIZ"

none

Returns the GT.M stack size in bytes.

"TOTALBLOCKS"

region

Total number of database blocks in a given region.

"TRANSACTIONID"

NULL

or

transaction level

Transaction ID specified in the particular level (when the transaction level is specified). The first level TSTART is returned if the level is not specified as second argument.

[Note] Note

A NULL string is returned if the specified level (explicitly or implicitly) is greater than the current value of $TLEVEL.

"UNDEF"

none

Truth value showing whether undefined variables should be treated as having a null value (1 for "UNDEF"; 0 for "NOUNDEF"); GT.M defaults to 0.

"ZDATE_FORM"

none

Integer value showing whether four digit year code is active for $ZDATE(); GT.M defaults to 0 (for "YY" format). Use the environment variable gtm_zdate_form to set the initial value of this factor. For usage examples, refer to “$ZDate()”.

[Important] Important

FIS uses the LC_CREF, LV_GCOL, LV_REF keywords in testing and is documenting them to ensure completeness in product documentation. They may (or may not) be useful during application development for debugging or performance testing implementation alternatives.

Examples of $VIEW()

Example:

GTM>Set a=1,*b(1)=a
GTM>write $view("LV_CREF","a")," ",$view("LV_CREF","b")
1 0
GTM>write $view("LV_REF","a")," ",$view("LV_REF","b") 
2 1
GTM>

This example creates an alias variable and an alias container variable and checks the number of both container references and total references to the cells associated with both a and b.

Example:

GTM>Set *a(1)=b,*b(1)=a
GTM>kill *a,*b
GTM>write $view("LV_GCOL")
2
GTM>

This example creates two cross associated alias containers, destroys their ancestor nodes with KILL * and uses $VIEW("LV_GCOL") to force a clean-up of the abandoned data-spaces. In the absence of the $VIEW("LV_GCOL"), GT.M would do this automatically at some subsequent convenient time.

Example:

GTM>write $view("GVSTAT","DEFAULT")
SET:203,KIL:12,GET:203,DTA:2,ORD:23,ZPR:21,QRY:0,LKS:0,LKF:0,CTN:44,DRD:103,DWT:59,
NTW:24,NTR:55,NBW:27,NBR:138,NR0:0,NR1:0,NR2:0,NR3:0,TTW:17,TTR:5,TRB:0,TBW:32,
TBR:80,TR0:0,TR1:0,TR2:0,TR3:0,TR4:0,TC0:0,TC1:0,TC2:0,TC3:0,TC4:0,ZTR:7,DFL:9,
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:35,CFE:0,CFS:0,CFT:0,CQS:0,CQT:0,CYS:0,CYT:0,BTD:13,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>

These are statistics associated with the DEFAULT region. Refer to “ZSHOW Information Codes” for information on the parameters.

Example:

Given the following global directory configuration:

GDE>add -name a(1:10)      -region=a1
GDE>add -name a(10,1)      -region=a2
GDE>add -name a(10,2)      -region=a3
GDE>add -name a(120:300)   -region=a4
GDE>add -name a(60:325)    -region=a5
GDE> show -name
  *** NAMES ***
 Global        Region
 ------------------------------------------------------------------------------
 *             DEFAULT
 a(1:10)       A1
 a(10,1)       A2
 a(10,2)       A3
 a(60:120)     A5
 a(120:300)    A4
 a(300:325)    A5

Here are some $VIEW("REGION",gvn) outputs:

GTM>write $view("REGION","^a(1)")
A1
GTM>write $view("REGION","^a(10)")
DEFAULT,A2,A3
GTM>w $view("REGION","^a(60)")
A5
GTM>w $view("REGION","^a")
DEFAULT,A1,A2,A3,A5,A4

Some examples of $VIEW("DEVICE",name) usage:

GTM> WRITE $VIEW("DEVICE","0")
TERMINAL:OPEN

This indicates the $PRINCIPAL device is a terminal and it is open (which is usually the case for $PRINCIPAL.) The $ZPIN and $ZPOUT intrinsic special variables can be used as the device name to select to corresponding side of a split $PRINCIPAL device.

GTM> OPEN "f.txt"
GTM> CLOSE "f.txt":NODESTROY
GTM> WRITE $VIEW("DEVICE","f.txt")
RMS:CLOSED