Skip to main content

$VIEW

Returns the contents of memory locations.

Synopsis

$VIEW(offset,mode,length)
$V(offset,mode,length)

Parameters

Argument Description
offset

Positive Integer: an offset, in bytes, from a base address within the memory region specified by mode. Interpretation is mode-dependent (see below.)

-1: a flag to return process summary information.

mode Optional — The memory region whose base address will be used to locate the data. Default is -1.
length

Optional — The length of the data to be returned, in bytes. May also contain a letter “O” reverse order suffix. Default is 1.

When returning process summary information , a returned value format flag: 1=caret–separated string (the default); 2=$list-structured string.

Description

$VIEW returns the contents of memory locations.

The view buffer is a special memory area used to store blocks of data read from the Caché database (CACHE.DAT) with the VIEW command. After reading a block into the view buffer, you can use the $VIEW function with mode 0 to examine the contents of the view buffer. You must open the view buffer as device 63 in order to access it; when finished, you should close device 63.

You can also use $VIEW to return process summary information.

The $VIEW function is usually used when debugging and repairing Caché databases and system information.

Parameters

offset

The value of this argument depends upon the mode argument, as follows:

  • When mode is 0, -1, or -2, specify a positive integer as the offset from the base address, in bytes, counting from 0.

  • When mode is -3, or a positive integer, specify an address in the process address space. The value -1 can be used to retrieve a summary of the process state, as described in “Process Summary Information” below.

  • When mode is -5, specify a positive integer that specifies the number of global nodes in the current block. In this case, odd values return full global references and even values return pointers or data.

mode

The possible values for mode are shown in the following table. If mode is omitted, the default is -1. Note that some values are implementation specific. Implementation restrictions are noted in the table.

Mode Memory Management Region Base Address
0 The view buffer Beginning of view buffer
-1 The process’s partition (default) Beginning of partition
-2 The system table Beginning of system table
-3 The address space for the current process. 0
-5 Global reference and data Special. See “Using Mode -5,” later in the Notes section.
-6 Reserved for InterSystems use  
-7 Used only by the integrity checking utility Special.
n When n is a positive number, the address space for the running process n, where n is the pid (value of the $JOB special variable) for that process. Treats offset and length the same as mode -3. 0

length

A length in bytes, or a flag character. Interpretation depends on the mode and offset values:

  • When mode is 0, -1, or -2, -3, or a positive integer (a pid), and offset is a positive integer, the length parameter can be:

    • A negative integer from -1 to the maximum string length (as a negative integer) to return that length of data as a string. $VIEW returns the specified number of characters starting at the address indicated by offset.

    • A positive integer in the range 1 through 8 (inclusive) to return the decimal value of the data. $VIEW returns from one to four contiguous bytes, or eight contiguous bytes, starting at the address indicated by offset.

    • A letter C or P as a quoted string to indicate a four-byte address on 32-bit systems, or an eight-byte address on 64-bit systems. When specifying C or P, you do not specify a length integer value.

    To return a byte value in reverse order (low-order byte at lowest address) append a letter O suffix to the length value and enclose the resulting string in double quotes.

    If the length parameter is omitted, the default is 1.

  • When mode is -3, or a positive integer (a pid), and offset is -1, the length parameter is a flag that specifies the format of the summary information. Specify a length of 1 to return this summary as a delimited string, or 2 to return this summary as a $LIST structure. If the length parameter is omitted, the default is 1.

  • When mode is -5, do not specify a length parameter.

Notes

$VIEW Usage Restricted

The $VIEW function is a restricted system capability. It is a protected command because the invoked code is located in the CACHESYS database. For further details, refer to the “CACHESYS Special Capabilities” in the Assets and Resources chapter of the Caché Security Administration Guide.

Process Summary Information

When offset is -1, you can use mode -3 to return summary information from the current process address space as a ^ delimited string, as shown in this example:

  WRITE $VIEW(-1,-3,1)

You can also return the same information as a $LIST structure, as follows:

  SET infolist = $VIEW(-1,-3,2)
  ZWRITE infolist

To return summary information from the address space of a specified process, provide the Process ID (pid) for that process as a positive integer for the mode argument, as shown in this example:

  SET pid=$PIECE($IO,"|",4)
  WRITE $VIEW(-1,pid,1)

The following Terminal example returns more than one currently open devices in the dev field. It first returns just the current process. It then opens a spool device (device 2), and returns the open devices as a comma-separated list:

USER>WRITE $VIEW(-1,-3)
8484^*^|TRM|:|8484*,^116^...
USER>OPEN 2:(3:12)

USER>WRITE $VIEW(-1,-3)
8484^*^|TRM|:|8484*,2,^118^...

The summary information return value is in the following format:

pid^mode^dev^mem^dir^rou^stat^prio^uic^loc^blk^^^defns^lic^jbstat^mempeak^roles^loginroles

The fields are defined as follows:

