Reads and writes database blocks and modifies data in memory.
where viewargument is one of the following:
||Optional — A postconditional expression.
||A block location, specified as an integer.
||An offset, in bytes, from a base address within the memory region specified by mode.
||The memory region whose base address will be used to calculate the data to be modified.
||The length of the data to be modified.
||The replacement value to be stored at the memory location.
The VIEW command reads and writes database blocks and writes locations in memory. VIEW has two argument forms:
VIEW block transfers data between the InterSystems IRIS database and memory.
VIEW offset:mode:length:newvalue places newvalue in the memory location identified by offset, mode, and length.
You can examine data in memory with the $VIEW function.
InterSystems recommends that you avoid use of the VIEW command. When used in any environment, it can corrupt memory structures.
Use VIEW with Caution
Use the VIEW command with caution. It is usually used for debugging and repair of InterSystems IRIS databases and InterSystems IRIS system information. It is easy to corrupt memory or your InterSystems IRIS database by using VIEW incorrectly.
VIEW Usage Restricted
The VIEW command 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.
An optional postconditional expression. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions in Using ObjectScript.
A block location, specified as an integer. If block is a positive integer, VIEW reads that number block into the view buffer. If block is a negative integer, VIEW writes the block currently in the view buffer to that block address. The block and the offset:mode:length:newvalue arguments are mutually exclusive.
If the block is already in a memory buffer, the current contents of the buffer will be copied.
Block location 0 is not a valid location. Attempting to specify VIEW 0 results in a <BLOCKNUMBER> error.
An offset, in bytes, from a base address within the memory region specified by mode.
The memory region whose base address will be used to calculate the data to be modified. See Modifying Data in Memory for a description of the possible values.
The length of the data to be modified.
Specify the number of bytes as an integer from 1 to 4, or 8. You can also use the letters C or P to indicate the size of an address field (pointer) on the current platform.
If newvalue defines a string, specify the number of bytes as a negative integer, counting from 1. If the length of newvalue exceeds this number, InterSystems IRIS ignores the extraneous characters. If the length of newvalue is less than this number, InterSystems IRIS stores the supplied characters and leaves the rest of the memory location unchanged.
To store a byte value in reverse order (low-order byte at lowest address) append the letter O to the length number and enclose both in double quotes.
The replacement value to be stored at the memory location.
The following example reads the sixth block from the InterSystems IRIS database into the view buffer:
The following example writes the view buffer back to the sixth block of the InterSystems IRIS database, presumably after the data has been modified:
The following example copies the string "WXYZ" into four bytes starting at offset ADDR in the view buffer. The expression $VIEW(ADDR,0,-4) would then result in the value "WXYZ":
The View Buffer
When used to read and write database buffers, the VIEW command works with the view buffer (device 63). The view buffer is a special memory area that you must open before you can perform any VIEW operations.
When you open the view buffer (with the OPEN command), you indicate the InterSystems IRIS database (IRIS.DAT) to be associated with the view buffer. Using the VIEW command, you can then read individual blocks from the InterSystems IRIS database into the view buffer.
After reading a block into the view buffer, you can use the $VIEW function to examine the data. Or, you can use the VIEW command to modify the data. If you modify the data, you can use the VIEW command again to write the modified block back to the InterSystems IRIS database.
Reading and Writing Data in an InterSystems IRIS Database
Before you can read and write data blocks in an InterSystems IRIS database with VIEW, you must first use the OPEN command to open the view buffer.
Open the view buffer. The view buffer is designated as device number 63. Hence the command is:
where location is the namespace that contains the IRIS.DAT file to be associated with the view buffer. The location is implementation specific. The OPEN 63 command creates the view buffer by allocating a region of system memory whose size is equal to the block size used by the InterSystems IRIS database.
Use the VIEW block form to read in a block from the associated InterSystems IRIS database. Specify block as a positive integer. For example:
This example reads the fourth block from the InterSystems IRIS database into the view buffer. Because the size of the view buffer equals the block size used in the InterSystems IRIS database, the view buffer can contain only one block at any given time. As you read in subsequent blocks, each new block overwrites the current block. To determine which blocks to read in from the InterSystems IRIS database, you should be familiar with the structure of the file.
Examine the data in the block with the $VIEW function or modify it with the VIEW command.
If you changed any of the data in the view buffer, write it back to the InterSystems IRIS database. To write data, use the VIEW block form but specify a negative integer for block. The block number usually matches the number of the current block in the view buffer, but it does not have to. The specified block number identifies which block in the file will be replaced (overwritten) by the block in the view buffer. For example, VIEW -5 replaces the fifth block in the InterSystems IRIS database with the current block in the view buffer.
Close the view buffer using CLOSE 63.
Transferring a Block between InterSystems IRIS Databases
When you open the view buffer, InterSystems IRIS does not automatically clear the existing block. This allows you to transfer a block of data from one InterSystems IRIS database to another using the following sequence:
Use OPEN 63 and specify the namespace that contains the first InterSystems IRIS database.
Use VIEW to read the desired block from the file into the view buffer.
If necessary, use VIEW to modify the data in the view buffer.
Use OPEN 63 again and specify the namespace that contains the second InterSystems IRIS database.
Use VIEW to write the block from the view buffer to the second InterSystems IRIS database.
Use CLOSE 63 to close the view buffer.
Modifying Data in Memory
In addition to reading and writing data from an InterSystems IRIS database, the VIEW command allows you to modify data in memory either in the view buffer or in other system memory areas.
To modify data, use the following form:
All four arguments are required.
You modify data by storing a new value into a memory location, which is specified as a byte offset from the base address indicated by mode. You specify the amount of memory affected in the length argument.
The possible values for mode are shown in the following table:
||Memory Management Region
||Address space of process n, where n is the value of $JOB for that process, a process ID (pid).
||The view buffer
||Beginning of view buffer
||The process’s partition
||Beginning of partition
||The system table
||Beginning of system table
||The process’s address space
||Reserved for InterSystems use
||Used only by the integrity checking utility
||Special. See the High Availability Guide.