MATWRITE, MATWRITEU

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.

MATWRITE writes a record, then releases the update (exclusive) record lock
MATWRITEU writes a record, retaining the update (exclusive) record lock

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.

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.

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.

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:

A recID can be a number or an alphanumeric string.
If a number, it is converted to canonical form: multiple plus and minus signs are resolved, and the plus sign, and leading and trailing zeros are removed. If the number is enclosed in single or double quotation marks, conversion to canonical form is not performed. Only a single period can be specified, which is used as the decimal separator character.
If an alphanumeric string, the first character must be a letter, dollar sign ($), or percent sign (%). Subsequent characters may be letters, numbers, or percent characters. If the first character is a dollar sign ($), all subsequent characters must be letters.
The period (.) character can appear within a recID. If the recID is alphabetic any number of periods can be specified; these periods are stripped out and are not part of the recID. If the recID is a mixed alphanumeric, no periods may be specified.
The recID may be enclosed in single or double quotation marks, these become part of the record name, unless the recID is an integer in canonical form. Single and double quotes are equivalent. Thus: "4"='4'=4 and "rec1"='rec1' but not equal to rec1. Do not specify a blank space within a recID.
A recID is case-sensitive.
A recID is limited to 31 characters. You may specify a recID longer than 31 characters, but only the first 31 characters are used. Therefore, a recID must be unique within its first 31 characters.

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()Opens in a new tab 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()Opens in a new tab 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