pid The process ID. See the PidOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
mode * if in at the Terminal prompt. + or – if the job is part of a callin connection. Omitted for daemons.
dev Current open device(s), returned as a comma-separated list. The current device (the $IO device) is indicated by an asterisk (*) suffix. See the OpenDevicesOpens in a new tab property of the SYS.ProcessOpens in a new tab class. Note that the dev value includes a trailing comma, the OpenDevices value does not.
mem Memory in use in the process partition (in KBs), if the process is not a daemon. Similar to but not identical to the MemoryUsedOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
dir Default directory.
rou Routine name.
stat A comma-separated pair of integer counts, bol,gcnt, where bol is the beginning of line token, specifying the number of lines executed, and gcnt is the global count, specifying the total number of FOR loops and XECUTE commands performed.
prio User’s current base priority. See the PriorityOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
uic Obsolete, defaults to 0,0.
loc Location, for daemon processes only.
blk Number of 2K blocks that can be used for buddy block queues. This is the maximum size of user memory space (also known as partition space). See the MemoryAllocatedOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
defns Default namespace. See the NameSpaceOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
lic License bits.
jbstat Job status, specified as high,low representing the high and low order bits. Refer to $ZJOB special variable for details.
mempeak Peak memory usage for the process, in kilobytes. This value is approximate to the nearest 64K. See the MemoryPeakOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
roles The roles that the process currently has, returned as a comma-separated list. Same as $ROLES value. See the RolesOpens in a new tab property of the SYS.ProcessOpens in a new tab class.
loginroles The roles that the process had when it was initiated, returned as a comma-separated list. See the LoginRolesOpens in a new tab property of the SYS.ProcessOpens in a new tab class.

Using Mode -5

If the current block in the view buffer contains part of a global, specifying -5 for mode returns the global references and the values contained in the block. The length parameter is not valid for a mode of -5.

With a mode of -5, the offset value specifies the number of global nodes in the block, rather than a byte offset from the base address. Odd values return full global references and even values return pointers or data.

For example, to return the full global reference of the nth node in the view buffer, specify n*2-1 for offset. To return the value of the nth node, specify n*2. To return the global reference of the last node in the block, specify -1 for the offset value.

$VIEW returns the nodes in collating sequence (that is, numeric). This is the same sequence that the $ORDER function uses. By writing code that expects this sequence, you can quickly perform a sequential scan through a global in the view buffer. (Several of the Caché utilities use this technique.) $VIEW returns a null string ("") if the offset specifies a location beyond the last node in the view buffer. Be sure to include a test for this value in your code.

If the current block is a pointer block, the values returned are Caché block numbers, which are pointers. If the block is a data block, the values returned are the data values associated with the nodes.

If $VIEW issues a <DATABASE> or <FUNCTION> error, it means that the information in the block is neither a valid global reference nor valid data.

The following example shows generalized code for examining the contents of the view buffer. The code first opens the view buffer and prompts for the number of the block to be read in. The FOR loop then cycles through all the offsets in the current block. The $VIEW function uses a mode of -5 to return the value at each offset. The WRITE commands output the resulting offset-value pairs.

When the end of the block is reached, $VIEW returns a null string (""). The IF command tests for this value and writes out the “End of block” message. The QUIT command then terminates the loop and control returns to the prompt so the user can read in another block.

Start OPEN 63
      WRITE !,"Opening view buffer."
      READ !!,"Number of block to read in: ",block QUIT:block=""
      VIEW block
         FOR i=1:1 { 
               SET x=$VIEW(i,-5)
               IF x="",i#2 {
                    WRITE !!,"End of block: ",block
                    QUIT }
               WRITE !,"Offset = ",i
               WRITE !,"Value = ",x
        }
        GOTO Start+2
        CLOSE 63
        QUIT

For a global block, typical output produced by this routine might appear as follows:

Opening view buffer.
Number of block to read in:3720
Offset = 1
Value = ^client(5)
Offset = 2
Value = John Jones
Offset = 3
Value = ^client(5,1)
Offset = 4
Value = 23 Bay Rd./Boston/MA 02049
 .
 .
 .
Offset = 126
Value = ^client(18,1,1)
Offset = 127
Value = Checking/45673/1248.00
End of block: 3720
Number of block to read in:

Reverse Order Byte Values (Big-Endian only)

On big-endian systems, you can return byte values in reverse order by using a letter “O” suffix as part of the length parameter. When you specify the letter O in length, $VIEW returns a byte value in reverse order. (The length value must be enclosed in double quotes.) This is shown in the following example:

   USE IO 
   FOR Z=0:0 {
      WRITE *-6 
      SET NEXTBN=$VIEW(LINKA,0,"3O") 
      QUIT:NEXTBN=0 }

In the example above, the length parameter of $VIEW is “3O” (3 and the letter O). When run on a big-endian system, this specifies a length of the next three (3) bytes in reverse order (O). Thus, $VIEW starts at a position in memory (the view buffer—as indicated by a mode of 0) and returns the highest byte, the second highest byte, and the third highest byte.

On little-endian systems, the letter “O” is a no-op. A length value of “3O” is the same as a length value of “3”.

You can use the IsBigEndian()Opens in a new tab class method to determine which bit ordering is used on your operating system platform: 1=big-endian bit order; 0=little-endian bit order.

  WRITE $SYSTEM.Version.IsBigEndian()

See Also

FeedbackOpens in a new tab