Ini_PutRawString

int Ini_PutRawString (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.

Note  This function is exactly like Ini_PutString except that unprintable characters in the string are not translated into escape codes. One possible use for this function is to write out a pathname in PC format. Since PC pathnames contain backslashes and since the escape character used by Ini_PutString is also the backslash, you must use Ini_PutRawString if you do not want the back slashes in the pathname to be converted into double backslashes in the destination .ini file. This is only an issue if you are using the inifile instrument to create entries that will not be read by one of the Ini_GetString functions in this instrument. The non-raw versions of the Ini_GetString functions automatically recognize and remove the escape codes inserted by Ini_PutString.

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.

For this function, the only error you are likely to encounter is:

–12 Out of memory!