WRITE, WRITEU, WRITEV, WRITEVU
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.
-
WRITE writes a record, then releases the update record lock
-
WRITEU writes a record, retaining the update record lock
-
WRITEV writes a field within a record, then releases the update record lock
-
WRITEVU writes a field within a record, retaining the update record lock
These WRITE statements write records without waiting for conflicting locks on those records to be released. To require that the program wait indefinitely for a conflicting lock to be released, you can check for locks prior to calling the WRITE statement.
Alternatively, you can set the $OPTION WRITE.LOCK.WAIT configuration option. However, this option applies globally, which can introduce unnecessary waits, such as on READ statements, and significantly slow down programs.
If lock contention is active, to specify the action that occurs when a record is locked, you can optionally specify a LOCKED clause.
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.
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.
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:
-
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.
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