FilePutString
This reference collection includes Vector documentation reproduced with permission. Snippets may require configuration-specific symbols and are not all standalone programs. Sources and validation limits.
Contract
long filePutString(char buff[], long buffsize, dword fileHandle);
buff contains the text to write, buffsize specifies the number of characters, and fileHandle comes from a successful output open. The dynamic File class has a corresponding PutString method. The documented result is 1 for success and 0 for error, not a character count.
Three counts that should not be confused
| Quantity | Meaning | Consequence |
|---|---|---|
| Buffer capacity | Storage allocated for the array | Does not establish how much valid text was formatted |
| Text length | Characters belonging to the intended string | Determines the intended write request |
| Return value | Success or failure status | Compare with 1; do not compare with the text length |
For example, a request to write 20 characters can succeed with a return of 1. Treating result == 20 as success would falsely report failure and can cause a retry to duplicate a record. Conversely, passing the full array capacity after formatting a short string is not a justified way to request only the intended text.
For an ordinary null-terminated CAPL text string, compute the valid string length rather than using its capacity. Keep the requested count within the valid initialized contents. Use an appropriate binary-writing API when the payload is binary; this page does not define a binary serialization format.
Record separators belong to your format
Do not assume the function appends a line separator for you. Include the separator in the intended text and in the length calculation. Two calls containing 10 and 20 without a separator do not define two timestamp records. Before using non-ASCII text, agree on the encoding selected at open time and verify an actual round trip; character counts alone do not establish the resulting encoded byte count.
Failure policy
Check the open result before writing. Check each write and record the first failure. On a failed write, stop reporting the export as successful, attempt to close the valid handle, and preserve the failure outcome. Do not blindly retry by appending the entire logical record: the documented status alone does not establish whether a failed operation wrote no data.
After successful writes, check fileClose and inspect the complete output. A close success must not erase an earlier write failure. Neither status proves that the expected row count, separators and numeric units are correct.
Use the disposable fixture matrix to verify output before exporting real measurement timestamps. The API contract is sourced from the authorized reference; examples of failure modes are independent analysis and have not been executed in your environment. See sources and limits.