Caché MultiValue Basic Reference
MATWRITE, MATWRITEU
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Writes data from a dimensioned array to a MultiValue file record.
Synopsis
MATWRITE array {ON | TO} filevar,recID 
   [SETTING var] [ON ERROR statements] [LOCKED statements] [THEN statements] [ELSE statements]

MATWRITEU array {ON | TO} filevar,recID 
   [SETTING var] [ON ERROR statements] [LOCKED statements] [THEN statements] [ELSE statements]
Arguments
array Name of an existing dimensioned array that supplies the record data written to the MultiValue file. This array must have been dimensioned using the DIM statement.
filevar A local variable used as the file identifier of an open MultiValue file. This variable is set by the OPEN statement. You can specify either ON or TO as the keyword.
recID The record ID of the record to be written, specified as either a number or an alphanumeric string of up to 31 characters. Letters in a recID are case-sensitive. Additional naming conventions are described below.
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 clause. Provided for jBASE compatibility.
Description
The MATWRITE statements are used to write data from a dimensioned array to a record in a MultiValue file.
You can optionally specify a LOCKED clause. This clause is executed if the write command could not acquire an exclusive record lock 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 array is not a MultiValue dimensioned array. If no ON ERROR clause is present, an <ARRAY DIMENSION> error is issued. 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 record write is successful, the THEN clause is executed. If record write is attempted but fails, 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.
You can use the STATUS function to determine the status of the write operation, as follows: 0=write successful; -1=write failed because file not open (or opened by another process).
Note:
This statement cannot be executed from the MVBasic command shell. Attempting to do so results in a MVBasic syntax error.
Record Naming Conventions
The following are naming conventions for a valid MultiValue recID:
Empty Nodes
By default, MATWRITE assigns empty strings to unassigned nodes. If the highest subscripts of the dimensioned array are unassigned or have empty string values, the resulting record is truncated at the last assigned data value. This behavior can be configured using the %SYSTEM.Process.MVUndefined() method.
Record Locks
RECORDLOCKU performs an update (exclusive) lock on a record. This update record lock is automatically released when you write data to the record using MATWRITE. The MATWRITEU command does not release the update record lock. You can check the status of an update record lock using the RECORDLOCKED function. You can explicitly release an update record lock using the RELEASE command.
MATWRITE and WRITE
The MATWRITE and MATWRITEU statements write from a dimensioned array to a MultiValue file record. The various WRITE statements write from a dynamic array (or an ordinary string) to a MultiValue file record.
Emulation
D3, jBASE, MVBase, R83, POWER95, Reality, and Ultimate set $OPTIONS MATBUILD.UNASSIGNED.ERROR. This causes these emulations to not support unassigned dimensioned array nodes. Because MATWRITE uses MATBUILD to construct the output string, if MATWRITE encounters an unassigned node, it issues an <UNDEFINED> error. This behavior can be configured using the %SYSTEM.Process.MVUndefined() method.
UniData MATWRITE truncates the highest subscripts of a dimensioned array if they are unassigned or have empty string values. (UniData MATBUILD does not truncate in these circumstances.)
By default, Caché and the D3, jBASE, PIOpen, Prime, UniData, and UniVerse emulations do not set $OPTIONS STATIC.DIM; all other emulations set $OPTIONS STATIC.DIM. When set, STATIC.DIM re-dimensions an array at runtime when there are more attributes than the number of dimensioned array elements. Thus excess attributes are appended to the end of the array. When STATIC.DIM is not set, excess attributes are placed in array element 0.
Examples
The following example writes a line of data to an existing sequential file on a Windows system:
DIM myarray(6)
OPEN "TEST.FILE" TO mytest
   IF STATUS()=0
   THEN
     MATWRITE myarray TO mytest,1
     ON ERROR PRINT "MATWRITE error occurred"
     CLOSE mytest
   END
   ELSE
     PRINT "File open failed"
   END
See Also