Caché ObjectScript Reference
Reads and writes database blocks and modifies data in memory.
||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.
command reads and writes database blocks and writes locations in memory. VIEW
has two argument forms:
You can examine data in memory with the $VIEW
InterSystems recommends that you avoid use of the VIEW
command. When used in any environment, it can corrupt memory structures.
An optional postconditional expression. Caché executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). Caché does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions
in Using Caché 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
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.
defines a string, specify the number of bytes as a negative integer, counting from 1. If the length of newvalue
exceeds this number, Caché ignores the extraneous characters. If the length of newvalue
is less than this number, Caché 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 Caché database into the view buffer:
The following example writes the view buffer back to the sixth block of the Caché 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":
Use the VIEW
command with caution. It is usually used for debugging and repair of Caché databases and Caché system information. It is easy to corrupt memory or your Caché database by using VIEW
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
When you open the view buffer (with the OPEN
command), you indicate the Caché database (CACHE.DAT) to be associated with the view buffer. Using the VIEW
command, you can then read individual blocks from the Caché 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 Caché database.
Reading and Writing Data in a Caché Database
Before you can read and write data blocks in a Caché 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:
is the namespace that contains the CACHE.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 Caché database.
Use the VIEW block
form to read in a block from the associated Caché database. Specify block
as a positive integer. For example:
This example reads the fourth block from the Caché database into the view buffer. Because the size of the view buffer equals the block size used in the Caché 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 Caché 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
If you changed any of the data in the view buffer, write it back to the Caché 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 Caché database with the current block in the view buffer.
Transferring a Block between Caché Databases
When you open the view buffer, Caché does not automatically clear the existing block. This allows you to transfer a block of data from one Caché database to another using the following sequence:
Use OPEN 63
and specify the namespace that contains the first Caché database.
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 Caché database.
to write the block from the view buffer to the second Caché database.
In addition to reading and writing data from a Caché 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
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 Caché High Availability Guide.