DECLARE Read Options

The DECLARE command accepts three optional directives that affect how a declared file source is read and its lifecycle:

DECLARE field type STREAM name, rate BINFILE | TEXTFILE source
    [DISPOSABLE]
    [ONESHOT]
    [HOLD]

The directives are independent and can be combined freely. They apply to replayed files (BINFILE, TEXTFILE). The live source DEVICE takes only ONESHOT of them, with the meaning described below - see the matrix at the end of the chapter. The read deadline of DEVICE is set by the separate TIMEOUT clause, described in the DECLARE Command chapter.

ONESHOT

Without ONESHOT, a file is read in an infinite loop - once the end of the file is reached, the read position returns to the beginning. ONESHOT disables the loop: the file is read exactly once, and once exhausted the stream returns records with every field marked NULL. The record bytes are zeroed, but the null markers distinguish missing data from a numeric zero. Exhausting the file neither ends the process nor deletes the file.

An empty looped TEXTFILE provides no record even after rewinding. Starting with the first read, the accessor returns EIO with zeroed bytes and every field marked NULL; it does not mark the source as exhausted. The service treats this absence as a NULL record rather than an ONESHOT end of file. Without looping, missing tokens in the final record become NULL, while fields already read retain their values. ut_facctxtsrc guards these cases.

For a read failure handled with a NULL record, SourceBuffer logs Read failure from declared source only on the first such failure of that source. Later slots do not repeat the message. This is a WARN message, compiled out in Release; ut_sourceBuffer guards the rule.

DECLARE measurement INTEGER STREAM burst, 0.1 BINFILE 'data.dat' ONESHOT

Use case: one-off loading of historical data into the system.

A DEVICE source has no file to rewind, so ONESHOT changes only the meaning of the end of data. Without ONESHOT the end of data means there is no writer: the slot gets a NULL record, and a writer connecting again resumes the data. With ONESHOT exhaustion is the first end of data after at least one byte was received; from then on the source returns only NULL records, also when another writer connects.

DECLARE sample INTEGER STREAM recording, 1/100 DEVICE '/tmp/recording.fifo' ONESHOT

The --until-eof (-u) option of xretractor reads all sources as if every declaration carried ONESHOT, and stops processing once the first of them is exhausted. For a DEVICE source exhaustion is checked before the slot that would get a NULL record from beyond the end of data, so such a record reaches no stream.

The source must pass the availability check before execution. A missing file or failed open ends the run with an environment error, K4, and code EIO, including with --until-eof. A successfully opened FIFO without a writer follows the first-data waiting rule described above.

DISPOSABLE

When the source’s storage is closed - at the end of the process or when the plan is replaced - the system deletes the input file named in the declaration itself, the stream descriptor (.desc) and the metadata files (.meta, .meta.shadow), if they exist. The deletion depends neither on the end of the data nor on ONESHOT: a file read in a loop is deleted at closing as well, even if it was not read to the end.

DECLARE temp INTEGER STREAM one_time, 0.1 BINFILE 'temp.dat' DISPOSABLE ONESHOT

The combination DISPOSABLE ONESHOT is useful for temporary one-off input, but it is not required.

HOLD

The file is opened when the plan starts, but physical data reading is held until the first request for this stream’s data - fetching data by a query or preparing a record for a client (e.g. an Ad Hoc query). Merely listing the plan does not release the hold. Until the stream is queried, the system shows zero values for it; the first record of the file is read in the next step after the release. The hold is one-off - it does not return when the consumers go away.

DECLARE sparse INTEGER STREAM optional_stream, 1.0 BINFILE 'sparse.dat' HOLD

Use case: keeping the start of a recording until it is first needed, e.g. on user request via xqry. The combination ONESHOT HOLD replays the file once, from the moment of the first request.

Comparison table

Options and source kinds matrix

DEVICE with DISPOSABLE or HOLD is a compile error naming the stream and the option, e.g. DECLARE s: DEVICE does not take HOLD. The reasons: holding the reads does not stop the producer, it only builds up a backlog, and DISPOSABLE would delete the path of the device or FIFO, whose lifecycle does not belong to the reader. ONESHOT on DEVICE does not rewind a file, it only marks the end of data - see ONESHOT.

The deprecated FILE form resolved as DEVICE (a /dev/... path) behaves the same: it refuses DISPOSABLE and HOLD and accepts ONESHOT - see Deprecated FILE form.