zstructTextNew

Description: Creates a new text struct for storing and retrieving text data.

Declaration:

zStructText* zstructTextNew(const char* pathname);

Parameters:

const char* pathname

The pathname of the record to store or retrieve.

Returns:

zStructText*

An address to the struct for use with ztextRetrieve() or ztextStore().

Remarks:

ALWAYS call function zstructFree(struct) when finished using.
You must not reuse this struct. Make a new one for every dataset.

zstructTextStringNew

Description: Creates a new text struct with a character string for storing text data. This struct is used for storing a single null terminated string.

Declaration:

zStructText* zstructTextStringNew(const char* pathname, char *text);

Parameters:

const char* pathname

The pathname of the record to store.

char *text

The null terminated character string to store. Does not make a copy.

Returns:

zStructText*

An address to the struct for use with ztextStore().

Remarks:

ALWAYS call function zstructFree(struct) when finished using.
You must not reuse this struct. Make a new one for every dataset.

ztextRetrieve

Description: Retrieve a text record

Declaration:

int ztextRetrieve(long long *ifltab, zStructText *textStruct);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen).

zStructText *textStruct

A text struct that will contain text data a single text record. This struct is created by zstructTextNew(const char* pathname); with pathname being an valid existing pathname. When you are finished with the struct, the struct must be freed by a call to zstructFree.

Returns:

STATUS_OKAY (0): Successful.
STATUS_RECORD_NOT_FOUND (-1): There was no data set for the pathname given.
<-1: Error code. Usually a large negative number containing information about the error. See zerrorDecode to decode the value. Error information is printed to the message file.

Remarks:

Text tables are dimensioned to [number rows][number columns]. HEC-DSS takes a text table and stores it as individual null terminated strings. For example, a table of color characteristics might be:

Color Wave length Temperature Energy

Red long hot low

Blue short cool high

Yellow med-long warm medium

In this example the text table is stored as:

“Red\0long\0hot\0low\0Blue\0short\0cool\0high\0Yellow\0med-long\0warm\0medium”

and the labels are "Color\0Wave length\0Temperature\0Energy\0".

All strings (or cells) must be null terminated. There is no limit on the number of characters in a text or text table record (although one needs to be careful about exhausting memory), nor a limit on the number of characters per table cell. Table cells do not have to be the same size, only terminated with a null character. When passing in the number of characters, make sure you include the last null terminator.

Along with the table, you may include column "labels". In this example, "Color, wave length, etc." are labels.

A text table and text string are separate parts of a record and can be stored together (for example, you can have a description of the table with the table.) A single column text table is called a "text list"; it is a regular text table, but with just one column.

ztextRetrieveToFile

Description: Retrieves a text record and then writes the contents to a file

Declaration:

int ztextRetrieveToFile(long long *ifltab, const char *pathname, const char *filename);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen).

const char *pathname

The pathname of the text record to retrieve.

const char *filename

The full name of the file to write the text output to. It does not have to exist.

Returns:

STATUS_OKAY (0): Successful.
STATUS_RECORD_NOT_FOUND (-1): There was no data set for the pathname given.
<-1: Error code. Usually a large negative number containing information about the error. See zerrorDecode to decode the value. Error information is printed to the message file.

ztextStore

Description: Store a text record

Declaration:

int ztextStore(long long *ifltab, zStructText *textStruct);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen).

zStructText *textStruct

A text struct containing text data to write to a single text record. This struct is created by zstructTextNew(const char* pathname); with the pathname being an valid pathname. When you are finished with the struct, the struct must be freed by a call to zstructFree().

Returns:

STATUS_OKAY (0): Successful.
<-1: Error code. Usually a large negative number containing information about the error. See zerrorDecode to decode the value. Error information is printed to the message file.

zStructText parameters used in this call:

Required:

const char* pathname

The pathname of the record to store. The pathname must be exact, but is case insensitive (i.e., "Apart" is the same as "APART"). There are no specific conventions for text pathnames.

Optional:

char *textString
int numberTextChars

If you want to store a text string or array, then textString points to the char array and numberTextChars is the length to store. The array may contain nulls ('\0'), '\n' and other characters. You can store a text string and text table in the same record. A text string can be long; for example, it may be an entire chapter from a book. If you are not storing a text string, set numberTextChars to 0.

char *textTable
int numberTableChars
int numberRows
int numberColumns

If you want to store a text list or text table, then textTable points to the char array and numberTableChars is the length to store, including nulls. A text list is just a text table with 1 column. Each cell in the table must be a null terminated string. There must be (numberRows * numberColumns) null terminated strings in textTable. You can store a text string and text table in the same record. If you are not storing a text string, set numberTableChars to 0.

char *labels
int numberLabelChars

If the table has a labels or header row, then labels points to the char array and numberLabelChars is the length to store, including nulls. Each cell in the table must be a null terminated string. There must be numberColumns null terminated strings in labels. If you are not storing labels, set numberLabelChars to 0.

Remarks:

Text tables are dimensioned to [number rows][number columns]. HEC-DSS takes a text table and stores it as individual null terminated strings. For example, a table of color characteristics might be:

Color	Wave Length	Temperature	Energy
Red	Long	Hot	Low
Blue	Short	Cool	High
Yellow	Med-long	Warm	Medium

In this example the text table is stored as:

“Red\0long\0hot\0low\0Blue\0short\0cool\0high\0Yellow\0med-long\0warm\0medium”

and the labels are "Color\0Wave length\0Temperature\0Energy\0".

All strings (or cells) must be null terminated. There is no limit on the number of characters in a text or text table record (although one needs to be careful about exhausting memory), nor a limit on the number of characters per table cell. Table cells do not have to be the same size, only terminated with a null character. When passing in the number of characters, make sure you include the last null terminator.

Along with the table, you may include column "labels". In this example, "Color, wave length, etc." are labels.

A text table and text string are separate parts of a record and can be stored together (for example, you can have a description of the table with the table.) A single column text table is called a "text list"; it is a regular text table, but with just one column.

ztextStoreFromFile

Description: Read the contents of a file and store as text in DSS with path name pathname. Data is stored as a text list, where each line is a row.

Declaration:

int ztextStoreFromFile(long long *ifltab, const char *pathname, const char *filename);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen).

const char *pathname

The pathname of the text record to store.

const char *filename

The full name of the file to read the text from.

Returns:

STATUS_OKAY (0): Successful.
<-1: Error code. Usually a large negative number containing information about the error. See zerrorDecode to decode the value. Error information is printed to the message file.

ztextStructPrint

Description: Print the contents of a text struct to standard out. Utility function

Declaration:

void ztextStructPrint(zStructText *textStruct);

Parameters:

zStructText *textStruct

The text struct to print to standard out