Ini_PutString

int Ini_PutString (IniText handle, const char sectionName[], const char tagName[], const char stringValue[]);

Purpose

Adds a tag/string pair to the tag/value list identified by handle. The string is associated with the tag identified by tagName in the section identified by sectionName.

If the string 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 line ........"
<Tag Name> Line 0002 = "second part of line ......."
<Tag Name> Line 0003 = "third part of line"

When you attempt to retrieve the string from the file by calling Ini_GetPointerToString, Ini_GetStringCopy, or Ini_GetStringIntoBuffer, 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 string 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.
stringValue const char [] The string to associate 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.

The only error you are likely to encounter is:
–12 Out of memory!