Caché MultiValue Basic Reference
READ, READL, READU, READV, READVL, READVU
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Reads data from a MultiValue file.
Synopsis
READ dynarray FROM filevar,recID 
   [SETTING var] [ON ERROR statements] [[THEN statements] [ELSE statements]]

READL dynarray FROM filevar,recID 
   [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]

READU dynarray FROM filevar,recID 
    [SETTING var] [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]

READV dynarray FROM filevar,recID,fieldno 
   [SETTING var] [ON ERROR statements] [[THEN statements] [ELSE statements]]

READVL dynarray FROM filevar,recID,fieldno 
   [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]

READVU dynarray FROM filevar,recID,fieldno 
   [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]
Arguments
dynarray A dynamic array used to receive the field values from the file. This argument may be a local variable or an object reference.
filevar A local variable used as the file identifier of an open MultiValue file. This variable is set by the OPEN statement.
recID The record ID of the record to be read, specified as either a number or an alphanumeric string of up to 31 characters. Letters in a recID are case-sensitive. For naming conventions, refer to WRITE.
fieldno The field number of the field to be read, specified as an integer. Used with READV and READVU. If 0, returns the recID.
SETTING var Optional — When an error occurs, sets the local variable var to the operating system's error return code. Successful completion returns 0; error return codes are platform-specific. The SETTING clause is executed before the ON ERROR, THEN, or ELSE clause. Provided for jBASE compatibility.
Description
These read statements read a value from a MultiValue file into a dynamic array. The READ, READL, and READU statements read the specified record into dynarray. The READV, READVL, and READVU statements reads the specified field within a record into dynarray.
The dynarray argument accepts a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]).
You must use the OPEN statement to open the MultiValue file before issuing any of these READ statements.
A read operation must be able to acquire at least a shared lock on the desired resource. The READL and READVL statements acquire a shared lock before performing the read. The READU and READVU statements acquire an update lock before performing the read.
You can optionally specify a LOCKED clause for READL, READU, READVL, and READVU. This clause is executed if the statement could not acquire the desired resource due to lock contention. The LOCKED clause is optional, but strongly recommended; if no LOCKED clause is specified, program execution waits indefinitely for the conflicting lock to be released. The statements argument can be the NULL placeholder keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line; there must be a line break between the LOCKED keyword and the first line.
You can optionally specify an ON ERROR clause, which is executed if an argument is invalid. The statements argument can be the NULL placeholder keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line; there must be a line break between the ON ERROR keyword and the first line.
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. If the read is successful, the THEN clause is executed. The THEN clause is executed even when all remaining field identifiers are the null string. If read cannot read the specified record, the ELSE clause is executed. The statements argument can be the NULL keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line and cannot follow a THEN, ELSE, or END keyword on that line.
Reading a Record
READ, READL, and READU all read the specified MultiValue file record value into dynarray. If recID refers to a non-existent record, the read operation fails.
Reading a Field
READV, READVL, and READVU all read the specified field value from the specified MultiValue file record into dynarray. They do this by locating field delimiters in the record string. If fieldno is 0, these statements returns the specified recID to dynarray. If fieldno refers to a non-existent field (does not correspond to a field delimiter), these statements returns the null string to dynarray. If fieldno is 1 and the entire record consists of a single numeric value (and thus contains no field delimiters), these statements return that numeric value.
If recID refers to a non-existent record and fieldno is not 0, the read operation fails.
Reading to an Object
The dynarray argument can be an object reference, allowing READ to read data into an object. The following statements are all valid forms of reading to an object:
READ @me->prop FROM myfile,1
READ "class"->meth()->prop FROM myfile,1
READ obj->prop FROM myfile,1
READ (obj)->prop FROM myfile,1
READ and MATREAD
The various READ statements read from a MultiValue file into a dynamic array. The various MATREAD statements read from a MultiValue file into a dimensioned array.
Examples
The following example illustrates the use of the READ statement:
OPEN "TEST.FILE" TO myfile
READ mydyn FROM myfile,1
PRINT "the record value:",mydyn
The following example illustrates the use of the READV statement:
OPEN "TEST.FILE" TO myfile
READV mydyn FROM myfile,1,1
PRINT "the field value:",mydyn
See Also