PutText

C++

long PutText(
  LPSTR TextBuffer,                  // buffer that contains data
  long NumberOfCharacters = -1,      // number of characters to write
  long FilePosition = -1,            // position of data in file
  long Format = 0                    // text format
);

long PutText(
  LPWSTR TextBuffer,                 // buffer that contains data
  long NumberOfCharacters = -1,      // number of characters to write
  long FilePosition = -1,            // position of data in file
  long Format = 0                    // text format
);

BASIC

PutText(
  TextBuffer As Variant,             // variant that contains data
  NumberOfCharacters As Long = -1,   // number of characters to write
  FilePosition As Long = -1,         // position of data in file
  Format As TextFormat = 0           // text format
) As Long

Parameters

TextBuffer

C++

Pointer to buffer that contains data.
If parameter NumberOfCharacters is -1, text must be NULL terminated.

BASIC

Variant that contains data.
Variant must be of String data type; it must not be an array.

NumberOfCharacters

Maximum number of characters that can be written to file, not including termination.
If this parameter is -1 entire text is written.

FilePosition

Position in file to write data at.
If this parameter is -1 data is written at current file position.

Format

Text formatting options, specified as a combination of the following values:

IXF_TEXT_NULLTERM	terminating NULL is appended,
IXF_TEXT_CRLFTERM	terminating CR/LF pair is appended,
IXF_TEXT_STRING	text is written as raw character sequence (see Remarks); cannot be combined with other flags.

Return Values

Remarks

IXFile represents text as length-prefixed by default. Actual text data in file is preceded with a long number specifying length of text in characters. If text is formatted as length-prefixed its length is written first and then the exact number of characters. At least 4 bytes are written for length prefix, which can be zero (empty text).

If text is formatted as NULL- or CR/LF-terminated, characters are written to file followed by terminating character(s). CR/LF-terminated text is always terminated with CR/LF pair. If CR/LF termination is requested TextBuffer should not contain CR/LF characters; if such character is found, it terminates text prematurely. To write preformatted texts containing CR/LF characters, IXF_TEXT_STRING formatting should be used instead.

If Format have IXF_TEXT_STRING flag set, text is written as a raw sequence of characters of specified length, without any termination or length prefix. If length of text is smaller than NumberOfCharacters, text is right-padded with appropriate number of NULL characters to achieve requested length.

Unicode version of the method should not be confused with Unicode system calls or Unicode text data. All versions of the method can be used on Unicode and non-Unicode systems depending on your needs; text is always written as a single byte character sequence. Conversion between Unicode and ANSI is performed internally according to current codepage which can be changed with SetCodePage method. See Unicode Support for more information on Unicode system calls, Unicode methods and Unicode text data.

See Also