WRITEV

WRITEV, WRITEVU

Top  Previous  Next

 

The WRITEV statement writes a specific field to a record of a previously opened file. The WRITEVU statement is identical but preserves any lock on the record.

 

 

Format

 

WRITEV var {ENCODING name} TO file.var, record.id, field.expr

{ON ERROR statement(s)}

 

where

 

varis the name of a variable containing the data to be written.

 

file.varis the file variable associated with the file. This may not be a data collection file.

 

record.idevaluates to the id of the record to be written.

 

field.exprevaluates to the number of the field to be written.

 

statement(s)are statements to be executed if the write fails.

 

The keyword ON may be used in place of TO.

 

 

The optional ENCODING element to this statement sets the character encoding to be used, overriding any encoding set in the VOC F-type record or when the file was opened. This is relevant only to directory files and is ignored for other file types. A null string as the encoding name is equivalent to not having the ENCODING clause at all. To disable the default encoding, the encoding name should be specified as "NULL".

 

The contents of var are written to field field.expr of record record.id of the file. If the record does not already exist, it will be created by this operation.. The WRITEV statement releases any read or update lock on this record. The WRITEVU statement preserves the lock. Within a transaction, the lock is retained until the transaction terminates and then released regardless of which statement is used. Attempting to write a record in a transaction will fail if the process does not hold an update lock on the record or the file.

 

 

A field.expr value of zero is treated as a reference to field one. A negative field number causes the var string to be appended as a new field at the end of the record.

 

The ON ERROR clause is executed for serious fault conditions such as errors in a file's internal control structures. The STATUS() function will return an error number. If no ON ERROR clause is present, an abort would occur.

 

Although it is generally acceptable to assume that a WRITEV that does not execute the ON ERROR clause or abort was successful, the WRITEV operation normally returns zero from an immediately following use of the STATUS() function. On ECS mode systems, status value ER$ECS.DATA will be returned if a record containing ECS characters is written to a non-ECS mode hashed file or a directory file with no encoding. The write will have completed but only the low order byte of each character will have been written.

 

 

Example

 

WRITEV ITEM TO STOCK, ITEM.ID, 3

 

This program fragment writes the value of ITEM to field 3 of record ITEM.ID in a file previously opened to file variable STOCK.

 

 

See also:

READV