NATIONAL INSTRUMENTS 320682 Lab Windows Standard Libraries User Manual

Low-Level I/O Functions
Under UNIX you can use the low-level I/O functions (such as open, sopen, read, and write) from the system library by including system header files in your program. Under Windows you can use these functions by including cviincludeansilowlvlio.h in your program. No function panels are provided for these functions.
Standard Language Additions
LabWindows/CVI does not support extended character sets that require more than 8 bits per character. As a result, the wide character type wchar_t is identical to the single-byte char type. LabWindows/CVI accepts wide character constants specified with the L prefix (as in L`ab’), but only the first character is significant. Furthermore, library functions that use the wchar_t type operate only on 8-bit characters.
LabWindows/CVI supports variable argument functions using the ANSI C macros, with one exception: none of the unspecified arguments can have a struct type. As a result, the macro va_arg (ap, type) should never be used when type is a structure.
Note: LabWindows/CVI will not warn you about this error.
Under UNIX, LabWindows/CVI implements only the C locale as defined by the ANSI C standard. The native locale, which is specified by the empty string, “”, is also the C locale. The following table shows the locale information values for the C locale.

LabWindows/CVI Standard Libraries

1-2

© National Instruments Corporation

Chapter 1

ANSI C Library

Table 1-2. C Locale Information Values

Name
decimal_point thousands_sep grouping int_curr_symbol
currency_symbol mon_decimal_point mon_thousands_sep mon_grouping positive_sign negative_sign int_frac_digits frac_digits p_cs_precedes p_sep_by_space
n_cs_precedes n_sep_by_space p_sign_posn
n_sign_posn

Type C locale Value Description

char *

“.”

Decimal point character for non-monetary

values.

char *

“”

Non-monetary digit group separator character

or characters.

char *

“”

Non-monetary digit groupings.

char *

“”

The three-character international currency

symbol, plus the character used to separate the

international symbol from the monetary

quantity.

char *

“”

The local currency symbol for the current

locale.

char *

“”

Decimal point character for monetary values.

char *

“”

Monetary digit group separator character or

characters.

char *

“”

Monetary digit groupings.

char *

“”

Sign character or characters for non-negative

monetary quantities.

char *

“”

Sign character or characters for negative

monetary quantities.

char

CHAR_MAX Digits appear to the right of the decimal point for international monetary formats.

char

CHAR_MAX Digits appear to the right of the decimal point for other than international monetary formats.

char

CHAR_MAX 1 if currency_symbol precedes nonnegative monetary values; 0 if it follows.

char

CHAR_MAX

1 if currency_symbol is separated from non-negative monetary values by a space; else 0.

char

CHAR_MAX Like p_cs_precedes, for negative values.

char

CHAR_MAX Like p_sep_by_space, for negative values.

char

CHAR_MAX

The positioning of positive_sign for a
non-negative monetary quantity, then its currency_symbol.

char

CHAR_MAX

The positioning of negative_sign for a
negative monetary quantity, then its currency_symbol.

© National Instruments Corporation

1-3

LabWindows/CVI Standard Libraries

ANSI C Library

Chapter 1

Under Windows, LabWindows/CVI implements the default locale by using the appropriate items from the Intl section of the WIN.INI file and appropriate Microsoft Windows functions. Anything not mentioned here has the same behavior under the default locale as specified in the C locale.
For the LC_NUMERIC locale:
· decimal_point maps to the value of sDecimal.
· thousands_sep maps to the value of sThousand.
For the LC_MONETARY locale:
· currency_symbol maps to the value of sCurrency.
· mon_decimal_point maps to the value of sDecimal.
· mon_thousands_sep maps to the value of sThousand.
· frac_digits maps to the value of iCurrDigits.
· int_frac_digits maps to the value of iCurrDigits.
· p_cs_precedes and n_cs_precedes are set to 1 if iCurrency equals 0 or 2, otherwise they are set to 0.
· p_sep_by_space and n_sep_by_space are set to 0 if iCurrency equals 0 or 1, otherwise they are set to 0.
· p_sign_posn and n_sign_posn are determined by the value of iNegCurr as follows:

Value of iNegCurr 0, 4 1, 5, 8, 9 3, 7, 10 6 2

Value of p_sign_posn/n_sign_posn 0 1 2 3 4

For the LC_CTYPE locale: · isalnum maps to the Windows function isCharAlphaNumeric. · isalpha maps to the Windows function isCharAlpha.

LabWindows/CVI Standard Libraries

1-4

© National Instruments Corporation

Chapter 1

ANSI C Library

· islower maps to the Windows function isCharLower.
· isupper maps to the Windows function isCharUpper.
· tolower maps to the Windows function AnsiLower.
· toupper maps to the Windows function AnsiUpper.
For the LC_TIME locale:
· strftime uses the following items from the WIN.INI file for the appropriate format specifiers: sTime, iTime, s1159, s2359, iTLZero, sShortDate, and sLongDate.
· The names of the weekdays and the names of the months match the language version of LabWindows/CVI. That is, a German version of LabWindows/CVI would use the German names of months and days.
For the LC_COLLATE locale:
· strcoll maps to the Windows function lstrcmp.
Because LabWindows/CVI does not support extended character sets that require more than a byte per character, a multibyte character in LabWindows/CVI is actually a single byte character. Likewise, a multibyte sequence is a sequence of single byte characters. Because a multibyte character is the same as a wide character, the conversion functions described in these sections do little more than return their inputs as outputs.

Character Processing
LabWindows/CVI implements all the ANSI C character processing facilities as both macros and functions. The macros are disabled when the LabWindows/CVI debugging level is set to Standard or Extended, so that user protection is available for the arguments to the functions.

String Processing
Under UNIX, the strcoll function is equivalent to strcmp and its behavior is not affected by the LC_COLLATE locale. Under Windows, strcoll is equivalent to the Windows function lstrcmp. For both platforms, the function strxfrm performs a string copy using strncpy and returns the length of its second argument.

© National Instruments Corporation

1-5

LabWindows/CVI Standard Libraries

ANSI C Library

Chapter 1

Input/Output Facilities
The function rename fails if the target file already exists. Under Microsoft Windows, rename fails if the source and target files are on different disk drives. Under UNIX, rename fails if the source and target files are on different file systems.
The functions fgetpos and ftell set errno to EFILPOS on error.

errno Set by File I/O Functions
The errno global variable is set to indicate specific error conditions by the ANSI C file I/O functions and the low-level I/O functions. The possible values of errno are declared in cviincludeansierrno.h. There is a base set of values that is common to all platforms. There are additional values that are specific to particular platforms.
Under Windows 3.1, errno gives very limited information. If the operating system returns an error, errno is set to EIO.
Under Windows 95 and NT, you can call the Windows SDK GetLastError function to obtain system specific information when errno is set to one of the following values:
EACCES EBADF EIO ENOENT ENOSPC

Mathematical Functions
The macro HUGE_VAL defined in the header math.h as well as the macros FLT_EPSILON, FLT_MAX, FLT_MIN, DBL_EPSILON, DBL_MAX, DBL_MIN, LDBL_EPSILON, LDBL_MAX, and DBL_MIN defined in the header float.h all refer to variables. Consequently, these macros cannot be used in places where constant expressions are required, such as in global initializations.

Time and Date Functions
Function time returns the number of seconds since January 1, 1990.
Functions mktime and localtime require time zone information to produce correct results. LabWindows/CVI obtains time zone information from the environment variable named TZ, if it exists. The value of this variable should have the format AAA[S]HH[:MM]BBB, where optional items are in square brackets.

LabWindows/CVI Standard Libraries

1-6

© National Instruments Corporation

Chapter 1

ANSI C Library

The AAA and BBB fields specify the names of the standard and daylight savings time zones, respectively (such as EST for Eastern Standard Time and EDT for Eastern Daylight Time). The optional sign field S indicates whether the local time zone is to the west (+) or to the east (-) of UTC (Greenwich Mean Time). The hour field (HH) and the optional minutes field (:MM) specify the number of hours and minutes from UTC. As an example, the string EST05EDT specifies the time zone information for the eastern part of the United States.
The functions gmtime, localtime, and mktime make corrections for daylight savings time (DST). LabWindows/CVI uses a set of rules for determining when daylight savings time begins and ends. A string in the messages file cvimsgs.txt in the LabWindows/CVI bin directory specifies these rules. The following is the default value of this string.
“:(1986)040102+0:110102-0:(1967)040102-0:110102-0”
This states that for the years from 1986 to the present, DST begins at 2:00 a.m. on the first Sunday in April, and ends at 2:00 a.m. on the last Sunday in October. For the years from 1967 to 1985, DST begins at 2:00 a.m. on the last Sunday in March, and ends at 2:00 a.m. on the last Sunday in October. You can change the way LabWindows/CVI determines DST by changing this string in the cvimsgs.txt file. The countmsg.exe program must be executed after changing the text file. You should execute the following line.
countmsg cvimsgs.txt

Control Functions
The assert macro defined by LabWindows/CVI does not print diagnostics to the standard error stream when the debugging level is anything other than None. Instead, when the value of its argument evaluates to zero, LabWindows/CVI will display a dialog box with a message containing the file name, line number, and expression that caused the assert to fail.
Under UNIX, system passes the specified command to the Bourne shell (sh) as input, as if the current process was performing a wait(2V) system call and was waiting until the shell terminated. Callbacks are not called while the command is executing.
Under Windows, the executable can be either an MS DOS or Microsoft Windows executable, including .exe, .com, .bat, and .pif files. The function does not return until the command terminates, and user keyboard and mouse events are ignored until the command exits. Callbacks for asynchronous events, such as idle events, Windows messages, and VXI interrupts, PostDeferredCall calls, and DAQ events are called while the command is executing. If you need to execute a command built into command.com such as copy, dir, and others, you can call system with the command command.com /C DosCommand args, where DosCommand is the shell command you would like executed. Refer to your DOS documentation for further help with command.com. DOS executables (.exe, .com, and .bat files) use the settings in _default.pif (in your Windows directory) when they are running. You can change their priority, display options, and more by editing _default.pif

© National Instruments Corporation

1-7

LabWindows/CVI Standard Libraries

ANSI C Library

Chapter 1

or by creating another .pif file. Refer to your Microsoft Windows documentation for help on creating and editing .pif files.
If the function is passed a null pointer, LabWindows/CVI returns a non zero value if a command processor is available. Under UNIX, if the argument is not a null pointer, the program returns a zero. Under Microsoft Windows, if the argument is not a null pointer, the program returns zero if the program was successfully started, otherwise it returns one of the following error codes.
-1 System was out of memory, executable file was corrupt, or relocations were invalid. -3 File was not found. -4 Path was not found. -6 Attempt was made to dynamically link to a task, or there was a sharing or network
protection error. -7 Library required separate data segments for each task. -9 There was insufficient memory to start the application. -11 Windows version was incorrect. -12 Executable file was invalid. Either it was not a Windows application or there was an error
in the .EXE image. -13 Application was designed for a different operating system. -14 Application was designed for MS-DOS 4.0. -15 Type of executable file was unknown. -16 Attempt made to load a real-mode application (developed for an earlier Windows version.) -17 Attempt was made to load a second instance of an executable file containing multiple data
segments that were not marked read-only. -20 Attempt was made to load a compressed executable file. The file must be decompressed
before it can be loaded. -21 Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this
application was corrupt. -22 Application requires Microsoft Windows 32-bit extensions. -23 Could not find toolhelp.dll or toolhelp.dll is corrupted. -24 Could not allocate a GetProcUserDefinedHandle.
The exit function does not actually flush and close the open streams. LabWindows/CVI leaves files open so that they may be used from within the Interactive Window after execution of the project terminates. The Close Libraries menu option under the Run menu performs this library cleanup. This library cleanup is also performed when you restart execution of the project by selecting Run Project from the Run menu. The argument passed to function exit is not used by the LabWindows/CVI environment. Under UNIX, standalone executables created by LabWindows/CVI return the value of the argument passed to the exit function.

LabWindows/CVI Standard Libraries

1-8

© National Instruments Corporation

Chapter 1

ANSI C Library

The UNIX version of LabWindows/CVI works with all the signals supported by UNIX in addition to the ANSI C signals.

ANSI C Library Function Reference
For ANSI C function descriptions, consult a reference work such as C: A Reference Manual which is listed in the Related Documentation section of About This Manual. Alternatively, you can use LabWindows/CVI function panel help. The following function description is provided because it is an extension of the ANSI C function set.

fdopen
FILE fp = fdopen (int fileHandle, char mode);

Note: This function is available only in the Windows version of LabWindows/CVI.

Purpose

You can use this function to obtain a pointer to a buffered I/O stream from a file handle returned by one of the following functions.

open sopen

(low-level I/O) (low-level I/O)

You can use the return value just as if you had obtained it from fopen.

(Although this function is not in the ANSI standard, it is included in this library because it returns a pointer to a buffered I/O stream.)

Parameters

Input fileHandle mode

integer File handle returned by open or sopen. string Specifies the read/write, binary/text, and append modes.

Return Value fp

FILE * Pointer to a buffered I/O file stream.

Return Codes NULL (0) Failure. More specific information is in errno.

© National Instruments Corporation

1-9

LabWindows/CVI Standard Libraries

ANSI C Library

Chapter 1

Parameter Discussion
mode is the same as the mode parameter to fopen.
You should use a mode value that is consistent with the mode in which you originally opened the file. If you use write capabilities that were not enabled when the file handle was originally opened, the call to fdopen succeeds, but any attempt to write fails. For instance, if you originally opened the file for reading only, you can pass “rw” to fdopen, but any call to fwrite fails.

LabWindows/CVI Standard Libraries

1-10

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

This chapter describes the functions in the LabWindows/CVI Formatting and I/O Library, and contains many examples of how to use them. The Formatting and I/O Library contains functions that input and output data to files and manipulate the format of data in a program.
The Formatting and I/O Library Function Overview section contains general information about the Formatting and I/O Library functions and panels. Because the Formatting and I/O Library differs in many respects from the other LabWindows/CVI libraries, it is very important to read the overview before reading the other sections of this chapter.
The Formatting and I/O Library Function Reference section contains an alphabetical list of function descriptions. This section is helpful for determining the syntax of the file I/O and string manipulation functions.
The Using the Formatting and Scanning Functions section describes in detail this special class of functions. Although these functions are listed in the function reference, their versatility and complex nature require a more complete discussion.
The final section, Formatting and I/O Library Programming Examples, contains many examples of program code that call Formatting and I/O Library functions. Most of the examples use the formatting and scanning functions.
Formatting and I/O Library Function Overview
This section contains general information necessary for understanding the Formatting and I/O Library functions and panels.
The Formatting and I/O Library Function Panels
The Formatting and I/O Library function panels are grouped in a tree structure according to the types of operations performed. The Formatting and I/O Library function tree is shown in Table 2-1.
The first- and second-level bold headings in the tree are the names of function classes and subclasses. Function classes and subclasses are groups of related function panels. The third-level headings in plain text are the names of individual function panels. The names of the functions are in bold italics to the right of the function panels. Refer to the Sample Function Panels for the Formatting and Scanning Functions section later in this chapter for more information.

© National Instruments Corporation

2-1

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Table 2-1. The Formatting and I/O Library Function Tree

Formatting and I/O File I/O Open File Close File Read from File Write to File Array to File File to Array Get File Information Set File Pointer String Manipulation Get String Length String to Lowercase String to Uppercase Fill Bytes Copy Bytes Copy String Compare Bytes Compare Strings Find Pattern Read Line Write Line Data Formatting Formatting Functions Fmt to Memory (Sample Panel) Fmt to File (Sample Panel) Fmt to Stdout (Sample Panel) Scanning Functions Scan from Mem (Sample Panel) Scan from File (Sample Panel) Scan from Stdin (Sample Panel) Status Functions Get # Formatted Bytes Get Format Index Error Get I/O Error Get I/O Error String

OpenFile CloseFile ReadFile WriteFile ArrayToFile FileToArray GetFileInfo SetFilePtr
StringLength StringLowerCase StringUpperCase FillBytes CopyBytes CopyString CompareBytes CompareStrings FindPattern ReadLine WriteLine
Fmt FmtFile FmtOut
Scan ScanFile ScanIn
NumFmtdBytes GetFmtErrNdx GetFmtIOError GetFmtIOErrorString

The classes and subclasses in the tree are described below: · The File I/O function panels open, close, read, write, and obtain information about files. · The String Manipulation function panels manipulate strings and character buffers.

LabWindows/CVI Standard Libraries

2-2

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

· The Data Formatting function panels perform intricate formatting operations with a single function call.
­ Formatting Functions, a subclass of Data Formatting, contains function panels that combine and format one or more source items into a single target item.
­ Scanning Functions, a subclass of Data Formatting, contains function panels that transform a single source item into several target items.
­ Status Functions, a subclass of Data formatting, contains function panels that return information about the success or failure of a formatting or scanning call.
The online help with each panel contains specific information about operating each function panel.

The String Manipulation Functions
The functions in the String Manipulation class perform common operations such as copying one string to another, comparing two strings, or finding the occurrence of a string in a character buffer. These functions are similar in purpose to the standard C string functions.

The Special Nature of the Formatting and Scanning Functions
The formatting and scanning functions are different in nature from the other functions in the LabWindows/CVI libraries. With few exceptions, each LabWindows/CVI library function has a fixed number of parameters, and each parameter has a definite data type. Each formatting and scanning function, however, takes a variable number of parameters, and the parameters can be of various data types. This difference is necessary to give the formatting and scanning functions versatility.
For instance, a single Scan function call performs disparate operations, such as the following.
· Find the two numeric values in the string:
“header: 45, -1.03e-2”
and place the first value in an integer variable and the second in a real variable.
· Take the elements from an integer array, swap the high and low bytes in each element, and place the resulting values in a real array.
To perform these operations, each formatting and scanning function takes a format string as one of its parameters. In effect, a format string is a mini- program that instructs the formatting and scanning functions on how to transform the input arguments to the output arguments. For conciseness, format strings are constructed using single-character codes. These codes are

© National Instruments Corporation

2-3

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

described in detail in the Using the Formatting and Scanning Functions section later in this chapter.
You may find the formatting and scanning functions more difficult to learn than other LabWindows/CVI functions. To help you in this learning process, read the discussions in the Formatting and I/O Library Programming Examples section at the end of this chapter.

Formatting and I/O Library Function Reference
This section gives a brief description of each of the functions available in the LabWindows/CVI Formatting and I/O Library. The LabWindows/CVI Formatting and I/O Library functions are arranged alphabetically.

ArrayToFile
int status = ArrayToFile (char fileName, void array, int dataType, int numberOfElements, int numberOfGroups, int arrayDataOrder, int fileLayout, int colSepStyle, int fieldWidth, int fileType, int fileAction);
Purpose
Saves an array to a file using various formatting options. The function handles creating, opening, writing, and closing the file. The file can later be read back into an array using the FileToArray function.
Parameters

Input

fileName array dataType numberOfElements numberOfGroups arrayDataOrder fileLayout colSepStyle fieldWidth fileType fileAction

string void * integer integer integer integer integer integer integer integer integer

File pathname. Numeric array. Array element data type. Number of elements in array. Number of groups in array. How groups are ordered in file. Direction to write groups in file. How data on one line are separated. Constant width between columns. ASCII/binary mode. File pointer reposition location.

LabWindows/CVI Standard Libraries

2-4

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Return Value

status

integer

Indicates success/failure.

Return Codes

0

Success.

-1

Error attempting to open file.

-2

Error attempting to close file.

-3

An I/O error occurred.

-4

Invalid dataType parameter.

-5

Invalid numberOfElements parameter.

-6

Invalid numberOfGroups parameter.

-7

Invalid arrayDataOrder parameter.

-8

Invalid fileLayout parameter.

-9

Invalid fileType parameter.

-10

Invalid separationStyle parameter.

-11

Invalid fieldWidth parameter.

-12

Invalid fileAction parameter.

Parameter Discussion
FileName may be an absolute pathname or a relative file name. If you use a relative file name, the file is created relative to the current working directory.
DataType must be one of the following.
VAL_CHAR VAL_SHORT_INTEGER VAL_INTEGER VAL_FLOAT VAL_DOUBLE VAL_UNSIGNED_SHORT_INTEGER VAL_UNSIGNED_INTEGER VAL_UNSIGNED_CHAR
If you save the array data in ASCII format, you may divide the array data into groups. Groups can be written as either columns or rows. NumberOfGroups specifies the number of groups into which to divide the array data. If you do not want to divide your data into groups, use 1.
If you divide your array data into groups, arrayDataOrder specifies how the data is ordered in the array. The two choices are as follows.

© National Instruments Corporation

2-5

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

· VAL_GROUPS_TOGETHER–all points of each data group are assumed to be stored consecutively in the data array.
· VAL_DATA_MULTIPLEXED–it is assumed that the first point from each data group is stored together, followed by the second point from each group and so on.
If you save the array data in ASCII format, fileLayout specifies how the data appears in the file. The two choices are as follows.
· VAL_GROUPS_AS_COLUMNS
· VAL_GROUPS_AS_ROWS
If you have only one group, use VAL_GROUPS_AS_COLUMNS to write each array element on a separate line.
If you specify that multiple values be written on each line, colSepStyle specifies how the values are separated. The choices are as follows.
· VAL_CONST_WIDTH–constant field width for each column
· VAL_SEP_BY_COMMA–values followed by commas, except last value on line
· VAL_SEP_BY_TAB–values separated by tabs
If you have specified a colSepStyle of VAL_CONST_WIDTH, fieldWidth specifies the width of the columns.
FileType specifies whether to create the file in ASCII or binary format.
The choices are as follows.
· VAL_ASCII
· VAL_BINARY
FileAction specifies the location in the file to begin writing data if the named file already exists. The choices are as follows.
· VAL_TRUNCATE–Positions the file pointer to the beginning of the file and deletes its prior contents.
· VAL_APPEND–All write operations append data to file.
· VAL_OPEN_AS_IS–Positions the file pointer at the beginning of the file but does not affect the prior file contents.

LabWindows/CVI Standard Libraries

2-6

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

CloseFile
int status = CloseFile (int fileHandle); Purpose
Closes the file associated with fileHandle. fileHandle is the file handle that was returned from the OpenFile function and specifies the file to close. Parameter

Input

fileHandle

integer

File handle.

Return Value

status

integer

Result of the close file operation.

Return Codes
-1 0

Bad file handle. Success.

CompareBytes
int result = CompareBytes (char buffer#1, int buffer#1Index, char buffer#2, int buffer#2Index, int numberofBytes, int caseSensitive);
Purpose
Compares the numberofBytes starting at position buffer#1Index of buffer#1 to the numberofBytes starting at position buffer#2Index of buffer#2.
Parameters

Input

buffer#1 buffer#1Index buffer#2 buffer#2Index numberofBytes caseSensitive

string integer string integer integer integer

String 1. Starting position in buffer#1. String 2. Starting position in buffer#2. Number of bytes to compare. Case sensitivity mode.

© National Instruments Corporation

2-7

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Return Value

result

integer

Result of the compare operation.

Return Codes
-1 0 1

Bytes from buffer#1 less than bytes from buffer#2. Bytes from buffer#1 identical to bytes from buffer#2. Bytes from buffer#1 greater than bytes from buffer#2.

Parameter Discussion
Both buffer#1Index and buffer#2Index are zero-based.
If caseSensitive is zero, alphabetic characters are compared without regard to case. If caseSensitive is non-zero, alphabetic characters are considered equal only if they have the same case.
The function returns an integer value indicating the lexicographic relationship between the two sets of bytes.

CompareStrings
int result = CompareStrings (char string#1, int string#1Index, char string#2, int string#2Index, int caseSensitive);
Purpose
Compares the NUL-terminated string starting at position string#1Index of string#1 to the NUL-terminated string starting at position string#2Index of string#2. Both string#1Index and string#2Index are zero-based.
Parameters

Input

string#1 string#1Index string#2 string#2Index caseSensitive

string integer string integer integer

String 1. Starting position in string#1. String 2. Starting position in string#2. Case sensitivity mode.

LabWindows/CVI Standard Libraries

2-8

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Return Value

result

integer

Result of the compare operation.

Return Codes
-1 0 1

Bytes from string#1 less than bytes from string#2. Bytes from string#1 identical to bytes from string#2. Bytes from string#1 greater than bytes from string#2.

Parameter Discussion
If caseSensitive is zero, alphabetic characters are compared without regard to case. If caseSensitive is non-zero, alphabetic characters are equal only if they have the same case.
The function returns an integer value indicating the lexicographic relationship between the two strings.

CopyBytes
void CopyBytes (char targetBuffer[], int targetIndex, char *sourceBuffer, int sourceIndex, int numberofBytes);
Purpose
Copies the numberofBytes bytes starting at position sourceIndex of sourceBuffer to position targetIndex of targetBuffer.
Parameters

Input Output

targetIndex
sourceBuffer sourceIndex
numberofBytes targetBuffer

integer
string integer
integer string

Starting position in targetBuffer. Source buffer. Starting position in sourceBuffer. Number of bytes to copy.
Destination buffer.

Return Value None

© National Instruments Corporation

2-9

LabWindows/CVI Standard Libraries

Formatting and I/O Library
Parameter Discussion Both sourceIndex and targetIndex are zero-based. You can use this function even when sourceBuffer and targetBuffer overlap.

Chapter 2

CopyString
void CopyString (char targetString[], int targetIndex, char *sourceString, int sourceIndex, int maximum#Bytes);
Purpose
Copies the string starting at position sourceIndex of sourceString to position targetIndex of targetString until an ASCII NUL is copied or maximum#Bytes bytes have been copied. Appends an ASCII NUL if no ASCII NUL was copied.
Parameters

Input

targetIndex

integer

sourceString

string

sourceIndex

integer

maximum#Bytes integer

Output targetString

string

Starting position in targetString. Source buffer. Starting position in sourceString. Number of bytes to copy, excluding the ASCII NUL. Destination buffer.

Return Value
None
Parameter Discussion
Both sourceIndex and targetIndex are zero-based. If you want to use maximum#Bytes to prevent from writing beyond the end of targetString, make sure that you allow room for the ASCII NUL. For example, if maximum#Bytes is 40, the destination buffer should contain at least 41 bytes.
If you do not want to specify a maximum number of bytes to copy, use -1 for maximum#Bytes.
You can use this function even when sourceString and targetString overlap.
Note: The value of maximum#Bytes must not exceed one less than the number of bytes in the target variable.

LabWindows/CVI Standard Libraries

2-10

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

FileToArray
int status = FileToArray (char fileName, void array, int dataType, int numberOfElements, int numberOfGroups, int arrayDataOrder, int fileLayout, int fileType);
Purpose
Reads data from a file into an array. Can be used with files created using the ArrayToFile function. The function handles creating, opening, reading, and closing the file.
Parameters

Input Output

fileName dataType numberOfElements numberOfGroups arrayDataOrder fileLayout fileType array

string integer integer integer integer integer integer void*

File pathname. Array element data type. Number of elements in array. Number of Groups in array. How groups are ordered in file. Direction to write groups in file. ASCII/binary mode. Numeric array.

Return Value

status

integer

Indicates success or failure.

Return Code
0 -1 -2 -3 -4 -5 -6 -7 -8 -9

Success. Error attempting to open file. Error attempting to close file. An I/O error occurred. Invalid arrayDataType parameter. Invalid numberOfElements parameter. Invalid numberOfGroups parameter. Invalid arrayDataOrder parameter. Invalid fileLayout parameter. Invalid fileType parameter.

© National Instruments Corporation

2-11

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Parameter Discussion
FileName may be an absolute pathname or a relative file name. If you use a relative file name, the file is located relative to the current working directory.
DataType must be one of the following.
· VAL_CHAR · VAL_SHORT_INTEGER · VAL_INTEGER · VAL_FLOAT · VAL_DOUBLE · VAL_UNSIGNED_SHORT_INTEGER · VAL_UNSIGNED_INTEGER · VAL_UNSIGNED_CHAR
NumberOfGroups specifies the number of groups into which the data in the file is divided. Groups can be in the form of either columns or rows. If there are no groups, use 1. This parameter only applies if the file type is ASCII.
If the data is divided into groups, arrayDataOrder specifies the order in which the data is to be stored in the array. The two choices are as follows.
· VAL_GROUPS_TOGETHER– all points from one data group are stored together followed by all points from the next data group.
· VAL_DATA_MULTIPLEXED–the first points from each data group are stored consecutively, followed by the second points from each group, etc.
If the file is in ASCII format, fileLayout specifies how the data appears in the file. The two choices are as follows.
· VAL_GROUPS_AS_COLUMNS · VAL_GROUPS_AS_ROWS
If there is only one group, VAL_GROUPS_AS_COLUMNS specifies that each value in the file is on a separate line.
FileType specifies whether the file is in ASCII or binary format. The choices are as follows.
· VAL_ASCII · VAL_BINARY

LabWindows/CVI Standard Libraries

2-12

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

FillBytes
void FillBytes (char buffer[], int startingIndex, int numberofBytes, int value); Purpose Sets the numberofBytes bytes starting at position startingIndex of buffer to the value in the lower byte of value. startingIndex is zero-based. Parameters

Input

buffer startingIndex numberofBytes value

string integer integer integer

Destination buffer. Starting position in buffer. Number of bytes to fill. Value to place in bytes.

Return Value None

FindPattern
int ndx = FindPattern (char buffer, int startingIndex, int numberofBytes, char pattern, int caseSensitive, int startFromRight);
Purpose
Searches a character buffer for a pattern of bytes. The pattern of bytes is specified by the string pattern.
Parameters

Input

buffer startingIndex numberofBytes pattern caseSensitive startFromRight

string integer integer string integer integer

Buffer to be searched. Starting position in buffer. Number of bytes to search. Pattern to search for. Case-sensitivity mode. Direction of search.

© National Instruments Corporation

2-13

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Return Value

ndx

integer

Index in buffer where pattern

was found.

Return Code

-1

Pattern not found.

Parameter Discussion
The buffer searched is the set of numberofBytes bytes starting at position startingIndex of buffer. Exception: If numberofBytes is -1, the buffer searched is the set of bytes starting at position startingIndex of buffer up to the first ASCII NUL. startingIndex is zero-based.
If caseSensitive is zero, alphabetic characters are compared without regard to case. If caseSensitive is non-zero, alphabetic characters are considered equal only if they have the same case. If startFromRight is zero, the leftmost occurrence of the pattern in the buffer will be found. If startFromRight is non-zero, the rightmost occurrence of the pattern in the buffer will be found.
If the pattern is found, pattern returns the index relative to the beginning of buffer where it found the first byte of the pattern. If the pattern is not found, pattern returns -1.
The following example returns 4, which is the index of the second of the three occurrences of ab in the string 1ab2ab3ab4. The first occurrence is skipped because startingIndex is 3. Of the two remaining occurrences, the leftmost is found because startFromRight is zero:
ndx = FindPattern (“1ab2ab3ab4”, 3, -1, “AB”, 0, 0);
On the other hand, the following line returns 7, which is the index of the last occurrence of ab, because startFromRight is non-zero:
ndx = FindPattern (“1ab2ab3ab4”, 3, -1, “AB”, 0, 1);

Fmt
int n = Fmt (void target, char formatString, source1,…,sourcen);
Purpose
Formats the source1 … sourcen arguments according to descriptions in the formatString argument.

LabWindows/CVI Standard Libraries

2-14

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Parameters

Input Output

formatString

String.

source1,…,sourcen Types must match formatString contents.

target

Type must match formatString contents.

Return Value

n

integer

Number of source format

specifiers satisfied.

Return Code -1

Format string error.

Using This Function
This function places the result of the formatting into the target argument, which you must pass by reference. The return value indicates how many source format specifiers were satisfied, or -1 if the format string is in error. A complete discussion of this function is in the Using the Formatting and Scanning Functions section later in this chapter.

FmtFile
int n = FmtFile (int fileHandle, char *formatString, source1,…,sourcen);
Purpose
Formats the source1 … sourcen arguments according to descriptions in the formatString argument. The result of the formatting is written into the file corresponding to the fileHandle argument, which was obtained by a call to the LabWindows/CVI function OpenFile.
Parameters

Input

fileHandle formatString source1,…,sourcen

integer string types must match formatString contents

File handle.

© National Instruments Corporation

2-15

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Return Value

n

integer

Number of source format

specifiers satisfied.

Return Codes
-1 -2

Format string error I/O error.

Using This Function
The return value indicates how many source format specifiers were satisfied, -1 if the format string is in error, or -2 if there was an I/O error. A complete discussion of this function is in the Using the Formatting and Scanning Functions section later in this chapter.

FmtOut
int n = FmtOut (char *formatString, source1,…,sourcen); Purpose Formats the source1 … sourcen arguments according to descriptions in the formatString argument. The result of the formatting is written to the Standard I/O window. Parameters

Input

formatString

String.

source1,…,sourcen Types must match formatString contents.

Return Value

n

integer

Number of source format

specifiers satisfied.

Return Codes
-1 -2

Format string error. I/O error.

LabWindows/CVI Standard Libraries

2-16

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Using This Function
The return value indicates how many source format specifiers were satisfied, -1 if the format string is in error, or -2 if there was an I/O error. A complete discussion of this function is in the Using the Formatting and Scanning Functions section later in this chapter.

GetFileInfo
int status = GetFileInfo (char fileName, long fileSize); Purpose Verifies if a file exists. Returns an integer value of zero if no file is present and 1 if file is present. fileSize is a long variable that contains the file size in bytes or zero if no file exists.
Parameters

Input Output

fileName fileSize

string long

Pathname of the file to be checked.
File size or zero.

Return Value

status

integer

Indicates if the file exists.

Return Codes
1 0 -1

File exists. File does not exist. Maximum number of files already open.

Example
/ Check for presence of file A:DATATEST1.DAT. / / Print its size / / if file exists or message stating file does not exist. / int n; long size; n = GetFileInfo(“a:\data\test1.dat”,&size); if (n == 0)
FmtOut(“File does not exist.”); else
FmtOut(“File size = %i[b4]”,size);

© National Instruments Corporation

2-17

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

GetFmtErrNdx
int n = GetFmtErrNdx (void); Purpose Returns the zero-based index into the format string where an error occurred in the last formatting or scanning call. Parameters
None Return Value

n

integer

Position of error in format

string.

Return Code

-1

No error.

Using This Function
If the format string of the preceding call contains an error, such as an invalid format, or inappropriate modifier, the return value indicates the position within the format string, beginning with position zero, where the error was found. The function can report only one error per call, even if several errors existed within the string.
Example
int i, n; Scan (“1234”, “%s>%d”, &i); n = GetFmtErrNdx (); / n will have the value -1, indicating that / / there was no error found in the format string. /

GetFmtIOError
int status = GetFmtIOError (void);
Purpose
This function returns specific I/O information for the last call to a Formatting and I/O function that performs file I/O. If the last function was successful, GetLastFmtIOError returns zero (no

LabWindows/CVI Standard Libraries

2-18

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

error). If the last function that performs I/O encountered an I/O error, GetLastFmtIOError returns a nonzero value.
Return Value

status

integer

Indicates success or failure of last function that performed file I/O.

Return Codes

FmtIONoErr

0

FmtIONoFileErr

1

FmtIOGenErr

2

FmtIOBadHandleErr 3

FmtIOInsuffMemErr 4

FmtIOFileExistsErr 5

FmtIOAccessErr

6

FmtIOInvalArgErr

7

FmtIOMaxFilesErr

8

FmtIODiskFullErr

9

FmtIONameTooLongErr 10

No error. File not found. General I/O error. Invalid file handle. Not enough memory. File already exists. Permission denied. Invalid argument. Maximum number of files open. Disk is full. File name is too long.

GetFmtIOErrorString
char *message = GetFmtIOErrorString (int errorNum); Purpose Converts the error number returned by GetLastFmtIOError into a meaningful error message. Parameters

Input errorNum integer Error Code returned by GetLastFmtIOErr.

Return Value

message

string

Explanation of error.

© National Instruments Corporation

2-19

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

NumFmtdBytes
int n = NumFmtdBytes (void); Purpose Returns the number of bytes formatted or scanned by the previous formatting or scanning call. Parameters
None Return Value

n

integer

Number of bytes formatted or

scanned.

Using This Function
If the previous call was a formatting call, NumFmtdBytes returns the number of bytes placed into the target. If the previous call was a scanning call, NumFmtdBytes returns the number of bytes scanned from the source. The return value is undefined if there have been no preceding formatting or scanning calls.
Certain operations using the FmtFile and ScanFile routines can result in more than 64 KB being formatted or scanned. Because NumFmtdBytes returns an integer, its value will not be accurate in these cases. The value returned rolls over when formatting or scanning more than 65,535 bytes.
Example
double f; int n; Scan (“3.1416”, “%s>%f”, &f); n = NumFmtdBytes (); / n will have the value 6, indicating that six bytes / / were scanned from the source string. /

OpenFile
int handle = OpenFile (char *fileName, int read/writeMode, int action, int fileType); Purpose Opens a file for input and/or output.

LabWindows/CVI Standard Libraries

2-20

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Parameters

Input

fileName read/writeMode action fileType

string integer integer integer

Pathname. Read/write mode. File pointer reposition location. ASCII/binary mode.

Return Value

handle

integer

File handle to be used in subsequent ReadFile/WriteFile calls.

Return Code

-1

Function failed, unable to open file, or bad argument

to function.

Parameter Discussion
fileName is a pathname specifying the file to be opened. If the read/writeMode argument is write or read/write, this function creates the file if it does not already exist. If a file is created, it is created with no protection; that is, both reading and writing can be performed on it. Use the function GetFileInfo if it is necessary to determine whether a file already exists.
read/writeMode specifies how the file is opened:
· VAL_READ_WRITE = open file for reading and writing
· VAL_READ_ONLY = open file for reading only
· VAL_WRITE_ONLY = open file for writing only
action specifies whether to delete the old contents of the file, and whether to force the file pointer to the end of the file before each write operation. action is meaningful only if read/writeMode = write or read/write. After read operations are performed, the file pointer points to the byte following the last byte read. action values are as follows:
· VAL_TRUNCATE = truncate file (deletes its old contents and positions the file pointer at the beginning of the file.
· VAL_APPEND = do not truncate file (all write operations append to end of file).
· VAL_OPEN_AS_IS = do not truncate file (positions the file pointer at the beginning of the file. )

© National Instruments Corporation

2-21

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

fileType specifies whether to treat file as ASCII or binary. When performing I/O on a file in binary mode, no special treatment is given to carriage returns (CR) and line feeds (LF). When you open the file in ASCII mode, CR LF combination translates to LF when reading, and LF translates to CR LF when writing. fileType values are as follows:
· VAL_BINARY = binary
· VAL_ASCII = ASCII

ReadFile
int n = ReadFile (int fileHandle, char buffer[], int count);
Purpose
Reads up to count bytes of data from a file or STDIN into buffer. Reading starts at the current position of the file pointer. When the function completes, the file pointer points to the next unread character in the file.
Parameters

Input Output

fileHandle count buffer

integer integer string

File handle. Number of bytes to read. Input buffer.

Return Value

n

integer

Number of bytes read.

Return Codes
-1 0

Error, possibly bad handle. Tried to read past end-of-file.

Parameter Discussion
fileHandle is the file handle returned by the OpenFile function. fileHandle points to the file from which you want to read. If fileHandle =0, input is read from STDIN, and no prior OpenFile call is needed. buffer is the buffer into which you read data. You must allocate space for this buffer before you call this function. count specifies the number of bytes to read. count must not be greater than buffer size.

LabWindows/CVI Standard Libraries

2-22

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Using This Function
The return value can be less than number of bytes requested if end of file was reached before byte count was satisfied. Notice that if you open the file in ASCII mode, each CR LF combination read is counted as 1 character, because the pair is translated into LF when stored in the buffer.
Note: This function does not terminate the buffer with an ASCII NUL.

ReadLine
int n = ReadLine (int fileHandle, char lineBuffer[], int maximum#Bytes); Purpose Reads bytes from a file until a linefeed is encountered. Parameters

Input

fileHandle

integer

maximum#Bytes integer

Output

lineBuffer

string

File handle.
Maximum number of bytes to read into line, excluding the ASCII NUL.
Input buffer.

Return Value

n

integer

Number of bytes read,

excluding linefeed.

Return Codes

-2

End of file.

-1

I/O error.

Parameter Discussion
This function places up to maximum#Bytes bytes, excluding the linefeed, into lineBuffer. Appends an ASCII NUL to lineBuffer. If there are more than maximum#Bytes bytes before the linefeed, the extra bytes are discarded.
fileHandle is the file handle that was returned from the OpenFile function and specifies the file from which to read the line. The file should be opened in ASCII mode so that a

© National Instruments Corporation

2-23

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

carriage-return/linefeed combination will be treated as a linefeed. If fileHandle is zero, the line will be read from the standard input.
lineBuffer is a character buffer. It should be large enough to contain maximum#Bytes bytes plus an ASCII NUL.
ReadLine returns the number of bytes read from the file, including discarded bytes, but excluding the linefeed. Hence, the return value will exceed maximum#Bytes if and only if bytes are discarded.
If no bytes are read because the end of the file has been reached, ReadLine returns -2. If an I/O error occurs, ReadLine returns -1.

Scan
int n = Scan (void source, char formatString, targetptr1,…,targetptrn); Purpose Scans a single source item in memory and breaks it into component parts according to format specifiers found in a formatString. The components are then placed into the target parameters. Parameters

Input Output

source formatString targetptr1,…,targetptrn

Type must match formatString contents string. Types must match formatString contents.

Return Value

n

integer Number of target format

specifiers satisfied.

Return Code -1

Format string error.

Using This Function
The return value indicates how many target format specifiers were satisfied, or -1 if the format string is in error. A complete discussion of this function is in the Using the Formatting and Scanning Functions section later in this chapter.

LabWindows/CVI Standard Libraries

2-24

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

ScanFile
int n = ScanFile (int fileHandle, char *formatString, targetptr1,…,targetptrn);
Purpose
Performs the same basic operation as the Scan function, except that the source material is obtained from the file referred to by the fileHandle argument, which is obtained by calling the LabWindows/CVI function OpenFile.
Parameters

Input Output

fileHandle formatString targetptr1,…,targetptrn

Integer. String. Types must match formatString contents.

Return Value

n

integer Number of target format

specifiers satisfied.

Return Codes

-1

Format string error.

-2

I/O error.

Using This Function
The amount of data read from the file depends on the amount needed to fulfill the formats in the format string. The return value indicates how many target format specifiers were satisfied, -1 if the format string is in error, or -2 if there was an I/O error. A complete discussion of this function is in the Using the Formatting and Scanning Functions section later in this chapter.

ScanIn
int n = ScanIn (char *formatString, targetptr1,…,targetptrn);
Purpose
Performs the same basic operation as the ScanFile function, except that the source material is obtained from STDIN.

© National Instruments Corporation

2-25

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Parameters

Input Output

formatString targetptr1,…,targetptrn

String. Types must match formatString contents.

Return Value

n

integer Number of target format

specifiers satisfied.

Return Codes

-1

Format string error.

-2

I/O error.

Using This Function
No argument is required for the source item in the case of the ScanIn function. The return value indicates how many target format specifiers were satisfied, -1 if the format string is in error, or -2 if there was an I/O error. A complete discussion of this function is in the Using the Formatting and Scanning Functions section later in this chapter.

SetFilePtr
long position = SetFilePtr (int fileHandle, long offset, int origin); Purpose Moves the file pointer for the file specified by fileHandle to a location that is offset bytes from origin. Returns the offset of the new file pointer position from the beginning of the file. Parameters

Input

fileHandle offset origin

integer long integer integer

File handle returned by OpenFile.
Number of bytes from origin to position of file pointer.
Position in file from which to base offset.

LabWindows/CVI Standard Libraries

2-26

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Return Value

position

long integer

Offset of the new file pointer position from the beginning of the file.

Return Code

-1

Error due to an invalid file handle, an invalid origin

value, or an offset value that is before the beginning

of the file.

Parameter Discussion
The valid values of origin are as follows:
· 0 = beginning of file
· 1 = current position of file pointer
· 2 = end of file
Using This Function
This function can also be used to obtain the file size by setting offset to 0 and origin to 2. In this case, the return value indicates the file size and the pointer will be at the end of the file.
It is possible to position the file pointer beyond the end of the file. Intermediate bytes (bytes between the old end of file and the new end of file) contain indeterminate values. An attempt to position the file pointer before the beginning of the file causes the function to return an error.
If the file is a device that does not support random access (such as the standard input), the function returns an indeterminate value.
Example
/ Open or create the file c:TEST.DAT, move 10 bytes into the file, and write a string to the file. /
/ Note: Use \ in pathname in C instead of . / int handle,result; long position; handle = OpenFile(“c:\TEST.DAT”, 0, 2, 1); if (handle == -1){
FmtOut(“error opening file”); exit(1); } position = SetFilePtr(handle, 10L, 0); if (position == 10){

© National Instruments Corporation

2-27

LabWindows/CVI Standard Libraries

Formatting and I/O Library
result = WriteFile(handle, “Hello, World!”, 13); if (result == -1)
FmtOut(“error writing to file”); } else
FmtOut(“error positioning file pointer”); CloseFile(handle);

Chapter 2

StringLength
int n = StringLength (char *string); Purpose Returns the number of bytes in the string before the first ASCII NUL. Parameter

Input

string

String.

Return Value

n

integer

Number of bytes in string

before ASCII NUL.

Example
char s[100]; int nbytes; nbytes = StringLength (s);

StringLowerCase
void StringLowerCase (char string[]); Purpose Converts all uppercase alphabetic characters in the NUL-terminated string to lowercase. Parameter

Input/Output string

String.

LabWindows/CVI Standard Libraries

2-28

© National Instruments Corporation

Chapter 2
Return Value None

Formatting and I/O Library

StringUpperCase
void StringUpperCase (char string[]); Purpose Converts all lowercase alphabetic characters in the NUL-terminated string to uppercase. Parameter

Input/Output string

String.

Return Value None

WriteFile
int n = WriteFile (int fileHandle, char *buffer, unsigned int count);
Purpose
Writes up to count bytes of data from buffer to a file or to STDOUT. Writing starts at the current position of the file pointer, and when the function completes, the file pointer is incremented by the number of bytes written.
Parameters

Input

fileHandle buffer count

integer string integer

File handle. Data buffer. Number of bytes to write.

Return Value

n

integer

Number of bytes written to the

file.

© National Instruments Corporation

2-29

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Return Code -1

Error.

Parameter Discussion
fileHandle is the file handle that was returned from the OpenFile function. If fileHandle=1, data is written to STDOUT and no prior OpenFile call is needed.
buffer is the buffer from which to write data.
count specifies number of bytes to write. The count parameter overrides the buffer size in determining the number of bytes to write. Buffers containing embedded NUL bytes are written in full. count must not be greater than buffer size.
Using This Function
For files opened in ASCII mode, each LF character is replaced with a CR-LF combination in the output. In this case, the return value does not include the CR character written to the output.
An error can indicate a bad file handle, an attempt to access a protected file, an attempt to write to a file opened as ReadOnly, or no more space left on disk.

WriteLine
int n = WriteLine (int fileHandle, char *lineBuffer, int numberofBytes); Purpose Writes numberofBytes bytes from lineBuffer to a file and then writes a linefeed to the file. Parameters

Input

fileHandle lineBuffer numberofBytes

integer string integer

File handle. Data buffer. Number of bytes to write.

Return Value

n

integer

Number of bytes written.

including line feed.

LabWindows/CVI Standard Libraries

2-30

© National Instruments Corporation

Chapter 2

Formatting and I/O Library

Return Code

-1

I/O error.

Parameter Discussion
If numberofBytes is -1, only the bytes in lineBuffer before the first ASCII NUL are written, followed by a linefeed.
fileHandle is the file handle that was returned from the OpenFile function. The file should be opened in ASCII mode so that a carriage return will be written before the linefeed. If fileHandle is 1, the line will be written to the STDOUT.
Using This Function
WriteLine returns the number of bytes written to the file, excluding the linefeed. If an I/O error occurs, WriteLine returns -1.

Using the Formatting and Scanning Functions
You use data formatting functions to translate or reformat data items into other forms. Typical usages might be to translate between data stored on external files and the internal forms which the program can manipulate, or to reformat a foreign binary representation into one on which the program can operate.
There are three subclasses of data formatting functions in the LabWindows/CVI Formatting and I/O Library:
· Formatting functions
· Scanning functions
· Status functions
You use formatting functions to combine and format one or more source items into a single target item, and you use scanning functions to break apart a single source item into several target items. The status functions return information regarding the success or failure of the formatting or scanning functions.
Introductory Formatting and Scanning Examples
To introduce you to the formatting and scanning functions, consider the following examples.

© National Instruments Corporation

2-31

LabWindows/CVI Standard Libraries

Formatting and I/O Library

Chapter 2

Convert the integer value 23 to its ASCII representation and place the contents in a string variable:
char a[5]; int b,n; b = 23; n = Fmt (a, “%s<%i”, b);
After the Fmt call, a contains the string 23.
In this example, a is the target argument, b is the source argument, and the string %s<%i is the format string. The Fmt call uses the format string to determine how to convert the source argument into the target argument.
With the Scan function, you can convert the string 23 to an integer:
char *a; a = “23”; n = Scan (a$, “%s>%i”, b%);
After the Scan call, b = 23.
In this example, a is the source argument, b is the target argument, and %s>%i is the format string.

References

• edit.com is for sale | www.oxley.com
• Test and Measurement Systems, a part of Emerson - NI

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>