HI_FileBase

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `HI_FileBase`

`HI_FileBase` -- associates the history with a file for data storage.

## Syntax

    #include <cogent/cogent.h>

``ST_STATUS HI_FileBase`(IP_hTASK historian, char* retbuf, int buflen, char* histname, char* dir, char* basename, char* ext, int numdigits);`

## Arguments

`historian`

  The task pointer to the Cascade Historian program.

`retbuf`

  An optional buffer containing an error message.

`buflen`

  The length in bytes of `retbuf`. If `retbuf` is non-NULL, this must be a valid non-zero length. If `retbuf` is NULL, this parameter is ignored.

`histname`

  The name of a history.

`dir`

  The name of an existing directory, either absolute or relative to the directory in which histdb was started.

`basename`

  The base file name, without an extension or directory.

`ext`

  The file extension.

`numdigits`

  An integer that specifies how the filename is augmented for multiple files, described in detail below.

## Returns

`ST_OK` on success. Otherwise `ST_ERROR`, and the `retbuf` will contain a NULL-terminated character string with an error message. If the return value is `ST_OK`, the `retbuf` may not contain useful information.

## Description

This command associates a file with a history. Without an associated file, data received by the Cascade Historian will be lost when the buffer is full, or when the Cascade Historian is shut down. A history without a file (and with a sufficiently large buffer) could be used for temporary storage and analysis of data.

A history is potentially logged to multiple files. These can be numbered sequentially, or based on date, as specified by the `numdigits` parameter. The filename specified by the user is automatically augmented as each new file is opened, and the Cascade Historian understands that these files all belong together as a single history.

When filebase or `HI_FileBase` is first called for a history, it sets the pattern for all file names to be created for the history. Once this has been done, the Cascade Historian will be able to find the files relating to that history at any time, and will begin numbering from the next file number as necessary.

The possible values for the `numdigits` parameter, with their implications, are as follows:

- `< 0` : Use the date to generate the unique suffix.

- `= 0` : No sequential digits are added to the name. This is the default.

- `> 0` : Specifies the number of decimal digits to be added to the filebase.

For example, the call:

        HI_FileBase (hist, NULL, 0, "hist1", "/tmp/histories", "test.", ".dat", 2);

would create files of the form:

        /tmp/histories/test.01.dat /tmp/histories/test.02.dat
        /tmp/histories/test.03.dat ...

This function corresponds to the Cascade Historian filebase command and the `hist_filebase` dynamic library function.

Prev | Home | Next
`HI_ExchangeBuffer` | Up | `HI_Flush`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.