Ini_PutData

int Ini_PutData (IniText handle, const char sectionName[], const char tagName[], const unsigned char data[], long dataSize);

Purpose

This function stores the specified block of bytes in the tag/value list identified by handle.

The data block can be any length greater than zero bytes and can contain any byte values.

The data is associated with the tag identified by tagName in the section identified by sectionName.

The bytes in the data block are converted to printable ASCII characters before they are added to the IniText. Ini_GetData automatically converts the ASCII characters back to their original byte values.

If the data is very long, the instrument driver will split it across multiple lines associated with the same tag name. This is done by generating new tag names, such as in:

<Tag Name> Line 0001 = "first part of data ........"
<Tag Name> Line 0002 = "second part of data ......."
<Tag Name> Line 0003 = "third part of data"

When you attempt to retrieve the data from the file by calling Ini_GetData, you only need to enter the same Tag Name that you passed into this function. The instrument driver takes care of reconstructing the original single block of data from the multiple lines.

Note  By default, the function checks for and deletes existing items with duplicate names. You can disable the duplicate checking, and thereby increase performance, by calling Ini_SetDuplicateChecking.

Parameters

Input
Name Type Description
handle IniText A handle returned from Ini_New. It represents the list of in-memory tag/value pairs.
sectionName const char [] The section name under which to place the tag/value pair.
tagName const char [] The tag name to use in the tag/value pair.
data const unsigned char [] A pointer to the block of bytes to store with the tag name.
dataSize long The number of bytes to store with the tag name.

Return Value

Name Type Description
status integer Indicates whether the function was successful.

A zero indicates success.

A negative value indicates an error. If the value is from –1 to –999, it is one of the error values defined in userint.h. If the value is from –5000 to –5999, it is one of the error values defined in toolbox.h.

For this function, the only error you are likely to encounter is:
–12 Out of memory!