Caché MultiValue Basic Reference
WRITE, WRITEU, WRITEV, WRITEVU
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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

WRITEU data {ON | TO} filevar,recID 
   [SETTING var] [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]

WRITEV data {ON | TO} filevar,recID,fieldno 
   [SETTING var] [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]

WRITEVU data {ON | TO} filevar,recID,fieldno 
   [SETTING var] [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]
Arguments
data Data to write to the MultiValue file. Can be an expression or variable that resolves to a dynamic array or some other literal value.
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.
fieldno The field number of the field to write. Used with WRITEV and WRITEVU.
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
The WRITE statements are used to write data to a record in a MultiValue file. You supply this data using the data variable.
You can optionally specify a LOCKED clause. This clause is executed if the write operation could not acquire an update 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 when the operation fails and generates an error code. For example, attempting to write to a read-only file. If you do not specify an ON ERROR clause, the ELSE clause is taken for an error code condition, as well as for an unsuccessful write. 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 file write is successful, the THEN clause is executed. If file write does not complete successfully, 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.
If the WRITE has neither an ON ERROR clause nor an ELSE clause, a failed write operation generates a <WRITE> error and halts program execution.
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).
Record Naming Conventions
The following are naming conventions for a valid MultiValue recID:
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 WRITE or WRITEV. The WRITEU and WRITEVU commands do 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.
Writing a Field to a Record
WRITEV and WRITEVU writes a field within a record. They search the record string for the delimited piece specified by the fieldno count, replace it, then rewrite the record. If the fieldno is higher than the number of field delimiters, these statements append the field to the end of the record. If the entire record consists of a single numeric value (and thus contains no field delimiters), these statements convert the record value to a string before appending the specified field value. If the fieldno is 0, a new field is appended to the beginning of the record.
WRITE and MATWRITE
The various WRITE statements write a dynamic array (or a string value) to a MultiValue file record. The various MATWRITE statements write a dimensioned array to a MultiValue file record.
Examples
The following example writes a line of data to an existing sequential file on a Windows system:
OPEN "TEST.FILE" TO mytest
   IF STATUS()=0
   THEN
     WRITE "John Doe" TO mytest,1
     CLOSE mytest
   END
   ELSE
     PRINT "File open failed"
   END
See Also