WRITESEQ, WRITESEQF

Writes a line of data to a sequential file.

Synopsis

WRITESEQ data ON filevar [ON ERROR statements] [THEN statements] [ELSE statements]
WRITESEQ data TO filevar [ON ERROR statements] [THEN statements] [ELSE statements]

WRITESEQF data ON filevar [ON ERROR statements] [THEN statements] [ELSE statements]
WRITESEQF data TO filevar [ON ERROR statements] [THEN statements] [ELSE statements]

Arguments

data	Data to write to the sequential file. Can be an expression or variable that resolves to a literal value.
filevar	A file variable name used to refer to the file in Caché MVBasic. This filevar is obtained from OPENSEQ. The ON and TO keywords are equivalent.

Description

The WRITESEQ statement is used to write a line of data to a file that has been opened for sequential access using OPENSEQ. You supply this data using the data variable. WRITESEQ appends the two newline characters (carriage return & linefeed) to the data, defining it as a line of data.

By default, WRITESEQ begins writing at the beginning of the file, overwriting any existing file data.

WRITESEQ increments a pointer to the end of the data it has just written (plus the two newline characters), so that repeated invocations of WRITESEQ write sequential lines of data to the file. The same file pointer is used by WRITESEQ and READSEQ.

You can determine the current position of this pointer using the STATUS statement. You can reposition this pointer using the SEEK statement.

To write an end-of-file, use the WEOFSEQ statement.

You can optionally specify an ON ERROR clause, which is executed when the operation fails and generates an error code. For example, specifying an invalid filevar, or 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.

You can use the STATUS function to determine the status of the write operation, as follows: 0=sequential write successful; -1=write failed because file not open (or opened by another process).

I/O Buffering

By default, WRITESEQ operations are written to an I/O buffer. This buffer is automatically assigned as part of the OPENSEQ operation. I/O buffering significantly improves overall performance, but means that write operations are not immediately applied to the sequential file.

WRITESEQF is identical to WRITESEQ, except that it does not use I/O buffering. WRITESEQF is useful for logging operations which must be immediately written to disk. However, because writing directly to a sequential file can significantly effect performance, WRITESEQF is not recommended for most data update operations.

Caché MVBasic provides two statements that override WRITESEQ I/O buffering. The FLUSH statement immediately writes the current contents of the I/O buffer to the sequential file. The NOBUF statement disables the I/O buffer for the duration of the sequential file open. That is, all subsequent WRITESEQ operations are immediately executed on the sequential file, exactly as if they were WRITESEQF operations.

New Sequential File

If you are creating a new file, issue an OPENSEQ and then issue a WRITESEQ. Issuing a CREATE is optional; the first WRITESEQ creates the file.

WRITESEQ and WRITEBLK

The WRITEBLK command writes a string of data to a sequential file. This string can be of any length, and may have no relationship to a record within the file. The WRITESEQ command writes a single line of data (a data record) to a sequential file, ending the write by appending two newline characters (carriage return & linefeed) to the data.

Issuing a WRITESEQ creates a new file, if the file specified in OPENSEQ does not exist. Issuing a WRITEBLK does not create a new file.

Examples

The following example writes a line of data to an existing sequential file on a Windows system:

OPENSEQ "C:\myfiles\test1" TO mytest
   IF STATUS()=0 
   THEN
     WRITESEQ "John Doe" TO mytest
     WEOFSEQ mytest
     CLOSESEQ mytest
   END
   ELSE
     PRINT "File open failed"
   END