$VIEW (ObjectScript)
Synopsis
$VIEW(offset,mode,length)
$V(offset,mode,length)
Arguments
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 InterSystems IRIS database (IRIS.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 InterSystems IRIS databases and system information.
Arguments
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. |
-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 argument 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 argument is omitted, the default is 1.
-
-
When mode is -3, or a positive integer (a pid), and offset is -1, the length argument 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 argument is omitted, the default is 1.
-
When mode is -5, do not specify a length argument.
$VIEW Usage Restricted
The $VIEW function is a restricted system capability. It is a protected command because the invoked code is located in the IRISSYS database. For further details, refer to IRISSYS Special Capabilities.
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:
Field | Description |
---|---|
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 argument 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 ObjectScript 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 InterSystems IRIS block numbers, which are pointers. If the block is a data block, the values returned are the data values associated with the nodes.
If the current block is a data block, and $VIEW issues a <VALUE OUT OF RANGE> error, it means that the information stored at that offset is a big string. To retrieve the data stored at that offset, trap the error and then use $GET with indirection on the global reference stored at the previous offset. For example, instead of x = $VIEW(offset, -5), use x = $GET(@$VIEW(offset-1,-5)).
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 argument. 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 argument 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()