® LabWindows /CVI Standard Libraries Reference Manual July 1996 Edition Part Number 320682C-01 © Copyright 1994, 1996 National Instruments Corporation. All rights reserved.
Internet Support GPIB: gpib.support@natinst.com DAQ: daq.support@natinst.com VXI: vxi.support@natinst.com LabVIEW: lv.support@natinst.com LabWindows: lw.support@natinst.com HiQ: hiq.support@natinst.com VISA: visa.support@natinst.com Lookout: lookout.support@natinst.com FTP Site: ftp.natinst.com Web Address: www.natinst.
Warranty The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period.
WARNING REGARDING MEDICAL AND CLINICAL USE OF NATIONAL INSTRUMENTS PRODUCTS National Instruments products are not designed with components and testing intended to ensure a level of reliability suitable for use in treatment and diagnosis of humans. Applications of National Instruments products involving medical or clinical treatment can create a potential for accidental injury caused by product failure, or by errors on the part of the user or application designer.
Contents _____________________________________________________________________________ About This Manual...........................................................................................................xvii Organization of This Manual .......................................................................................xvii Conventions Used in This Manual ...............................................................................xix The LabWindows/CVI Documentation Set .......................
Contents GetFmtErrNdx..................................................................................................2-18 GetFmtIOError .................................................................................................2-18 GetFmtIOErrorString .......................................................................................2-19 NumFmtdBytes ................................................................................................2-20 OpenFile ....................................
Contents Integer Array to Binary File, Assuming a Fixed Number of Elements.............................................................................2-54 Real Array to Binary File, Assuming a Fixed Number of Elements.............................................................................2-54 Real Array to Binary File, Assuming a Variable Number of Elements.............................................................................2-55 A Variable Portion of a Real Array to a Binary File.............
Contents Chapter 3 Analysis Library ...............................................................................................................3-1 Analysis Library Function Overview...........................................................................3-1 The Analysis Library Function Panels .............................................................3-1 Hints for Using Analysis Function Panels ...........................................3-3 Reporting Analysis Errors................................
Contents ToPolar1D ........................................................................................................3-33 ToRect ..............................................................................................................3-34 ToRect1D .........................................................................................................3-35 Transpose .........................................................................................................3-36 Error Conditions......
Contents ThreadIberr.......................................................................................................4-23 ThreadIbsta.......................................................................................................4-25 Chapter 5 RS-232 Library .................................................................................................................5-1 RS-232 Library Function Overview.............................................................................
Contents Chapter 6 DDE Library ......................................................................................................................6-1 DDE Library Function Overview.................................................................................6-1 The DDE Library Function Panels...................................................................6-1 DDE Clients and Servers..................................................................................6-2 The DDE Callback Function .......
Contents Chapter 8 Utility Library ...................................................................................................................8-1 The Utility Library Function Panels.............................................................................8-1 Utility Library Function Reference ..............................................................................8-5 Beep..................................................................................................................
Contents GetSystemDate.................................................................................................8-38 GetSystemTime................................................................................................8-39 GetWindowDisplaySetting...............................................................................8-39 InitCVIRTE......................................................................................................8-40 inp..............................................
Contents UnloadExternalModule ....................................................................................8-84 WriteToPhysicalMemory .................................................................................8-85 WriteToPhysicalMemoryEx.............................................................................8-86 Chapter 9 X Property Library .........................................................................................................9-1 X Property Library Overview.............
Contents Channel String for Analog Output Functions ..................................................10-7 Valid Counters for the Counter/Timer Functions ............................................10-7 Easy I/O for DAQ Function Reference ........................................................................10-8 AIAcquireTriggeredWaveforms ......................................................................10-8 AIAcquireWaveforms .........................................................................
Contents Tables Table 1-1. ANSI C Standard Library Classes .........................................................................1-1 Table 1-2. C Locale Information Values.................................................................................1-3 Table 2-1. The Formatting and I/O Library Function Tree.....................................................2-2 Table 3-1. The Analysis Library Function Tree......................................................................3-1 Table 3-2.
About This Manual The LabWindows/CVI Standard Libraries Reference Manual contains information about the LabWindows/CVI standard libraries—the Graphics Library, the Analysis Library, the Formatting and I/O Library, the GPIB Library, the GPIB-488.2 Library, the RS-232 Library, the Utility Library, and the system libraries.
About This Manual • Chapter 5, RS-232 Library, describes the functions in the LabWindows/CVI RS-232 Library. The RS-232 Library Function Overview section contains general information about the RS-232 Library functions and panels. The RS-232 Library Function Reference section contains an alphabetical list of function descriptions. • Chapter 6, DDE Library, describes the functions in the LabWindows/CVI DDE (Dynamic Data Exchange) Library.
About This Manual Conventions Used in This Manual The following conventions are used in this manual: bold Bold text denotes a parameter, menu item, return value, function panel item, or dialog box button or option. italic Italic text denotes emphasis, a cross reference, or an introduction to a key concept. bold italic Bold italic text denotes a note, caution, or warning. monospace Text in this font denotes text or characters that you should literally enter from the keyboard.
About This Manual The LabWindows/CVI Documentation Set For a detailed discussion of the best way to use the LabWindows/CVI documentation set, see the section Using the LabWindows/CVI Documentation Set in Chapter 1, Introduction to LabWindows/CVI of Getting Started with LabWindows/CVI. Related Documentation The following documents contain information that you may find helpful as you read this manual: • ANSI/IEEE Standard 488.
Chapter 1 ANSI C Library This chapter describes the ANSI C Standard Library as implemented in LabWindows/CVI. Note: When you link your executable or DLL with an external compiler, you are using the ANSI C library of the external compiler. Table 1-1.
ANSI C Library Chapter 1 Table 1-1. ANSI C Standard Library Classes (Continued) General Utilities String to Arithmetic Expression Random Number Generation Memory Management Searching and Sorting Integer Arithmetic Multibyte Character Sets Program Termination Environment String Handling Byte Operations String Operations String Searching Collation Functions Miscellaneous
Chapter 1 ANSI C Library Table 1-2. C Locale Information Values Name Type decimal_point char * "." thousands_sep char * "" Non-monetary digit group separator character or characters. grouping char * "" Non-monetary digit groupings. int_curr_symbol char * "" The three-character international currency symbol, plus the character used to separate the international symbol from the monetary quantity. currency_symbol char * "" The local currency symbol for the current locale.
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.
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.
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.
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.
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.
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.
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.
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.
Formatting and I/O Library Chapter 2 Table 2-1.
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.
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.
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.
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. • is assumed that the first point from each data group is stored together, followed by the second point from each group and so on. VAL_DATA_MULTIPLEXED—it If you save the array data in ASCII format, fileLayout specifies how the data appears in the file. The two choices are as follows.
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. integer Result of the close file operation. Return Value status Return Codes -1 Bad file handle. 0 Success.
Formatting and I/O Library Chapter 2 Return Value integer result Result of the compare operation. Return Codes -1 Bytes from buffer#1 less than bytes from buffer#2. 0 Bytes from buffer#1 identical to bytes from buffer#2. 1 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.
Chapter 2 Formatting and I/O Library Return Value integer result Result of the compare operation. Return Codes -1 Bytes from string#1 less than bytes from string#2. 0 Bytes from string#1 identical to bytes from string#2. 1 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.
Formatting and I/O Library Chapter 2 Parameter Discussion Both sourceIndex and targetIndex are zero-based. You can use this function even when sourceBuffer and targetBuffer overlap. 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.
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 string File pathname. dataType integer Array element data type.
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.
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 string Destination buffer. startingIndex integer Starting position in buffer. numberofBytes integer Number of bytes to fill. value integer Value to place in bytes.
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.
Chapter 2 Formatting and I/O Library Parameters Input formatString String. source1,…,sourcen Types must match formatString contents. Output target Type must match formatString contents. Return Value integer n 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.
Formatting and I/O Library Chapter 2 Return Value integer n Number of source format specifiers satisfied. Return Codes -1 Format string error -2 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.
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.
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 integer n Position of error in format string. Return Code -1 No error.
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 No error. FmtIONoFileErr 1 File not found. FmtIOGenErr 2 General I/O error. FmtIOBadHandleErr 3 Invalid file handle. FmtIOInsuffMemErr 4 Not enough memory. FmtIOFileExistsErr 5 File already exists.
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 integer n 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.
Chapter 2 Formatting and I/O Library Parameters Input fileName string Pathname. read/writeMode integer Read/write mode. action integer File pointer reposition location. fileType integer ASCII/binary mode. integer File handle to be used in subsequent ReadFile/WriteFile calls. Return Value handle 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.
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.
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.
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.
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 Integer. formatString String. targetptr1,…,targetptrn Types must match formatString contents.
Formatting and I/O Library Chapter 2 Parameters Input formatString String. Output targetptr1,…,targetptrn Types must match formatString contents. Return Value integer n 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.
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.
Formatting and I/O Library Chapter 2 result = WriteFile(handle, "Hello, World!", 13); if (result == -1) FmtOut("error writing to file"); } else FmtOut("error positioning file pointer"); CloseFile(handle); 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 integer n Number of bytes in string before ASCII NUL.
Chapter 2 Formatting and I/O Library Return Value None 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.
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.
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.
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.
Chapter 2 Formatting and I/O Library Each of these formatting functions return the number of source format specifiers satisfied. If there is an error in the format string, -1 is returned. The formatting functions are used to format and combine multiple source items into a single target item. The only difference in the workings of the three functions is the location of the target data. For the function Fmt, the target is a data item in memory which is passed to the function by reference.
Formatting and I/O Library Chapter 2 Format specifiers describe the inputs and outputs of data transformations. Each format specifier has the following form. % [ rep ] formatcode [[ modifiers ]] The character % introduces all format specifiers. rep indicates how many times the format repeats with respect to the arguments. formatcode is a code character which indicates the nature of the data items being formatted.
Chapter 2 Formatting and I/O Library f real number. This source or target specifier indicates that the corresponding parameter is a real number, or if rep is present, a real array. The function performs conversions to ASCII when converting to or from the string format %s. c character. This source or target specifier indicates that the corresponding parameter is an integer with one significant byte, or, if rep is present, an array of 1-byte integers.
Formatting and I/O Library Chapter 2 the integer is converted to a string format. You can enter any non-negative value here. If n is less than the number of digits required to represent the integer, an asterisk (*) will be inserted into the string to signify an overflow. The default for n is zero, which indicates that the integer can occupy whatever space is necessary. pc Specify Padding.
Chapter 2 Formatting and I/O Library Note: When using both the bn and on modifiers on an integer specifier, the bn modifier must be first. Formatting Floating-Point Modifiers (%f) bn Specify Length. The b floating-point modifier specifies the length of the floating-point argument, or the length of an individual array element, in bytes. The default length is 8 bytes; therefore, double-precision values do not need this modifier. Single-precision floating-point values are indicated by b4.
Formatting and I/O Library Chapter 2 t Truncate. The t floating-point modifier indicates that in floating-point to integer transformations, the floating-point value is truncated instead of rounded. This is the default. r Round. The r floating-point modifier indicates that in floating-point to integer transformations, the floating-point value is rounded instead of truncated. The default method is truncation. Note: The value can be represented in scientific notation even when the e modifier is absent.
Chapter 2 Formatting and I/O Library tn Terminate on Character. When applied to a source string, the t string modifier specifies that the source string is terminated on the first occurrence of the character n, where n is the ASCII value of the character. Thus, %s[t44] causes reading of the source string to stop on an ASCII comma. Using %s[t44] and the source string Hello, World! as an example, Hello is placed into the target.
Formatting and I/O Library Chapter 2 Fmt, FmtFile, FmtOut—Literals in the Format String Literal characters appearing in a formatting function format string indicate that the literal characters are to be combined with the source parameters in the appropriate positions. They do not correspond to any source parameters, but are copied directly into the target item. Since the left side of the < symbol must be a single format specifier, literal characters if present must be on the right side of the symbol.
Chapter 2 Formatting and I/O Library Scanning Functions—Format String Consider the following scanning function: n = Scan(source, formatstring, targetptr1, ..., targetptrn); where formatstring contains the information to transform the source argument to the targetptr arguments. Format strings for the scanning functions are of the following form.
Formatting and I/O Library Chapter 2 formatcode is specified with one of the following codes: s string. As a source or target specifier this indicates that the corresponding parameter is a character string. As a source specifier the number of bytes of the source parameter that are consumed depends on the target specifier. If the target specifier is %s, bytes are consumed until a termination character is encountered (see the t modifier for strings for more information on termination characters).
Chapter 2 Formatting and I/O Library f real number. As a source or target specifier, this indicates that the corresponding parameter is a real number, or if rep is present, a real array. As a source specifier in conversions to string formats, the floating-point value is converted into ASCII form.
Formatting and I/O Library Chapter 2 rn Specify Radix. The r integer modifier specifies the radix of the integer argument, which is important if the integer is converted from a string format. Legal radixes are 8 (octal), 10 (decimal, the default), 16 (hexadecimal), and 256 (a special radix representing single 8-bit ASCII characters). wn Specify String Size.
Chapter 2 Formatting and I/O Library short int instr_buf[100]; short int prog_buf[100]; status = ibrd (ud, instr_buf, 200); Scan (instr_buf, "%100d[b2o01]>%100d", prog_buf); If, instead, your GPIB instrument sends two-byte binary data in Motorola byte order, the Scan function should appear as follows. Scan (instr_buf, "%100d[b2o10]>%100d", prog_buf); In either case, the o modifier is used only on the buffer containing the raw data from the instrument (instr_buf).
Formatting and I/O Library Chapter 2 If the pn modifier is omitted, a default of p6 is used. The p modifier is valid for sources only. en Specify as Scientific Notation. The e floating-point modifier indicates that the string representation of the floating-point value is in scientific notation. If omitted, non-scientific notation is used. n is optional and specifies the number of digits to use in the exponent. For example, %f[e2] causes 10.0 to be formatted as 1.0e+01.
Chapter 2 Formatting and I/O Library than the number of bytes available from the source, the remaining bytes are filled with ASCII NULs if the q modifier is used or blanks if the q modifier is not present. When the w modifier is used in conjunction with the a modifier, n indicates the number of bytes to append to the string excluding the terminating ASCII NUL. If wn modifies a target string and n is larger than the number of bytes in the target argument, the target argument is overwritten in compiled C.
Formatting and I/O Library Chapter 2 x Discard Terminator. When applied to a target string, the x modifier specifies that the terminating character be discarded before the next target is filled in. Using %s>%s[xt59]%s[xt59] with the source string "abc;XYZ;", "abc" is placed in the first target and "XYZ" is placed in the second target. d Discard Data. When applied to a target specifier, the d modifier indicates that there is no target argument to correspond to the target specifier.
Chapter 2 Formatting and I/O Library Some formats may have been correctly detected in the input, and the corresponding target parameters will have been filled in. Formats situated after the literal which did not appear, however, will not have been executed. The function return value can be used to determine exactly how many target parameters were actually fulfilled by the input. You can use the function NumFmtdBytes to determine the number of bytes consumed from the source parameter.
Formatting and I/O Library Chapter 2 String to Integer and Real String to String String to Integer and String String to Real, Skipping over Non-Numeric Characters in the String String to Real, after Finding a Semicolon in the String String to Real, after Finding a Substring in the String String with Comma-Separated ASCII Numbers to Real Array Scanning Strings That Are Not NUL-Terminated Integer Array to Real Array Integer Array to Real Array with Byte Swapping Integer Array Containing 1-Byte Integers to R
Chapter 2 Formatting and I/O Library Fmt (buf, "%s<%i[w6p0]", a); a = 1234; Fmt (buf, "%s<%i[w2]", a); /* result: "001234" */ /* result: "*4" */ Remarks The results shown are the contents of buf after each call to Fmt. The last call demonstrates what occurs when the width specified by the w modifier is too small.
Formatting and I/O Library Fmt x = Fmt x = Fmt x = Fmt x = Fmt x = Fmt x = Fmt (buf, "%s<%f[p0]", x); 12.345; (buf, "%s<%f[p6]", x); -12.345; (buf, "%s<%f[w12]", x); -12.3456789; (buf, "%s<%f[w6]", x); 0.00000012; (buf, "%s<%f[p8]", x); 0.00000012; (buf, "%s<%f", x); 4.5e050; (buf, "%s<%f", x); Chapter 2 /* result: "12." */ /* result: "12.345000" */ /* result: "-12.345" */ /* result: "-12.3*" */ /* result: "0.00000012" */ /* result: "1.2e-007" */ /* result: "4.
Chapter 2 Formatting and I/O Library Integer and Real to String with Literals char buf[20]; int f, r; double v; f = 4; r = 3; v = 1.2; Fmt (buf, "%s
Formatting and I/O Library Chapter 2 if ((i % 5) == 4) WriteFile (file_handle, "\n", 1); } CloseFile (file_handle); Remarks The FmtFile call writes the ASCII representation of a real array element to the file, followed by a comma. The w modifier specifies that the number be right-justified in a 15-character field. The WriteFile call writes a linefeed to the file after every fifth call to FmtFile.
Chapter 2 Formatting and I/O Library Real Array to Binary File, Assuming a Variable Number of Elements void StoreArray (double x[], int count, char filename[]) { int file_handle; file_handle = OpenFile (filename, 2, 0, 0); FmtFile (file_handle, "%*f<%*f", count, count, x); CloseFile (file_handle); } Remarks This example shows how a function can be used to write an array of real numbers to a binary file. The function's parameters are a real array, the number of elements to be written, and the filename.
Formatting and I/O Library Chapter 2 Concatenating Two Strings char buf[30]; int wave_type, signal_output; char *wave_str, *signal_str; int nbytes; wave_type = 1; signal_output = 0; switch (wave_type) { case 0: wave_str = "SINE;" break; case 1: wave_str = "SQUARE;" break; case 2: wave_str = "TRIANGLE;" break; } switch (signal_output) { case 0: signal_str = "OUTPUT OFF;" break; case 1: signal_str = "OUTPUT ON;" break; } Fmt (buf, "%s<%s%s", wave_str, signal_str); nbytes = NumFmtdBytes (); Remarks The two
Chapter 2 Formatting and I/O Library case 2: Fmt (buf, "%s
Formatting and I/O Library Chapter 2 Writing a Line Containing an Integer with Literals to the Standard Output int a, b; a = 12; b = 34; FmtOut ("%s
Chapter 2 Formatting and I/O Library Scan/ScanFile/ScanIn Examples in C This section contains examples of program code that use the Scan, ScanFile, and ScanIn functions from the Formatting and I/O Library. To eliminate redundancy, the examples include no error checking on I/O operations in this section except for the ASCII File to Two Integers with Error Checking example.
Formatting and I/O Library Chapter 2 Scan considers the occurrence of a non-numeric character (such as the x in 32x1) to mark the end of the integer. s = "32567"; n = Scan (s, "%s>%i[w3]", &a); /* result: a = 325, n = 1 */ The w3 modifier specifies that only the first 3 bytes of the string are scanned.
Chapter 2 Formatting and I/O Library When locating a real number in a string, Scan skips over white space characters. If a nonnumeric character other than a white space character, +, or - is found before the first numeric character, the Scan call fails. Thus, Scan fails on the p in p12.3; it leaves the value in x unmodified and returns zero, indicating that no target specifiers were satisfied. s n s n s n = = = = = = "12.3m"; Scan (s, "%s>%f", &x); /* result: x = 12.3, n = 1 */ "12.3.
Formatting and I/O Library Chapter 2 String to String char *s; char buf[10]; int n; s = " abc "; n = Scan (s, "%s>%s", buf); s = " abc "; n = Scan (s, "%s>%s[y]", buf); /* result: buf = "abc" */ /* result: buf = " abc" */ Remarks When extracting a substring from a string, Scan skips leading spaces and tabs unless the y modifier is present.
Chapter 2 Formatting and I/O Library String to Integer and String char *s; char buf[10]; int a, n; s = "32abc"; n = Scan (s, "%s>%i%s", &a, buf); /* result: a = 32, buf = "abc", n = 2 */ s = "32abc"; n = Scan (s, "%s>%i %s", &a, buf); /* result: a = 32, buf = ?????, n = 1 */ Remarks After the first call to Scan, a = 32, buf = "abc", and n = 2. Notice there are no spaces in the format string between the two target specifiers. In the second call, there is a space between %i and %s.
Formatting and I/O Library Chapter 2 String to Real, After Finding a Semicolon in the String char *s; double x; int n; s = "TIME 12:45:00; 7.34"; n = Scan (s, "%s>%s[xdt59]%f", &x); /* result: x = 7.34, n = 2 */ Remarks Some strings returned by programmable instruments contain headers that consist of numeric as well as non-numeric data and are terminated by a particular character, such as a semicolon. This example shows how such a header can be skipped. The format string contains two target specifiers.
Chapter 2 Formatting and I/O Library String with Comma-Separated ASCII Numbers to Real Array char *s; int n; double a[5]; /* 5 8-byte real numbers */ s = "12.3, 45, 6.5, -1.3E-2, 4"; n = Scan (s, "%s>%5f[x]", a); /* result: a[0] = 12.3, a[1] = 45.0, a[2] = 6.5, */ /* a[3] = -0.013, a[4] = 4.0, n = 1 */ Remarks The x modifier causes the comma separators to be discarded. Scan considers an array target to be satisfied when at least one element of the array is filled in.
Formatting and I/O Library Chapter 2 This code shows how to insert an ASCII NUL at the end of the transferred bytes. After the assignment, s is NUL-terminated. Integer Array to Real Array int ivals[100]; double dvals[100]; Scan (ivals, "%100i>%100f", dvals); Remarks Each integer in ivals is converted to real number and then written into dvals.
Chapter 2 Formatting and I/O Library The first call to Scan treats the 1-byte integers as signed values (from -128 to +127). The second call includes a u in the format string. This causes Scan to treat the 1-byte integers as unsigned values (from 0 to 255).
Formatting and I/O Library Chapter 2 The first call to Scan assumes that the real number is at the beginning of s. The second call assumes that the real number starts at the sixth byte of s. The i5 modifier causes the first 5 bytes of s to be ignored. ASCII File to Two Integers with Error Checking int file_handle, n, a, b; file_handle = OpenFile ("FILE.
Chapter 2 Formatting and I/O Library then reads the correct number of elements into values. The x modifier causes the comma separators to be discarded. Binary File to Integer Array, Assuming a Fixed Number of Elements int readings[100]; int file_handle, nbytes; file_handle = OpenFile ("FILE.
Formatting and I/O Library Chapter 2 Remarks This example shows how a subroutine can be used to read an array of real numbers from a binary file. The subroutine takes as parameters a real array, the number of elements to be read, and the filename. The ScanFile call reads the first count elements of x from a binary file. The two asterisks (*) in the format string are matched to count. For instance, if count is 100, then the format string is equivalent to %100f>100f.
Chapter 2 Formatting and I/O Library writing beyond the end of filename. Notice that the width specified is one less than the size of filename. This allows room for the ASCII NUL that ScanIn appends at the end of filename. The q modifier causes ScanIn to fill any unused bytes at the end of filename with ASCII NULs. Without the q modifier, all unused bytes are filled with spaces, except for the ASCII NUL at the end.
Chapter 3 Analysis Library This chapter describes the functions in the LabWindows/CVI Analysis Library. The Analysis Library Function Overview section contains general information about the Analysis Library functions and panels. The Analysis Library Function Reference section contains an alphabetical list of the function descriptions.
Analysis Library Chapter 3 Table 3-1.
Chapter 3 Analysis Library The classes and subclasses in the function tree are described here. • • The Array Operations function panels perform arithmetic operations on 1D and 2D arrays. – 1D Operations, a subclass of Array Operations, contains function panels that perform 1D array arithmetic. – 2D Operations, a subclass of Array Operations, contains function panels that perform 2D array arithmetic. The Complex Operations function panels perform complex arithmetic operations.
Analysis Library Chapter 3 large amounts of data. Large double-precision arrays consume a lot of memory. If the results you want do not require that you keep the original array or intermediate arrays of data, perform analysis operations in place where possible. • The Interactive window maintains a record of generated code. If you forget to keep the code from a function panel, you can cut and paste code between the Interactive and Program windows.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in Table 3-2. Add1D int status = Add1D (double arrayX[], double arrayY[], int numberofElements, double outputArray[]); Purpose Adds one-dimensional (1D) arrays. The function obtains the ith element of the output array by using the following formula: zi = xi + yi The function performs the operation in place; that is, outputArray can be the same array as either arrayX or arrayY.
Analysis Library Chapter 3 Purpose Adds two (2D) arrays. The function obtains the (ith, jth) element of the output array by using the following formula. z i , j = x i , j + yi , j The function performs the operation in place; outputArray can be the same array as either arrayX or arrayY. Parameters Input arrayX double-precision 2D Input array. array arrayY double-precision 2D Input array. array numberofRows integer Number of elements in first dimension.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in Table 3-2. Copy1D int status = Copy1D (double inputArray[], int numberofElements, double outputArray[]); Purpose Copies the elements of the inputArray. This function is useful to duplicate arrays for in-place operations. Parameters Input inputArray double-precision Input array. array numberofElements integer Output outputArray Number of elements in inputArray. double-precision Duplicated array.
Analysis Library Chapter 3 Parameters Input Output xReal double-precision Real part of x. xImaginary double-precision Imaginary part of x. yReal double-precision Real part of y. yImaginary double-precision Imaginary part of y. outputReal double-precision Real part of z. outputImaginary double-precision Imaginary part of z. integer Refer to error codes in Table 3-2.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in Table 3-2. CxDiv int status = CxDiv (double xReal, double xImaginary, double yReal, yImaginary, double *outputReal, double *outputImaginary); Purpose Divides two complex numbers. The function obtains the resulting complex number by using the following formulas. zr = (xr*yr + xi*yi) / (yr2 + yi2) zi = (xi*yr - xr*yi ) / (yr2 + yi2) Parameters Input Output xReal double-precision Real part of x.
Analysis Library Chapter 3 CxDiv1D int status = CxDiv1D (double arrayXReal[], double arrayXImaginary[], double arrayYReal[], double arrayYImaginary)[], int numberofElements, double outputArrayReal[], double outputArrayImaginary[]); Purpose Divides two 1D complex arrays. The function obtains the ith element of the resulting complex array by using the following formulas.
Chapter 3 Analysis Library CxLinEv1D int status = CxLinEv1D (double arrayXReal[], double arrayXImaginary[], int numberofElements, double aReal, double aImaginary, double bReal, double bImaginary, double outputArrayReal[], double outputArrayImaginary[]); Purpose Performs a complex linear evaluation of a 1D complex array. The function obtains the ith element of the resulting complex array by using the following formulas.
Analysis Library Chapter 3 CxMul int status = CxMul (double xReal, double xImaginary, double yReal, double yImaginary, double *outputReal, double *outputImaginary); Purpose Multiplies two complex numbers. The function obtains the resulting complex number by using the following formulas. zr = xr*yr - xi*yi zi = xr*yi + xi*yr Parameters Input Output xReal double-precision Real part of x. xImaginary double-precision Imaginary part of x. yReal double-precision Real part of y.
Chapter 3 Analysis Library The function performs the operations in place; that is, the input and output complex arrays can be the same. Parameters Input Output arrayXReal double-precision array Real part of x. arrayXImaginary double-precision array Imaginary part of x. arrayYReal double-precision array Real part of y. arrayYImaginary double-precision array Imaginary part of y. numberofElements integer Number of elements. outputArrayReal double-precision array Real part of z.
Analysis Library Chapter 3 Parameters Input Output xReal double-precision Real part of x. xImaginary double-precision Imaginary part of x. outputReal double-precision Real part of y. outputImaginary double-precision Imaginary part of y. integer Refer to error codes in Table 3-2. Return Value status CxSub int status = CxSub (double xReal, double xImaginary, double yReal, double yImaginary, double *outputReal, double *outputImaginary); Purpose Subtracts two complex numbers.
Chapter 3 Analysis Library CxSub1D int status = CxSub1D (double arrayXReal[], double arrayXImaginary[], double arrayYReal[], double arrayYImaginary[], int numberofElements, double outputArrayReal[], double outputArrayImaginary[]); Purpose Subtracts two 1D complex arrays. The function obtains the ith element of the resulting complex array by using the following formulas.
Analysis Library Chapter 3 Determinant int status = Determinant (void *inputMatrix, int matrixSize, double *determinant); Purpose Finds the determinant of a matrixSize by matrixSize 2D input matrix. Parameters Input Output inputMatrix double-precision 2D Input matrix. array matrixSize integer Dimension size of input matrix. determinant double-precision Determinant. Note: The input matrix must be a matrixSize by matrixSize square matrix.
Chapter 3 Analysis Library Parameters Input Output arrayX double-precision array Input array. arrayY double-precision array Input array. numberofElements integer Number of elements to be divided. outputArray double-precision array Result array. integer Refer to error codes in Table 3-2. Return Value status Div2D int status = Div2D (void *arrayX, void *arrayY, int numberofRows, int numberofColumns, void *outputArray); Purpose Divides two 2D arrays.
Analysis Library Chapter 3 Return Value integer status Refer to error codes in Table 3-2. DotProduct int status = DotProduct (double vectorX[], double vectorY[], int numberofElements, double *dotProduct); Purpose Computes the dot product of the vectorX and vectorY input arrays. The function obtains the dot product by using the following formula: n −1 dotproduct = x • y = ∑ xi ∗ yi i=0 Parameters Input vectorX double-precision array Input vector. vectorY double-precision array Input vector.
Chapter 3 Analysis Library GetAnalysisErrorString char *message = GetAnalysisErrorString (int errorNum) Purpose Converts the error number returned by an Analysis Library function into a meaningful error message. Parameters Input errorNum integer Status returned by an Analysis function. string Explanation of error.
Analysis Library Chapter 3 Parameters Input inputArray double-precision array numberofElements integer Input array. Number of elements in Input Array. Output base double-precision Lower range. top double-precision Upper range. intervals integer Number of intervals. histogramArray integer array Histogram of input Array. axisArray double-precision array Histogram axis array. integer Refer to error codes in Table 3-2.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in n Table 3-2. LinEv1D int status = LinEv1D (double inputArray[], int numberofElements, double multiplier, double additiveConstant, double outputArray[]); Purpose Performs a linear evaluation of a 1D array. The function obtains the ith element of the output array by using the following formula. yi = a∗ xi + b The operation can be performed in place; that is, inputArray and outputArray can be the same array.
Analysis Library Chapter 3 LinEv2D int status = LinEv2D (void *inputArray, int numberofRows, int numberofColumns, double multiplier, double additiveConstant, void *outputArray); Purpose Performs a linear evaluation of a 2D array. The function obtains the (ith, jth) element of the output array by using the following formula. yi,j = a* xi,j + b The function performs the operation in place; that is, inputArray and outputArray can be the same array.
Chapter 3 Analysis Library MatrixMul int status = MatrixMul (void *matrixX, void *matrixY, int #ofRowsInX, int cols/rowsInX/Y, int #ofColumnsInY, void *outputMatrix); Purpose Multiplies two 2D input matrices. The function obtains the (ith, jth) element of the output matrix by using the following formula. k −1 zi , j = ∑ x i , p ∗ y p , j p= 0 Parameters Input Output matrixX double-precision 2D matrixX input matrix. array matrixY double-precision 2D matrixY input matrix.
Analysis Library Chapter 3 MaxMin1D int status = MaxMin1D (double inputArray[], int numberofElements, double *maximumValue, int *maximumIndex, double *minimumValue, int *minimumIndex); Purpose Finds the maximum and minimum values in the input array, as well as the respective indices of the first occurrence of the maximum and minimum values. Parameters Input inputArray double-precision array numberofElements integer Output Input array. Number of elements. maximumValue double-precision Maximum value.
Chapter 3 Analysis Library Parameters Input Output inputArray double-precision 2D array Input array. numberofRows integer Number of elements in first dimension of inputArray. numberofColumns integer Number of elements in second dimension of inputArray. maximumValue double-precision Maximum value. maximumRowIndex integer Index of maximumValue in inputArray array (first dimension). maximumColumnIndex integer Index of maximumValue in inputArray (second dimension).
Analysis Library Chapter 3 Parameters Input inputArray double-precision array numberofElements integer Output mean Input array. Number of elements in inputArray. double-precision Mean value. integer Refer to error codes in Table 3-2. Return Value status Mul1D int status = Mul1D (double arrayX[], double arrayY[], int numberofElements, double outputArray[]); Purpose Multiplies two 1D arrays. The function obtains the ith element of the output array by using the following formula.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in Table 3-2. Mul2D int status = Mul2D (void *arrayX, void *arrayY, int numberofRows, int numberofColumns, void *outputArray); Purpose Multiplies two 2D arrays. The function obtains the (ith, jth) element of the output array by using the following formula. z i , j = x i, j * yi , j The function performs the operation in place; that is, outputArray can be the same array as either arrayX or arrayY.
Analysis Library Chapter 3 Neg1D int status = Neg1D (double inputArray[], int numberofElements, double outputArray[]); Purpose Negates the elements of the input array. The function performs the operation in place; that is, inputArray and outputArray can be the same array. Parameters Input Output inputArray double-precision Input array. array numberofElements integer outputArray double-precision Negated values of the inputArray. array Number of elements.
Chapter 3 Analysis Library Sort int status = Sort (double inputArray[], int numberofElements, int direction, double outputArray[]); Purpose Sorts the input array in ascending or descending order. The function performs the operation in place; that is, inputArray and outputArray can be the same array. Parameters Input inputArray double-precision array numberofElements integer direction Input array. Number of elements to be sorted. integer 0: ascending. Non-zero: descending.
Analysis Library Chapter 3 Parameters Input inputArray double-precision array numberofElements integer Output Input array. Number of elements in inputArray. mean double-precision Mean value. standardDeviation double-precision Standard deviation. integer Refer to error codes in Table 3-2. Return Value status Sub1D int status = Sub1D (double arrayX[], double arrayY[], int numberofElements, double outputArray[]); Purpose Subtracts two 1D arrays.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in Table 3-2. Sub2D int status = Sub2D (void *arrayX, void *arrayY, int numberofRows, int numberofColumns, void *outputArray); Purpose Subtracts two 2D arrays. The function obtains the (ith, jth) element of the output array by using the formula: z i , j = x i , j − yi , j The function performs the operation in place; that is, outputArray can be in place of either arrayX or arrayY.
Analysis Library Chapter 3 Subset1D int status = Subset1D (double inputArray[], int numberofElements, int index, int length, double outputArray[]); Purpose Extracts a subset of the inputArray input array containing the number of elements specified by the length and starting at the index element. Parameters Input inputArray double-precision array numberofElements integer Output Input array. Number of elements in inputArray. index integer Initial index for the subset.
Chapter 3 Analysis Library Parameters Input Output xReal double-precision X coordinate. yImaginary double-precision X coordinate. magnitude double-precision Magnitude. phaseRadians double-precision Phase (in radians). integer Refer to error codes in Table 3-2.
Analysis Library Chapter 3 Parameters Input arrayXReal double-precision array X coordinate. arrayYImaginary double-precision array Y coordinate. numberofElements integer Output Number of elements. magnitude double-precision array Magnitude. phaseRadians double-precision array Phase (in radians). integer Refer to error codes in Table 3-2.
Chapter 3 Analysis Library Return Value integer status Refer to error codes in Table 3-2. ToRect1D int status = ToRect1D (double magnitude[], double phaseRadians[], int numberofElements, double outputArrayReal[], double outputArrayImaginary[]); Purpose Converts the set of polar coordinate points (magnitude, phaseRadians) to a set of rectangular coordinate points (outputArrayReal, outputArrayImaginary). The function obtains the ith element of the rectangular set by using the following formulas.
Analysis Library Chapter 3 Transpose int status = Transpose (void *inputMatrix, int numberofRows, int numberofColumns, void *outputMatrix); Purpose Finds the transpose of a 2D input matrix. The (ith, jth) element of the resulting matrix uses the formula: yi,j = xi,j Parameters Input inputMatrix double-precision 2D Input matrix. array numberofRows integer Size of first dimension. numberofColumns integer Output outputMatrix Size of second dimension. double-precision 2D Transpose matrix.
Chapter 3 Analysis Library Error Conditions If an error condition occurs during a call to any of the functions in the LabWindows/CVI Analysis Library, the status return value contains the error code. This code is a value that specifies the type of error that occurred. The currently defined error codes and their associated meanings are given in Table 3-2. Table 3-2. Analysis Library Error Codes Symbolic Name Code Error Message BaseGETopAnlysErr -20101 Base must be less than Top.
Chapter 4 GPIB/GPIB-488.2 Library This describes the NI-488 and NI-488.2 functions in the LabWindows/CVI GPIB Library, as well as the Device Manager functions in LabWindows/CVI. The GPIB Library Function Overview section contains general information about the GPIB Library functions and panels, the GPIB DLL, and guidelines and restrictions you should know when using the GPIB Library. Detailed descriptions of the NI-488 and NI-488.2 functions can be found in your NI-488.2 function reference manual.
GPIB/GPIB-488.2 Library Chapter 4 Table 4-1. The GPIB Functions Library Function Tree GPIB/GPIB-488.
Chapter 4 GPIB/GPIB-488.2 Library Table 4-1.
GPIB/GPIB-488.2 Library Chapter 4 Table 4-1.
Chapter 4 GPIB/GPIB-488.2 Library • The Bus Control function panels provide low-level control of the GPIB bus. • The Board Control function panels provide low-level control of the GPIB board. These functions are normally used when the GPIB board is not controller-in-charge. • The Callbacks function panels install callback functions that are invoked when certain GPIB events occur. The functions in this class are available only under Windows. Under UNIX, you can use the ibsgnl function.
GPIB/GPIB-488.2 Library Chapter 4 drivers are packaged with your GPIB interface board and are not included with LabWindows/CVI. LabWindows/CVI does not require any special procedures for installing and using the device driver. Follow the directions outlined in your board documentation. You can use a utility program called IBCONF, included with your GPIB software, to specify configuration parameters for devices on the GPIB.
Chapter 4 GPIB/GPIB-488.2 Library Note: When writing instrument modules, you must use the Device Manager functions (OpenDev and CloseDev) instead of ibfind or ibdev. You must also use the Device Manager functions in application programs that make calls to instrument modules. The Device Manager functions allow instrument modules to open devices without specific device names, thereby preventing device name conflicts.
GPIB/GPIB-488.2 Library Chapter 4 included in the wait mask. Aside from the difficulty caused by ESRQ in waiting for RQS, the error will have no detrimental effects on other GPIB operations. If you call the serial poll function ibrsp and have received one or more responses previously via the automatic serial poll feature, the ibrsp function returns the first queued response. Other responses are read in FIFO (first-in-first-out) fashion.
Chapter 4 GPIB/GPIB-488.2 Library • The last GPIB call was a board call. Autopolling is re-instated after a subsequent device call. • GPIB I/O is in progress. In particular, during asynchronous GPIB I/O, autopolling will not occur until the asynchronous I/O has completed. • The "stuck SRQ" condition exists. • Autopolling has been disabled by IBCONF or by ibconfig. Read and Write Termination The IEEE 488 specification defines two methods of identifying the last byte of device-dependent (data) messages.
GPIB/GPIB-488.2 Library Chapter 4 Global Variables for the GPIB Library The following global variables are used by the GPIB Library and the GPIB-488.2 Library: • Status Word (ibsta) • Error (ibcnt, ibcntl) These variables are updated after each NI-488 or NI-488.2 routine to reflect the status of the device or board just accessed. Refer to your NI-488.2 user manual for detailed information on the GPIB global variables.
Chapter 4 GPIB/GPIB-488.2 Library If you want to use GPIB under Windows 95 and you have an older board, it is recommended that you upgrade to one of the boards in this list. Compatibility Driver The compatibility driver is a 32-to-16-bit thunking DLL that you can use with the Windows 3.1 GPIB driver under Windows 95. All GPIB boards are supported by the compatibility driver. The compatibility driver has several limitations.
GPIB/GPIB-488.2 Library Chapter 4 Notification of SRQ and Other GPIB Events Synchronous Callbacks Under Windows 3.1, you can use ibInstallCallback to specify a function to be called when an SRQ is asserted on the GPIB or when an asynchronous I/O operation has completed. It is a board-level function only. The same functionality exists on Windows 95 when you are using the compatibility driver.
Chapter 4 GPIB/GPIB-488.2 Library GPIB Function Reference Most of the functions in the GPIB/GPIB-488.2 Library are described in the software reference manual that you received with your GPIB board. This section contains descriptions only for the Device Manager functions, the callback installation functions, and the functions for returning the thread-specific status variables. Note: ResetDevs is not available in LabWindows/CVI. This function was available in a previous LabWindows version.
GPIB/GPIB-488.2 Library Chapter 4 CloseInstrDevs int result = CloseInstrDevs (char *instrumentPrefix); Purpose Closes instrument devices. Parameter Input instrumentPrefix string Must be null-terminated. integer Result of the close instrument devices operation. Return Value result Return Codes 0 Success. Using This Function Closes all devices associated with the instrument module whose prefix is specified.
Chapter 4 GPIB/GPIB-488.2 Library The callback function is called when any of the GPIB events specified in the Event Mask parameter have occurred on the board or device, but only while you allow the system to process events. The system can process events when you call ProcessSystemEvents or GetUserEvent, or when you have called RunUserInterface and none of your callback functions are currently active.
GPIB/GPIB-488.2 Library Chapter 4 Return Value status integer (short integer on Windows 3.1) The same value as the ibsta status variable. Refer to your NI-488.2 or NI-488.2M user manual for a description of the values of ibsta status variable. eventMask The conditions upon which to invoke the callback function are specified as bits in the eventMask parameter. The bits corresponds to the bits of the ibsta status word. This value reflects a sum of one or more events.
Chapter 4 GPIB/GPIB-488.2 Library CallbackFunction The callback function must have the following form. void CallbackFunctionName (int boardOrDevice, int mask, void *callbackData); The mask and callbackData parameters are the same values that were passed to ibInstallCallback. If invoked because of an SRQI or RQS condition, the callback function should call the ibrsp function to read the status byte.
GPIB/GPIB-488.2 Library Chapter 4 Only one callback function can apply for each board or device. Each call to this function for the same board or device supersedes the previous call. To disable callbacks for a board or device, pass 0 for the eventMask parameter. Parameters Input boardOrDevice integer A board index, or a board or device descriptor returned by OpenDev, ibfind, or ibdev. eventMask integer Specifies the events upon which the callback function is called. Pass 0 to disable callbacks.
Chapter 4 GPIB/GPIB-488.2 Library SRQI, RQS, and Auto Serial Polling If you want to install a callback for the SRQI (board-level) event, Auto Serial Polling must be disabled. You can disable Auto Serial Polling with the following function call: ibconfig (boardIndex, IbcAUTOPOLL, 0); If you want to install a callback for the RQS (device-level) event, Auto Serial Polling must be enabled for the board.
GPIB/GPIB-488.2 Library Chapter 4 If invoked because an asynchronous I/O operation (started by ibrda, ibwrta, or ibcmda) completed, the callback function should contain the following call: ibwait (boardOrDevice, TIMO | CMPL); The ibcnt and ibcntl status variables are not updated until this call to ibwait is made. Restrictions on Operations in Asynchronous Callbacks Callbacks installed with ibnotify can be called at any time while your program is running.
Chapter 4 GPIB/GPIB-488.2 Library OpenDev int bd = OpenDev (char *deviceName, char *instrumentPrefix); Purpose Opens a GPIB device. Parameters Input deviceName string Must be null-terminated. instrumentPrefix string Must be null-terminated. integer Result of the open device operation. Return Value bd Return Codes -1 Device table is full, or no more devices available. Parameter Discussion deviceName is a string specifying a device name that appears in the IBCONF device table.
GPIB/GPIB-488.2 Library Chapter 4 ThreadIbcnt int threadSpecificCount = ThreadIbcnt (void); Note: This function is available only under Windows 95 and NT. This function returns the value of the thread-specific ibcnt variable for the current thread. The global variables ibsta, iberr, ibcnt, and ibcntl are maintained on a process-specific (rather than thread-specific) basis. If you are calling GPIB functions in more than one thread, the values in these global variables may not always be reliable.
Chapter 4 GPIB/GPIB-488.2 Library If you are not using multiple threads, the value returned by this function is identical to the value of the ibcntl global variable. Parameters none Return Value threadSpecificCount long integer The number of bytes actually transferred by the most recent GPIB read, write, or command operation for the current thread of execution. If an error occurred loading the GPIB DLL, this is the error code returned by the MS Windows LoadLibrary function.
GPIB/GPIB-488.2 Library Chapter 4 Return Codes Defined Constant Value Description EDVR 0 Operating system error. The system-specific error code is returned by ThreadIbcntl. ECIC 1 Function requires GPIB-PC to be CIC. ENOL 2 No listener on write function. EADR 3 GPIB-PC addressed incorrectly. EARG 4 Invalid function call argument. ESAC 5 GPIB-PC not System Controller as required. EABO 6 I/O operation aborted. ENEB 7 Non-existent GPIB-PC board. EDMA 8 Virtual DMA device error.
Chapter 4 GPIB/GPIB-488.2 Library See Also ThreadIbsta, ThreadIbcnt, ThreadIbcntl. ThreadIbsta int threadSpecificStatus = ThreadIbsta (void); Note: This function is available only under Windows 95 and NT. This function returns the value of the thread-specific ibsta variable for the current thread. The global variables ibsta, iberr, ibcnt, and ibcntl are maintained on a process-specific (rather than thread-specific) basis.
GPIB/GPIB-488.2 Library Chapter 4 Return Codes The return value is a sum of the following bits. Defined Constant Hex Value Condition ERR 8000 GPIB error. END 2000 END or EOS detected. SRQI 1000 SRQ is on. RQS 800 Device requesting service. CMPL 100 I/O completed. LOK 80 GPIB-PC in Lockout State. REM 40 GPIB-PC in Remote State. CIC 20 GPIB-PC is Controller-In-Charge. ATN 10 Attention is asserted. TACS 8 GPIB-PC is Talker. LACS 4 GPIB-PC is Listener.
Chapter 5 RS-232 Library This chapter describes the functions in the LabWindows/CVI RS-232 Library. The RS-232 Library Function Overview section contains general information about the RS-232 Library functions and panels. The RS-232 Library Function Reference section contains an alphabetical list of function descriptions. In order to use the RS-232 Library on UNIX, your UNIX kernel must support asynchronous I/O functions (for example, aioread and aiowrite).
RS-232 Library Chapter 5 Table 5-1.
Chapter 5 RS-232 Library Using RS-485 You can use all of the functions in the RS-232 Library with the National Instruments RS-485 AT-Serial board. The ComSetEscape function allows you to control the transceiver mode of the board. Reporting RS-232 Errors The functions in the RS-232 Library return negative values when an error occurs. In addition, the global variable rs232err is updated after each function call to the RS-232 Library. If the function executes properly, it sets rs232err to zero.
RS-232 Library Chapter 5 All functions, except the Open and Close functions, require the com port to be opened with OpenCom or OpenComConfig. If the program writes data to the output queue and then immediately closes the com port, the data in the queue may be lost if it has not had time to be sent over the port. To guarantee that all bytes were written before closing the port, monitor the length of the output queue with the GetOutQLen function.
Chapter 5 RS-232 Library All serial devices are either of the type Data Communication Equipment (DCE) or Data Transmission Equipment (DTE). The PC is of type DTE. The difference between the two devices is in the meaning assigned to the pins. A DCE device reverses the meaning of pins 2 and 3, 4 and 5, and 6 and 20. In the simplest scenario, a DTE device is attached to a DCE device, such as a modem. Therefore, the cable required for a PC (or DTE) to talk to a device that is a DCE is shown in Table 5-3.
RS-232 Library Chapter 5 application. Refer to the Hardware Handshaking section later in this chapter for more information about using the lines 4, 5, 6, and 20. Another area that requires special attention is the gender of the connectors of your serial cable. The serial cable plugs into sockets in the PC and the serial device just as a lamp cord plugs into a wall socket. Both the connector and the socket can be male, with pins (like a lamp plug), or female, with holes (like an outlet).
Chapter 5 RS-232 Library Hardware Handshaking The SetCTSMode function enables hardware handshaking. For hardware handshaking to work, two conditions must exist. First, the serial devices must follow the same or similar hardware handshake protocols (they must use the same lines for the handshake and assign the same meanings to those lines). Second, the serial cable connecting the two devices must include the lines required to support the protocol.
RS-232 Library • Chapter 5 – If the input queue of the port is nearly full, the library lowers RTS and DTR. – If the input queue of the port is nearly empty, the library raises RTS and DTR. – If the port is closed, the library lowers RTS and DTR. When the PC is the sender: – The RS-232 library must detect that its CTS line is high before sending data out the port. Note: The only difference between LWRS_HWHANDSHAKE_CTS_RTS and LWRS_HWHANDSHAKE_CTS_RTS_DTR is the behavior of the DTR line.
Chapter 5 RS-232 Library Parameter Discussion The function does nothing if the port numbers are invalid (port is not open or parameter value is not in the range 1 through 32). ComBreak int result = ComBreak (int COMPort, int breakTimeMsec); Purpose Generates a break signal. Parameters Input COMPort integer Range 1 through 32. breakTimeMsec integer Range 1 through 255, or 0 to select 250. integer Refer to error codes in Table 5-6.
RS-232 Library Chapter 5 Parameters Input COMPort integer Range 1 through 32. fileHandle integer File handle returned by OpenFile. count integer If 0, this value is ignored. terminationByte integer If -1, this value is ignored. integer Number of bytes written to the output queue. Return Value nbytes <0 Error. Refer to error codes in Table 5-6. Parameter Discussion Reads count bytes from the file unless it encounters terminationByte, reaches EOF, or encounters an error.
Chapter 5 RS-232 Library ComRd int nbytes = ComRd (int COMPort, char buffer[], int count); Purpose Reads count bytes from input queue of the specified port and stores them in buffer. Returns either on time-out or when count bytes have been read. Returns an integer value indicating the number of bytes read from queue. Parameters Input Output COMPort integer Range 1 through 16. count integer 0 value takes no bytes from queue. buffer string The buffer in which to store the data.
RS-232 Library Chapter 5 ComRdByte int byte = ComRdByte (int COMPort); Purpose Reads a byte from the input queue of the specified port. Returns an integer whose low-order byte contains the byte read. Returns either on time-out, when the byte is read, or when an error occurs. If an error or a time-out occurs, ComRdByte returns a negative error code. See Table 5-6. This is the only case in which the high-order byte of the return value is non-zero. Parameter Input COMPort integer Range 1 through 32.
Chapter 5 RS-232 Library Parameters Input Output COMPort integer Range 1 through 32. count integer If 0, no bytes are removed from queue. terminationByte integer Low byte contains the numeric equivalent of the terminating character. buffer string The buffer in which to store the data. integer Number of bytes read from the input queue. Return Value nbytes Using This Function This function times out if the input queue remains empty within the specified time-out period.
RS-232 Library Chapter 5 ComSetEscape int result = ComSetEscape (int COMPort, int escapeCode); Purpose Directs the specified com port to carry out an extended function such as clearing or setting the RTS signal line or setting the transceiver mode for RS-485. The extended functions are defined by the serial device driver. Not all device drives support all escape codes. Unknown System Error (-1) is returned when the device driver does not support a particular escape code.
Chapter 5 RS-232 Library The following values may be used only with the RS-485 serial driver developed by National Instruments: WIRE_4—Sets the transceiver to Four Wire Mode. WIRE_2_ECHO—Sets the transceiver to Two Wire DTR controlled with echo mode. WIRE_2_CTRL—Sets the transceiver to Two Wire DTR controlled without echo. WIRE_2_AUTO—Sets the transceiver to Two Wire auto TXRDY controlled mode.
RS-232 Library Chapter 5 for ComRdTerm. If both count and terminationByte are disabled, the function terminates on error (which can include a time-out). Using This Function The function returns an error if the output queue remains full for the duration of the time-out period, the file handle is bad, a read error occurs, the port is not open, or the COMPort is invalid. ComWrt int nbytes = ComWrt (int COMPort, char buffer[], int count); Purpose Writes count bytes to the output queue of the specified port.
Chapter 5 RS-232 Library the port, call GetOutQLen. GetOutQLen returns the number of bytes remaining in the output queue. The function returns an error if the port is not open or parameter values are invalid. Example /* /* if /* Place the string "Hello, world!" in the output queue of */ COM2 and check if operation was successful.
RS-232 Library Chapter 5 Parameter Discussion This function times out if the output queue has not been updated in the specified time-out period. This can occur if the output queue is full and no further data can be sent because XON/XOFF is enabled and the device has sent an XOFF character without sending the follow-on XON character. It can also occur if Hardware Handshaking is enabled and the Clear To Send (CTS) line is not asserted.
Chapter 5 RS-232 Library FlushOutQ int status = FlushOutQ (int COMPort); Purpose Removes all characters from the output queue of the specified port. Parameter Input COMPort integer Range 1 through 32. integer Refer to Error Codes in Table 5-6. Return Value status Using This Function The function returns an error if the port is not open or if COMPort is invalid. GetComStat int status = GetComStat (int COMPort); Purpose Returns information about the status of the specified COM port.
RS-232 Library Chapter 5 Table 5-5. Bit Definitions for the GetComStat Function Hex Value Mnemonic Description 0001 INPUT LOST Input queue filled and input characters lost (characters were not removed fast enough). 0002 ASYNCH ERROR Problem determining number of characters in input queue. This is an internal error and normally should not occur. 0010 PARITY Parity error detected. 0020 OVERRUN Overrun error detected; a character was received before the receiver data register was emptied.
Chapter 5 RS-232 Library Parameter Input COMPort integer Range 1 through 32. integer Number of characters in the input queue. Return Value len Parameter Discussion The function returns an error if the port is not open or if COMPort is invalid. GetOutQLen int len = GetOutQLen (int COMPort); Purpose Returns the number of characters in the output queue of the specified port. Parameter Input COMPort integer Range 1 through 32. integer Number of characters in the output queue.
RS-232 Library Chapter 5 GetRS232ErrorString char *message = GetRS232ErrorString (int errorNum) Purpose Converts the error number returned by an RS-232 Library function into a meaningful error message. Parameters Input errorNum integer Error Code returned by RS-232 function. string Explanation of error.
Chapter 5 RS-232 Library Note: The callback function may receive more than one event at a time. When using this function at higher baud rates, some LWRS_RXCHAR events may be missed. It is recommended to use LWRS_RECEIVE or LWRS_RXFLAG instead. Note: Once the LWRS_RECEIVE event occurs, it is not triggered again until the input queue falls below, and then rises back above, notifyCount bytes.
RS-232 Library Chapter 5 Return Value integer status Refer to error codes in Table 5-6. Parameter Discussion The callback function must have the following form. void CallbackFunctionName (int COMPort, int eventMask, void *callbackData); The eventMask and callbackData parameters are the same values that were passed to InstallComCallback. The events are specified using bits in the eventMask parameter. You can specify multiple event bits in the eventMask parameter.
Chapter 5 RS-232 Library The following table further describes the events. Event Constant Name Description LWRS_RXCHAR Set when any character is received and placed in the receiving queue. LWRS_RXFLAG Set when the event character is received and placed in the receiving queue. The event character is specified in the eventCharacter parameter of this function. LWRS_TXEMPTY Set when the last character in the transmission queue is sent. LWRS_CTS Set when the CTS (clear-to-send) line changes state.
RS-232 Library Chapter 5 Return Value integer result Refer to error codes in Table 5-6. Parameter Discussion deviceName is the name of the com port in the ASCII string. For example, COM1 for com port 1 on Microsoft Windows using COMM.DRV, and /dev/ttya for com port 1 on UNIX using the Zilog 8530 SCC serial comm driver. If you pass a NULL pointer or an empty string for deviceName, the library uses the following device names depending on the COM port number you have specified.
Chapter 5 RS-232 Library Parameters Input COMPort integer Range 1 through 32. deviceName string Name of the COM port. baudRate long Either 110, 150, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 128000, or 256000. SPARCstations do not support 14400, 28800, 56000, 57600, 115200, 128000, and 256000. PCs do not support 150. Some PC serial drivers do not support 115200, 128000, and 256000. 0—no parity. 1—odd parity. 2—even parity. 3—mark parity. 4—space parity.
RS-232 Library Chapter 5 Under UNIX, the inputQueueSize and outputQueueSize parameters are ignored. The serial driver determines the queue size. Under Windows, if you specify 0 for inputQueueSize or outputQueueSize, 512 is used. If you specify a value between 0 and 30, 30 is used. On Windows 95 and NT, there is no maximum limitation on the queue size. On Windows 3.1, the maximum queue size is 65535.
Chapter 5 RS-232 Library SetComTime int result = SetComTime (int COMPort, double timeoutSeconds); Purpose Sets time-out limit for input/output operations. Parameters Input COMPort integer Range 1 through 32. timeoutSeconds double-precision Time-out period for all read/write functions. integer Refer to error codes in Table 5-6. Return Value result Using This Function This function sets the time-out parameters for all read and write operations. The default value of timeoutSeconds is 5.
RS-232 Library Chapter 5 SetCTSMode int result = SetCTSMode (int COMPort, int mode); Purpose Enables or disables hardware handshaking as described in the Hardware Handshaking section of the RS-232 Library Function Overview. Parameters Input COMPort integer Range 1 through 32. mode integer 0 to disable hardware handshaking, non-zero to enable hardware handshaking. See discussion below. integer Refer to error codes in Table 5-6.
Chapter 5 RS-232 Library SetXMode int result = SetXMode (int COMPort, int mode); Purpose Enables or disables software handshaking by enabling or disabling XON/XOFF sensitivity on transmission and reception of data. Parameters Input COMPort integer Range 1 through 16. mode integer 0 to disable, non-zero to enable. integer Refer to error codes in Table 5-6. Return Value result Using This Function By default, XON/XOFF sensitivity is disabled.
RS-232 Library Chapter 5 Parameters Input COMPort startDelay integer double-precision maximum#ofRetries waitPeriod integer double-precision Range 1 through 32. 0.0 selects the default value 10.0 seconds. 0 selects the default value 10. 0.0 selects the default value 10.0 seconds. >5.0 is recommended. packetSize integer 0 selects the default value 128. integer Result of the XModem configuration operation. Return Value result (Less than zero) Error code; See Table 5-6. (Zero) Success.
Chapter 5 RS-232 Library for an acknowledgment before it re-sends the current packet. When LabWindows/CVI plays the role of receiver, it waits for up to waitPeriod seconds for the next packet after it sends out an acknowledgment for the current packet. If it does not receive the next packet within delayPeriod seconds, it re-sends the acknowledgment, and waits again, up to maximum#ofRetries times. The default value of waitPeriod is 10.0. packetSize sets the packet size in bytes.
RS-232 Library Chapter 5 XModemReceive tries ((maximum#ofTries + 1) / 2) times to negotiate a CRC error check transfer. If there is no response, it tries to negotiate a check sum transfer up to ((maximum#ofTries -1) / 2) times. The file is opened in binary mode, and carriage returns and linefeeds are not treated as ASCII characters. They are written to the RS-232 line, untouched. If the size of the file being sent is not an even multiple of the packet size, the file received is padded with NUL (0) bytes.
Chapter 5 RS-232 Library Return Value result integer Result of the XModem send operation. <0 Failure. 0 Success. Using This Function The file is opened in binary mode. Carriage returns and linefeeds are not treated as ASCII characters. They are sent to the receiver untouched. This function uses the XModem file transfer protocol. The receiver must also follow this protocol for this function to work properly.
RS-232 Library Chapter 5 Error Conditions If an error condition occurs during a call to any of the functions in the LabWindows/CVI RS-232 Library, the function returns an error code and the global variable rs232err contains that error code. This code is a non-zero value that specifies the type of error that occurred. The currently defined error codes and their meanings are given in Table 5-6. Table 5-6. RS-232 Library Error Codes Code Error Message -1 Unknown system error. -2 Invalid port number.
Chapter 5 RS-232 Library Table 5-6. RS-232 Library Error Codes (Continued) -258 Packet not sent within retry limit. -259 Packet not received within retry limit. -260 End of transmission character encountered when start of data character expected. -261 Packet number could not be read. -262 Packet number inconsistency. -263 Packet data could not be read. -264 Checksum could not be read. -265 Checksum received did not match computed checksum. -269 Packet size exceeds input queue size.
Chapter 6 DDE Library This chapter describes the functions in the LabWindows/CVI DDE (Dynamic Data Exchange) Library. The DDE Library Function Overview section contains general information about the DDE Library functions and panels. The DDE Library Function Reference section contains an alphabetical list of function descriptions. This library is available for LabWindows/CVI for Microsoft Windows only.
DDE Library Chapter 6 DDE Clients and Servers Interprocess communication with DDE involves a client and a server in each DDE conversation. A DDE server can execute commands sent from another application, and send and receive information to and from a client application under Windows. A DDE client can send commands to a server application to be executed, and request data from a server application. With the LabWindows/CVI DDE Library, you can write programs to act as a DDE client or server.
Chapter 6 DDE Library DDE callback functions used in a program that acts as a DDE server can be triggered in a number of ways from client applications. Whenever a client application attempts to connect to your server program or requests information from your program, the callback function in your program is executed to process the request.
DDE Library Chapter 6 Table 6-2. DDE Transaction Types (xType) xType DDE_CONNECT Server Client When ? Y N When a new client requests a connection. DDE_DISCONNECT Y Y When conversation partner quits. DDE_DATAREADY Y Y When conversation partner sends data. DDE_REQUESTDATA Y N When client requests data. DDE_ADVISELOOP Y N When client requests advisory loop. DDE_ADVISESTOP Y N When client terminates request for advisory loop.
Chapter 6 DDE Library A DDE Library Example Using Microsoft Excel and LabWindows/CVI LabWindows/CVI includes a sample program called ddedemo.prj that uses DDE to send data to Microsoft Excel. The example program can be found in the samples\ddetcp directory. The following discussion outlines the process required to open an Excel worksheet file, send data over DDE, and setup a DDE link with one of the cells in the worksheet from a LabWindows/CVI program. Start Excel and load the worksheet file called LWCVI.
DDE Library Chapter 6 When the DDE_DATAREADY transaction is received in the callback function, a numeric display is updated by passing the data pointer value to a numeric control on the UIR file. When the DDE event is DDE_DISCONNECT, the DisconnectFromDDEServer function ends the DDE conversation and program execution is halted.
Chapter 6 DDE Library Parameter Discussion dataFormat must be a valid data format recognized by Microsoft Windows. The following are the valid data formats supported by Microsoft Windows: CF_TEXT CF_PALETTE CF_BITMAP CF_PENDATA CF_METAFILEPICT CF_RIFF CF_SYLK CF_WAVE CF_DIF CF_OWNERDISPLAY CF_TIFF CF_DSPTEXT CF_OEMTEXT CF_DSPBITMAP CF_DIB CF_DSPMETAFILEPICT The Microsoft Windows 3.
DDE Library Chapter 6 If successful, this function returns the number of bytes sent. Otherwise, this function returns a negative error code. See the help for the status control for the error code values. Note: Your program should not call AdviseDDEDataReady in a tight loop because the iterations will compete with user interface events for the CPU time. You should use this function sparingly, and only when the value of the hot- or warm-linked data object changes.
Chapter 6 DDE Library Parameter Discussion serverName, topicName, and itemName must be strings of length from 1 to 255. They are used without regard to case. Using this Function This function allows your program, acting as a DDE server, to send data to all clients that have set up hot or warm links on the specified topic and item. When a hot or warm link is set up, your server callback function receives a DDE_ADVISELOOP transaction type (xType) for a particular data object (identified by itemName).
DDE Library Chapter 6 Purpose Called by client to send a command to be executed by a DDE server application. Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. commandString string Command to be executed by the server application. timeout unsigned integer Timeout in ms. integer Refer to error codes in Table 6-3. Return Value status Parameter Discussion The commandString represents a valid command sequence for the server application to execute.
Chapter 6 Output DDE Library dataFormat unsigned integer Valid data format; for example, CF_TEXT. dataSize unsigned integer Number of bytes to read. Limited to 64 KB under Windows 3.1 and Windows 95. timeout unsigned integer Timeout in ms. dataBuffer void pointer Buffer in which to receive data. integer Refer to error codes in Table 6-3. Return Value status Parameter Discussion dataFormat must be a valid data format recognized by Microsoft Windows.
DDE Library Chapter 6 Purpose Called by client to write data to a DDE server application. Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. itemName string Uniquely identifies the output item; for example, system. dataFormat unsigned integer Valid data format; for example, CF_TEXT. dataPointer void pointer Buffer holding data. dataSize unsigned integer Number of bytes to write. Limited to 64 KB under Windows 3.1 and Windows 95.
Chapter 6 DDE Library See Also ConnectToDDEServer, ClientDDERead ConnectToDDEServer int status = ConnectToDDEServer (unsigned int *conversationHandle, char serverName[], char topicName[], ddeFuncPtr clientCallbackFunction, void *callbackData); Purpose Establishes a connection (conversation) between your program and a named server on a given topic name. Parameters Input serverName string Name of the server application. topicName string Specifies the type of conversation with the server.
DDE Library Chapter 6 clientCallbackFunction defines a callback function through which all messages from the server will be routed. The callback function must be of the following form: int (*ddeFuncPtr) (int handle, char *topicName, char *itemName, int xType, int dataFmt, int dataSize, void*dataPtr, void *callbackData); The xType (transaction type) parameter specifies the type of message received from the server.
Chapter 6 DDE Library DisconnectFromDDEServer int status = DisconnectFromDDEServer (unsigned int conversationHandle); Purpose Disconnects your client program from a server application. Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. integer Refer to error codes in Table 6-3. Return Value status Note: This function ends a conversation between a client and server corresponding to the conversationHandle that was passed.
DDE Library Chapter 6 Return Value string message Explanation of error. RegisterDDEServer int status = RegisterDDEServer (char serverName[], ddeFuncPtr serverCallbackFunction, void *callbackData); Purpose Registers your program as a valid DDE server, allowing other Windows applications to connect to it for interprocess communication. Parameters Input serverName string Name of the server application.
Chapter 6 DDE Library DDE_DISCONNECT DDE_DATAREADY DDE_REQUEST DDE_ADVISELOOP DDE_ADVISESTOP DDE_EXECUTE DDE_CONNECT—This transaction type is received when a client is requesting a connection. The topicName parameter specifies the connection topic. The set of valid topic names is defined by the server and can be used in different ways. For example, Excel uses the topic name to specify the file on which the client requests to operate.
DDE Library Chapter 6 This function registers your program as a DDE server with the specified name. Clients attempting to connect to your program must use the specified name. Thereafter, all requests by the client will be routed through the specified serverCallbackFunction. You can register your program as a DDE server multiple times as long as you specify different server names. Note: The callback function should return TRUE if the request is successful else return FALSE.
Chapter 6 DDE Library ServerDDEWrite int status = ServerDDEWrite (unsigned int conversationHandle, char itemName[], unsigned int dataFormat, void *dataPointer, unsigned int dataSize, unsigned int timeout); Purpose Writes data to a DDE client application when it requests data. Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. itemName string Uniquely identifies the output item; for example, system.
DDE Library Chapter 6 Refer to Microsoft programmers' documention for Windows 3.x for an in-depth discussion of DDE programming and meaning of each data format type. Using This Function This function allows your program, acting as a DDE server, to send data to a client. You should call this function only when your serverCallbackFunction receives transaction type (xType) of DDE_REQUESTDATA. If you call the function at any other time, the data is stored until the client requests data.
Chapter 6 DDE Library Return Value integer status Refer to error codes in Table 6-3. Parameter Discussion The itemName represents the information in the server application where the DDE link is established. For example, the item name could represent an Excel range of cells by using the range description R1C1:R10C10. Note: To the client, LabWindows/CVI does not distinguish between a hot link and a warm link.
DDE Library Chapter 6 Parameter Discussion The itemName represents the information in the server application where the DDE link is established. For example, the item name could represent an Excel range of cells by using the range description R1C1:R10C10. Note: To the client, LabWindows/CVI does not distinguish between a hot link and a warm link.
Chapter 6 DDE Library UnregisterDDEServer int status = UnregisterDDEServer (char serverName[]); Purpose Unregisters your application program as a DDE server. Parameters Input serverName string Name of the server application. integer Refer to error codes in Table 6-3. Return Value status See Also RegisterDDEServer Error Conditions If an error condition occurs during a call to any of the functions in the LabWindows/CVI DDE Library, the status return value contains the error code.
DDE Library Chapter 6 Table 6-3.
Chapter 7 TCP Library This chapter describes the functions in the LabWindows/CVI TCP (Transmission Control Protocol) Library. The TCP Library Function Overview section contains general information about the TCP Library functions and panels. The TCP Library Function Reference section contains an alphabetical list of function descriptions. In order to use this library in Microsoft Windows, a version of WINSOCK.DLL has to be present. The DLL comes with the program that drives the network card.
TCP Library Chapter 7 TCP Clients and Servers Network communication using the TCP library involves a client and a server in each connection. A TCP server can send and receive information to and from a client application through a network. A TCP client can send and request data to and from a server application. Once registered, a server waits for clients to request connection to it. A client, however, can only request connection to a pre-existing server.
Chapter 7 TCP Library program is invoked to process the request. The parameter prototypes for the TCP callback functions in LabWindows/CVI are defined below: int CallbackFunction (int handle, int xType, int errCode, void *callbackData); where handle represents the conversation handle xType represents the transaction type (see table below) errCode for TCP_DISCONNECT, is negative if the connection is being terminated due to an error callbackData is a user-defined data value.
TCP Library Chapter 7 Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. dataBuffer void pointer Buffer in which to receive data. dataSize unsigned integer Maximum number of bytes to read. timeout unsigned integer Timeout in ms. integer Returns the number of bytes read, or a negative error code if an error occurs; Refer to error codes in Table 7-3.
Chapter 7 TCP Library Return Value integer status Returns the number of bytes written, or a negative error code if an error occurs; Refer to error codes in Table 7-3. See Also ConnectToTCPServer, ClientTCPRead ConnectToTCPServer int status = ConnectToTCPServer (unsigned int *conversationHandle, unsigned int portNumber, char serverHostName[], tcpFuncPtr clientCallbackFunction, void *callbackData, unsigned int timeout); Purpose Establishes a conversation between your program and a pre-existing server.
TCP Library Chapter 7 Return Value status integer Refer to error codes in Table 7-3. Parameter Discussion clientCallbackFunction is the name of the function called to process messages to your program as a TCP client. The callback function must be of the following form: int (*tcpFuncPtr) (int handle, int xType, int errCode, void *callbackData); The xType (transaction type) parameter specifies the type of message received from the server.
Chapter 7 TCP Library See Also RegisterTCPServer, DisconnectFromTCPServer DisconnectFromTCPServer int status = DisconnectFromTCPServer (unsigned int conversationHandle); Purpose Disconnects your client program from a server application. Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. Return Value integer status Refer to error codes in Table 7-3. Note: This function terminates a connection identified by the conversation handle passed.
TCP Library Chapter 7 See Also RegisterTCPServer GetTCPErrorString char *message = GetTCPErrorString (int errorNum) Purpose Converts the error number returned by a TCP Library function into a meaningful error message. Parameters Input errorNum integer Status returned by a TCP function. string Explanation of error.
Chapter 7 TCP Library Return Value status integer Refer to error codes in Table 7-3. Parameter Discussion serverCallbackFunction is the name of the function to be called to process client requests. The callback function must be of the following form: int (*tcpFuncPtr) (int handle, int xType, int errCode, void *callbackData) The xType parameter specifies the type of message received from the server. The server callback function can receive the following transaction types.
TCP Library Chapter 7 It is up to you to define the meaning of the callback data. The following are examples of how the callback data can be used: • You can register your program as a TCP server multiple times under different port numbers. You could use the same callback function for all of the server instances by using the callback data to differentiate between them. • You can use the callback data to point to a data object that you need to access in the callback function.
Chapter 7 TCP Library ServerTCPWrite int status = ServerTCPWrite (unsigned int conversationHandle, void *dataPointer, unsigned int dataSize, unsigned int timeout); Purpose Writes data to a TCP client application. Parameters Input conversationHandle unsigned integer Uniquely identifies the conversation. dataPointer void pointer Buffer holding data. dataSize unsigned integer Number of bytes to write. timeout unsigned integer Timeout in ms.
TCP Library Chapter 7 Return Value integer status Refer to error codes in Table 7-3. See Also RegisterTCPServer Error Conditions If an error condition occurs during a call to any of the functions in the LabWindows/CVI TCP Library, the status return value contains the error code. This code is a non-zero value that specifies the type of error that occurred. Error code return values are negative numbers. The currently defined error codes and their associated meanings are shown in Table 7-3. Table 7-3.
Chapter 8 Utility Library This chapter describes the functions in the LabWindows/CVI Utility Library. The Utility Library contains functions that do not fit into any of the other LabWindows/CVI libraries. The Utility Library Function Panels section contains general information about the Utility Library functions and panels. The Utility Library Function Reference section contains an alphabetical list of function descriptions.
Utility Library Chapter 8 Table 8-1.
Chapter 8 Utility Library Table 8-1.
Utility Library Chapter 8 Table 8-1.
Chapter 8 Utility Library • Standard Input/Output Window functions control various attributes of the Standard Input/Output Window. • Run-Time Error Reporting functions enable and disable the feature which breaks execution when a LabWindows/CVI library function returns an error code. • Interrupts functions disable and enable the occurrence of interrupts. • Physical Memory Access functions read and write data from and to physical memory addresses. (Supported only under Microsoft Windows).
Utility Library Chapter 8 Breakpoint void Breakpoint (void); Purpose During execution of a program, a call to Breakpoint suspends program operation. While the program is suspended, you can inspect or modify variables, and use many other features of the LabWindows/CVI interactive program. Calling Breakpoint with the debugging level set to None, or from a compiled module, has no effect.
Chapter 8 Utility Library Cls void Cls (void); Purpose In the LabWindows/CVI environment, this function clears the Standard I/O window. Parameters None Return Value None CopyFile int result = CopyFile (char sourceFileName[], char targetFileName[]); Purpose Copies the contents of an existing file to another file. Parameters Input sourceFileName string File to copy. targetFileName string Copy of original file. integer Result of copy operation. Return Value result Return Codes 0 Success.
Utility Library Chapter 8 Parameter Discussion sourceFileName and targetFileName may contain wildcard characters ‘?’ and ‘*’. If sourceFileName has wildcards, all matching files are copied. If targetFileName has wildcards, it will be matched to sourceFileName. If the target file is a directory, the existing file (or group of files) will be copied into the directory.
Chapter 8 Utility Library Return Value loaded integer Indicates whether the LabWindows/CVI low-level support driver was loaded at startup. Return Codes 1 Low-level support driver was loaded at startup. 0 Low-level support driver was not loaded at startup. DateStr char *s = DateStr (void); Purpose Returns a 10-character string in the form MM-DD-YYYY, where MM is the month, DD is the day, and YYYY is the year. Parameters None Return Value 10-character string s The date in MM-DD-YYYY format.
Utility Library Chapter 8 Parameter Input numberofSeconds double-precision Number of seconds to wait. Return Value None DeleteDir int result = DeleteDir (char directoryName[]); Purpose Deletes an existing directory. Parameters Input directoryName String. Return Value integer result Result of operation. Return Codes 0 Success. -1 Directory not found. -3 General I/O error occurred. -4 Insufficient memory to complete operation. -6 Access denied, or directory not empty.
Chapter 8 Utility Library Parameter Input fileName string File to delete. integer Result of delete operation. Return Value result Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred. -4 Insufficient memory to complete operation. -5 Invalid path (for example, c:filename in Windows). -6 Access denied. -7 Specified path is a directory, not a file.
Utility Library Chapter 8 You can use this function in conjunction with EnableBreakOnLibraryErrors to temporarily suppress the Break on Library Errors feature around a segment of code. It does not affect the state of the Break on Library Errors check box in the Run Options dialog box of the Options menu in the Project window. Note: This function has been superseded by SetBreakOnLibraryErrors. DisableInterrupts void DisableInterrupts (void); Purpose Under Windows 3.
Chapter 8 Utility Library • The , , or key combination under Windows 3.1 or Windows 95. • The Switch To item in the system menu under Windows 3.1. This function affects the behavior of these keys only while LabWindows/CVI or a LabWindows/CVI Standalone Executable is the active application under Microsoft Windows. This function has no effect in Windows NT. See the Alternatives in Windows NT section for instructions on how to achieve the desired effect.
Utility Library Chapter 8 your standalone application to be brought up in place of the Program Manager when Windows boots. You can do this by changing the following line in your system.ini [boot] section. shell = progman.exe to shell = Alternatives in Windows 95 Under Windows 95, you can arrange for your standalone application to appear in place of the desktop when Windows boots. You can do this by changing the following line in your system.ini [boot] section.
Chapter 8 Utility Library • Do not use the Standard I/O Window in your final application. • If you use any of the built-in pop-ups in the User Interface Library, make the following calls. SetSystemPopupsAttribute (ATTR_MOVABLE, 0); SetSystemPopupsAttribute (ATTR_SYSTEM_MENU_VISIBLE, 0); An alternative approach is available on Windows 95 and NT.
Utility Library Chapter 8 Note: For you to be able to use this function under Windows 95, the LabWindows/CVI lowlevel support driver must be loaded. Note: Under Windows NT, the EnableInterrupts and DisableInterrupts functions have no effect. Interrupts are always enabled while your program is running at the user (as opposed to the kernel) level.
Chapter 8 Utility Library Return Value integer Result of operation. status Return Codes -1 Handle is invalid. 0 Executable is still running. 1 Executable has been terminated. Note: If you launch another LabWindows/CVI executable under Windows 3.x, the launched executable process will terminate itself after launching the new copy of the CVI Run-time Engine.
Utility Library Chapter 8 GetBreakOnProtectionErrors int state = GetBreakOnProtectionErrors (void); Purpose This function returns the state of the break on protection errors feature. It returns a 1 if the option is enabled, or a 0 if it is disabled. If debugging is disabled, this function always returns 0. For more information on the feature, see the documentation for SetBreakOnProtectionErrors. Return Value state integer The current state of the break on protection errors option.
Chapter 8 Utility Library Return Codes Nnn Where N.nn is the LabWindows/CVI version. GetCurrentPlatform int platformCode = GetCurrentPlatform (void); Purpose This function returns a code representing the operating system under which a project or standalone executable is running. The return value of GetCurrentPlatform should not be confused with the predefined macros such as _NI_mswin_, _NI_unix_, and others, which specify the platform on which the project is compiled.
Utility Library Chapter 8 GetDir int result = GetDir (char currentDirectory[]); Purpose Gets the current working directory on the default drive. Parameter Output currentDirectory string Current directory. integer Result of operation. Return Value result Return Codes 0 Success. -3 General I/O error occurred. -4 Insufficient memory to complete operation. Parameter Discussion currentDirectory must be at least MAX_PATHNAME_LEN bytes long.
Chapter 8 Utility Library Return Value integer result Result of operation. Return Codes 0 Success. -1 Current directory is on a network drive that is not mapped to a local drive. (currentDriveNumber is set correctly, but numberOfDrives is set to -1.) -3 General I/O error occurred. -4 Insufficient memory to complete operation. -6 Access denied. Parameter Discussion The mapping between the drive number and the logical drive letter is 0 = A, 1 = B, and so on.
Utility Library Chapter 8 Return Codes 0 Success. -1 Out of memory. -4 Invalid file format. -5 Undefined references. -8 Cannot open file. -9 Invalid module ID. -10 Identifier not defined globally in module. -25 DLL initialization failed (e.g. DLL file not found). Parameter Discussion moduleID is the value LoadExternalModule returns. name is the name of the identifier whose address is obtained from the external module.
Chapter 8 Utility Library GetFileAttrs int result = GetFileAttrs (char fileName[], int *read-only, int *system, int *hidden, int *archive); Note: Only available on the Windows version of LabWindows/CVI. Purpose Gets the following attributes of a file: • Read-Only • System • Hidden • Archive The read-only attribute makes it impossible to write to the file or create a file with the same name.
Utility Library Chapter 8 Parameter Discussion Each attribute parameter will contain one of the following values: 0—attribute is not set 1—attribute is set fileName may be the empty string (""), in which case the attributes of the file found by the most recent call to GetFirstFile or GetNextFile are returned. Example /* get the attributes of WAVEFORM.DAT */ int read_only,system,hidden,archive; GetFileAttrs ("waveform.dat",&read_only,&system,&hidden,&archive); if (read_only) FmtOut("WAVEFORM.
Chapter 8 Utility Library Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred. -4 Insufficient memory to complete operation. -5 Invalid path (for example, c:filename in Windows). -6 Access denied. Parameter Discussion fileName may be the empty string (""), in which case the date of the file found by the most recent call to GetFirstFile or GetNextFile is returned (Windows only). Example /* get the date of WAVEFORM.
Utility Library Chapter 8 Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred. -4 Insufficient memory to complete operation. -5 Invalid path (for example, c:filename in Windows). -6 Access denied. Parameter Discussion fileName may be the empty string (""), in which case the size of the file found by the most recent call to GetFirstFile or GetNextFile is returned (Windows only). Example long size; if (GetFileSize ("waveform.
Chapter 8 Utility Library Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred. -4 Insufficient memory to complete operation. -5 Invalid path (for example, c:filename in Windows). -6 Access denied. Parameter Discussion fileName may be the empty string (""), in which case the time of the file found by the most recent call to GetFirstFile or GetNextFile is returned (Windows only). Example /* get the time of WAVEFORM.
Utility Library Chapter 8 Under Windows, all of the attributes are honored. The normal attribute specifies files with no other attributes set or with only the archive bit set. The archive attribute specifies files that have been modified because they were last backed up using the DOS BACKUP command. The readonly attribute specifies files that are protected from being modified or overwritten. The system and hidden attributes specify files which normally do not appear in a directory listing.
Chapter 8 Utility Library Parameter Discussion searchPath may contain the wildcard characters '*' and '?'. Each attribute parameter can have one of the following values: 0— do not search for files with the attribute 1— search for files with the attribute fileName contains the basename and extension of the first matching file and must be at least MAX_FILENAME_LEN characters in length.
Utility Library Chapter 8 Using This Function This function is useful when your program needs to access a file in the project and you do not know what directory the file is in. Example char *fileName; char fullPath[MAX_PATHNAME_LEN]; fileName = "myfile.c" if (GetFullPathFromProject (fileName, fullPath) < 0) FmtOut ("File %s is not in the project\n", fileName); Note: Runtime errors are not reported for this function.
Chapter 8 Utility Library Parameters None Return Value integer k Key code. Using This Function The values returned are the same as the key values used in the User Interface Library. See userint.h. Keystroke Return Value 'b' (VAL_MENUKEY_MODIFIER | 'B') VAL_F4_VKEY (VAL_SHIFT_MODIFIER | VAL_F4_VKEY) Note: This function returns -1 if you are running on UNIX and have done one of the following.
Utility Library Chapter 8 Purpose This function obtains the name of the directory of the specified DLL module. This function is useful when a DLL and its related files are distributed to multiple users who may place them in different directories. If your DLL needs to access a file that is in the same directory as the DLL, you can use the GetModuleDir and MakePathname functions to construct the full pathname.
Chapter 8 Utility Library GetNextFile int result = GetNextFile (char fileName[]); Purpose Gets the next file found in the search starting with GetFirstFile. Parameters Output fileName string Next file found. integer Result of search. Return Value result Return Codes 0 Success. -1 No more files found matching criteria. -2 GetFirstFile must initiate search.
Utility Library Chapter 8 GetProjectDir int result = GetProjectDir (char directoryName[]); Purpose Gets the name of the directory containing the currently loaded project file. Parameters Output directoryName string Directory of project. integer Result of operation. Return value result Return codes 0 -1 Success. Current project has no pathname (it is untitled). Parameter Discussion directoryName must be at least MAX_PATHNAME_LEN bytes long.
Chapter 8 Utility Library GetStdioPort void GetStdioPort (int *stdioPort); Purpose Gets a value indicating the current destination for data written to the standard output (and the source of data read from the standard input.) The Standard I/O port can be either the CVI Standard Input/Output window or the standard Input/Output of the host system. This function is valid only on the UNIX version. Parameters Output stdioPort integer 0 = the CVI Standard Input/Output window.
Utility Library Chapter 8 Parameters Output maxNumLines integer bringToFrontWhenModified integer showLineNumbers integer The maximum number of lines that can be stored in the Standard Input/Output window. If this amount is exceeded, lines are discarded from the top. Indicates whether the Standard Input/Output window is brought to the front each time a string or character is added to it. 1 = Yes. 0 = No. Indicates whether line numbers are shown in the Standard Input/Output window. 1 = Yes. 0 = No.
Chapter 8 Utility Library Parameters Output top integer The current distance, in pixels, from the top of client area of the Standard Input/Output window to the top of the screen. left integer The current distance, in pixels, from the leftmost edge of client area of the Standard Input/Output window to the left edge of the screen. GetStdioWindowSize void GetStdioWindowSize (int *height, int *width); Purpose Gets the height and width, in pixels, of the client area of the Standard Input/Output window.
Utility Library Chapter 8 Parameters Output visible integer 1 = Standard I/O window is visible. 0 = Standard I/O window is not visible. GetSystemDate int status = GetSystemDate (int *month, int *day, int *year); Note: This function is only available on the Windows version of LabWindows/CVI. Purpose Obtains the system date in numeric format. Parameters Output month integer Month (1–12). day integer Day of month (1–31). year integer Year (Under Windows 3.
Chapter 8 Utility Library GetSystemTime int status = GetSystemTime(int *hours, int *minutes, int *seconds); Note: This function is only available on the Windows version of LabWindows/CVI. Purpose Obtains the system time in numeric format. Parameters Output hours integer Hours (0–23). minutes integer Minutes (0–59). seconds integer Seconds (0–59). integer Success or failure. Return Value status Return Codes 0 -1 Success. Failure reported by operating system.
Utility Library Chapter 8 Parameters Output visible integer 0, if window is to be hidden; 1, if window is to be displayed. zoomState integer ATTR_NO_ZOOM—normal display; ATTR_MINIMIZE ATTR_MAXIMIZE. Return Value None Example If you want to honor the user’s display options, put the following code where you display your initial panel.
Chapter 8 Utility Library Parameters Input hInstance void pointer 0 if called from main. hInstance if called from WinMain (first parameter). hInstDLL if called from DllMain (first parameter). argv string array argv if called from main (second parameter). Otherwise, 0. reserved void pointer Reserved for future use. Pass 0. integer 1 indicates success. 0 indicates failure (probably out of memory).
Utility Library Chapter 8 /* your other DETACH code */ CloseCVIRTE (); } return 1; } Note: The prototypes for InitCVIRTE and CloseCVIRTE are in cvirte.h, which is included by utility.h. inp char byteRead = inp (int portNumber); Note: This function is available only on the Windows versions of LabWindows/CVI. Purpose Reads a byte from a port. Note: For you to be able to use this function under Windows NT, the LabWindows/CVI lowlevel support driver must be loaded.
Chapter 8 Utility Library Parameters Input portNumber integer The port. short Word read from port. Return Value wordRead InStandaloneExecutable int standalone = InStandaloneExecutable(void); Purpose Returns a non-zero value if your program is running as a standalone executable. If your program is running in the LabWindows/CVI development environment, a zero is returned. Return Value standalone integer 1 = Program is running as a standalone executable. 0 = Program is running as in LabWindows/CVI.
Utility Library Chapter 8 Return Codes 0 Key has not been pressed. 1 Key has been pressed. Using This Function The function returns 1 if a keystroke is available in the keyboard buffer, 0 otherwise. After a keystroke is available, you should make a call to GetKey to flush the keyboard buffer. Otherwise, KeyHit will continue to return 1. Note: This function always returns 0 if you are running on UNIX and have done one of the following.
Chapter 8 Utility Library 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 or by creating another .pif file. Refer to your Microsoft Windows documentation for help on creating and editing .pif files. Parameter Input fileName string Pathname of executable file and arguments.
Utility Library Chapter 8 Return Codes under Microsoft Windows 0 Command was successfully started. -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 networkprotection error. -7 Library required separate data segments for each task. -9 There was insufficient memory to start the application. -11 Windows version was incorrect.
Chapter 8 Utility Library LaunchExecutableEx int result = LaunchExecutableEx (char *fileName, int windowState, int *handle); Purpose LaunchExecutableEx performs the same operation as LaunchExecutable with the following extended features: • Under Windows, you can specify how the Windows application displays. • This function returns a handle to the executable that can show whether the executable is still running and also terminate the executable.
Utility Library Chapter 8 A handle can be passed to ExecutableHasTerminated and TerminateExecutable. When you no longer need the handle, you should call RetireExecutableHandle. When you do not want to obtain a handle, you can pass NULL. When you launch several processes with LaunchExecutableEx but do not call RetireExecutableHandle on them, you might reach the limit for the maximum number of processes the system imposes.
Chapter 8 Utility Library LoadExternalModule int module_id = LoadExternalModule (char pathName[]); Purpose Loads a file containing one or more object modules. Parameter Input pathName string Relative or absolute pathname of the module to be loaded. integer ID of the loaded module. Return Value module_id Return Codes -1 Out of memory. -2 File not found. -4 Invalid file format. -6 Invalid path name. -7 Unknown file extension. -8 Cannot open file. -11 .PTH file open error. -12 .
Utility Library Chapter 8 Return Codes (Continued) -21 Could not load the DLL. -22 Could not find the DLL header file. -23 Could not load the DLL header file (out of memory or the file is corrupted). -24 Syntax error in the DLL header file. -25 DLL initialization function failed. -26 Module already loaded with different calling module handle. (See LoadExternalModuleEx.) -27 Invalid calling module handle. (See LoadExternalModuleEx.
Chapter 8 • Utility Library You can call RunExternalModule. This requires that the module contain a function with a pre-defined name and prototype. The function serves as the entry point to the module. See RunExternalModule for more information. LoadExternalModule can also be used on a source file (.c) that is part of the current project or a source file that has been loaded as the program for an instrument module.
Utility Library Chapter 8 3. If the file has not been found and its extension is .dll, LoadExternalModule searches for the file in the directories specified in the Windows LoadLibrary call. If it is a relative pathname with one or more directory paths (such as dir\module.obj), LoadExternalModule creates an absolute pathname by appending the relative pathname to the directory that contains the currently loaded project.
Chapter 8 Utility Library Parameters Input pathName string Relative or absolute pathname of the module to be loaded. callingModuleHandle void pointer Usually, the module handle of the calling DLL. You can use __CVIUserHInst. Zero indicates the project or executable. integer ID of the loaded module. Return Value moduleId Return Codes Same as the return codes for LoadExternalModule. Using this Function Refer to the function help for LoadExternalModule for detailed information on that function.
Utility Library Chapter 8 command in the Build menu of the Project Window to create an object file containing the table. You must include this object file in the external compiler project you use to create the DLL.
Chapter 8 Utility Library Example /* make a new directory named \DATA\WAVEFORM on drive C /* /* assuming that C:\DATA does not exist */ MakeDir ("C:\\DATA"); MakeDir ("C:\\DATA\\WAVEFORM"); MakePathname void MakePathname (char directoryName[], char fileName[], char pathName[]); Purpose Constructs a path name from a directory path and a filename. The subroutine ensures that the directory path and the filename are separated by a backslash. Parameters Input Output directoryName string Directory path.
Utility Library Chapter 8 outp char byteWritten = outp(int portNumber, char byteToWrite); Note: This function is available only on the Windows versions of LabWindows/CVI. Purpose Writes a byte to a port. Note: For you to be able to use this function under Windows NT, the LabWindows/CVI lowlevel support driver must be loaded. Parameters Input portNumber integer The port. byteToWrite char The byte to be written. char The byte that was written.
Chapter 8 Utility Library ReadFromPhysicalMemory int status = ReadFromPhysicalMemory (unsigned int physicalAddress, void *destinationBuffer, unsigned int numberOfBytes); Note: This function is available only on the Windows versions of LabWindows/CVI. Purpose Copies the contents of a region of physical memory into destinationBuffer. The function does not check whether the memory actually exists. If the memory does not exist, the success value is returned but no data is read.
Utility Library Chapter 8 ReadFromPhysicalMemoryEx int status = ReadFromPhysicalMemoryEx (unsigned int physicalAddress, void *destinationBuffer, unsigned int numberOfBytes, int bytesAtATime); Note: This function is available only in the Windows version of LabWindows/CVI. Purpose This function copies the contents of a region of physical memory into the specified buffer. It can copy the data in units of 1, 2, or 4 bytes at a time. The function does not check whether the memory actually exists.
Chapter 8 Utility Library ReleaseExternalModule int status = ReleaseExternalModule (int moduleID); Purpose Decreases the reference count for a module loaded using LoadExternalModule. When LoadExternalModule is called successfully on a module, that module's reference count is incremented by one. When you call ReleaseExternalModule, its reference count is decremented by one.
Utility Library Chapter 8 RenameFile int result = RenameFile (char existingFileName[], char newFileName[]); Purpose Renames an existing file. Parameters Input existingFileName string Existing file name. newFileName string New file name. integer Result of rename operation. Return Value result Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred. -4 Insufficient memory to complete operation. -5 Invalid path (for either of the file names).
Chapter 8 Utility Library Under UNIX, if the arguments to RenameFile specify files on different file systems, RenameFile copies the source to the target and then deletes the source file. RetireExecutableHandle int status = RetireExecutableHandle (int executableHandle); Purpose Informs the Utility Library that you no longer intend to use the handle acquired from LaunchExecutableEx. When you call this function the Utility Library can reuse the memory allocated to keep track of the state of the executable.
Utility Library Chapter 8 Return Value long n Result of the rounding operation. Example long n; n = round n = round n = round n = round n = round n = round n = round n = round (1.2); (1.8); (1.5); (0.5); (-1.2); (-1.8); (-1.5); (-0.
Chapter 8 Utility Library Parameter Discussion moduleID is the value LoadExternalModule returns. buffer is a character array in which you can pass information to and from the module. RunExternalModule requires that the module define the following function: void _xxx_entry_point (char []) where xxx is the base name of the file, in lowercase. For example, if the pathname of the file is as follows: C:\LW\PROGRAMS\TEST01.
Utility Library Chapter 8 If debugging is disabled, this function has no effect. Run-time errors are never reported when debugging is disabled. Parameters Input newState integer Pass a nonzero value to enable. Pass zero to disable. integer Previous state of the break on library errors feature. Return Value oldState Return Codes 1 Was previously enabled. 0 Was previously disabled, or debugging is disabled.
Chapter 8 Utility Library You can use this function to prevent LabWindows/CVI from displaying the dialog box and suspending execution when it encounters a protection error. In general, it is better not to disable the break on protection errors feature. Nevertheless, you may want to disable it temporarily around a line of code for which LabWindows/CVI is erroneously reporting a protection error. If debugging is disabled, this function has no effect.
Utility Library Chapter 8 SetDir int result = SetDir (char directoryName[]); Purpose Sets the current working directory to the specified directory. Under Windows 3.1, this function can change the current working directory on any drive, however it does not change the default drive. To change the default drive, use the SetDrive function. Parameters Input directoryName string New current working directory. integer Result of operation. Return Value result Return Codes 0 Success.
Chapter 8 Utility Library Return Value integer result Result of operation. Return Codes 0 Success. -1 Invalid drive number. Using This Function The mapping between the drive number and the logical drive letter is 0 = A, 1 = B, and so on. SetFileAttrs int result = SetFileAttrs (char fileName[], int read-only, int system, int hidden, int archive); Note: This function is available only on the Windows versions of LabWindows/CVI.
Utility Library Chapter 8 Return Value result return value Result of operation. Return Codes 0 -1 Success. One of the following errors occurred: • File not found. • Attribute cannot be changed. Parameter Discussion Each attribute parameter can have one of the following values: 0—clears the attribute 1—sets the attribute -1—leaves the attribute unchanged fileName may be the empty string (""), in which case the attributes of the file found by the most recent call to GetFirstFile or GetNextFile are set.
Chapter 8 Utility Library Parameters Input fileName string File to set attributes. month integer Month (1 to 12) 1 —January 2 —February 3 —March 4 —April 5 —May 6 —June 7 —July 8 —August 9 —September 10 —October 11 —November 12 —December day integer Day of month (1 to 31) year integer Year (1980–2099) integer Result of operation. Return Value status Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred.
Utility Library Chapter 8 SetFileTime int result = SetFileTime (char fileName[], int hours, int minutes, int seconds); Purpose Sets the time of a file. Parameters Input fileName string File to set date. hours integer Hours (0 to 23). minutes integer Minutes (0 to 59). seconds integer Seconds (0-58); Odd Values are rounded down. integer Result of operation. Return Value result Return Codes 0 Success. -1 File not found or directory in path not found. -3 General I/O error occurred.
Chapter 8 Utility Library SetPersistentVariable void SetPersistentVariable (int value); Purpose Lets you store an integer value across multiple builds and executions of your project in the LabWindows/CVI development environment. When you unload a project or load a new project, the value is reset to zero. This function is useful when your program performs an action (such as setting up your instruments) that takes a long time and that you do not want to be repeated each time you re-run your program.
Utility Library Chapter 8 Parameters Input stdioPort integer CVI_STDIO_WINDOW (0) = the CVI Standard Input/Output window. HOST_SYSTEM_STDIO (1) = the host system's standard output. integer Indicates whether the function succeeded. Return Value status Return Codes 0 -2 Success. Destination was not a valid range. Parameter Discussion In a standalone executable, the default value for stdioPort is CVI_STDIO_WINDOW.
Chapter 8 Utility Library Parameters Input maxNumLines integer bringToFrontWhenModified integer showLineNumbers integer The maximum number of lines that can be stored in the Standard Input/Output Window. If this amount is exceeded, lines are discarded from the top. Valid range: 100 to 1000000. Indicates whether the Standard Input/Output window is brought to the front each time a string or character is added to it. 1 = Yes. 0 = No.
Utility Library Chapter 8 showLineNumbers—In an executable, the default value is 0 ("do not show line numbers"). In the CVI Development System, the default value is the current state of the Line Numbers option in the View menu of the Standard Input/Output Window. The value that you set using this function is reflected the next time you bring up the View menu.
Chapter 8 Utility Library Parameter Discussion To vertically center the Standard Input/Output window client area within the area of the screen, pass VAL_AUTO_CENTER as the top parameter. To horizontally center the Standard Input/Output window client area within the area of the screen, pass VAL_AUTO_CENTER as the left parameter. SetStdioWindowSize int status = SetStdioWindowSize (int height, int width); Purpose Sets the height and width, in pixels, of the client area of the Standard Input/Output window.
Utility Library Chapter 8 SetStdioWindowVisibility void SetStdioWindowVisibility (int visible); Purpose Either brings to the front or hides the Standard Input/Output window. Parameters Input visible integer 1 = Standard I/O window is visible. 0 = Standard I/O window is hidden. SetSystemDate int status = SetSystemDate (int month, int day, int year); Note: This function is only available on the Windows version of LabWindows/CVI.
Chapter 8 Utility Library SetSystemTime int status = SetSystemTime(int hours, int minutes, int seconds); Note: This function is only available on the Windows version of LabWindows/CVI. Under Windows NT, you must have system administrator status to use this function. Purpose Sets the system time. Parameters Input hours integer Hours (0–23). minutes integer Minutes (0–59). seconds integer Seconds (058). Odd values are rounded down. integer Success or failure.
Utility Library Chapter 8 Parameters Input pathName string Path name to be split. Output driveName string Drive name. directoryName string Full directory path, ending with directory separator character. fileName string Simple file name. Return Value None Parameter Discussion The driveName, directoryName, and fileName parameters can each be NULL. If not NULL, they must be buffers of the following size or greater.
Chapter 8 Utility Library SyncWait void SyncWait (double beginTime, double interval); Purpose Waits until the number of seconds indicated by interval have elapsed since beginTime. Parameters Input beginTime interval double-precision double-precision Value returned by Timer. Number of seconds to wait after begin_time. Parameter Discussion beginTime must be a value returned by the Timer function. The resolution on Windows is normally 1 millisecond.
Utility Library Chapter 8 Parameters Input helpFile string Points to a string containing the help file that the Help application is to display. Specifies the type of help requested. command unsigned integer additionalLongData unsigned long integer This value parameter depends on the command parameter as described in the Parameter Discussion. additionalStringData string This value parameter depends on the command parameter as described in the Parameter Discussion.
Chapter 8 Utility Library HELP_CONTEXTPOPUP—Displays in a pop-up window a particular Help topic identified by a context number that has been defined in the [MAP] section of the .HPJ file. The main help window is not displayed. In this case, additionalLongData is the context number of the topic. HELP_HELPONHELP—Displays the contents topic of the designated Using Help file.
Utility Library Chapter 8 TerminateExecutable int status = TerminateExecutable (int executableHandle); Purpose Attempts to terminate an executable if it has not already terminated. Under Windows the system terminates an executable by sending close messages to each window in the application. If the application does not honor the close messages, then the application does not terminate.
Chapter 8 Utility Library Timer double t = Timer (void); Purpose Returns the number of seconds that have elapsed since the first call to Timer, Delay, or SyncWait or the first operation on a timer control. The value is never reset to zero except when you restart your program. The resolution on Windows is normally 1 millisecond. However, if the following line appears in the CVI section of your WIN.INI file, the resolution is 55 milliseconds.
Utility Library Chapter 8 TruncateRealNumber double y = TruncateRealNumber (double inputRealNumber); Purpose Truncates the fractional part of inputRealNumber and returns the result as a real number. Parameters Input inputRealNumber double-precision. Return Value double-precision y Value of inputRealNumber without its fractional part. UnloadExternalModule int status_id = UnloadExternalModule (int moduleID); Purpose Unloads an external module file loaded via LoadExternalModule.
Chapter 8 Utility Library Example int module_id; int status; char *pathname' pathname = "PROG.OBJ"; module_id = LoadExternalModule (pathname); if (module_id <0) FmtOut ("Unable to load %s\n", pathname); else { RunExternalModule (module_id, ""); UnloadExternalModule (module_id); } WriteToPhysicalMemory int status = WriteToPhysicalMemory (unsigned int physicalAddress, void *sourceBuffer, unsigned int numberOfBytes); Note: This function is available only on the Windows versions of LabWindows/CVI.
Utility Library Chapter 8 Return Value status integer Indicates whether the function succeeded. Return Codes 1 0 Success. Failure reported by the operating system, or low-level support driver not loaded. WriteToPhysicalMemoryEx int status = WriteToPhysicalMemoryEx (unsigned int physicalAddress, void *sourceBuffer, unsigned int numberOfBytes, int bytesAtATime); Note: This function is available only in the Windows version of LabWindows/CVI.
Chapter 8 Utility Library Return Value integer status Indicates whether the function succeeded. Return Codes 1 Success. 0 Failure reported by operating system, or low-level support driver not loaded, or numberOfBytes is not a multiple of bytesAtATime, or invalid value for bytesAtATime. Parameter Discussion numberOfBytes must be a multiple of bytesAtATime.
Chapter 9 X Property Library _____________________________________________________________________________ This chapter describes the functions in the Lab/Windows CVI X Property Library. The X Property Library contains functions that read and write properties to and from X Windows. The X Property Library Overview section contains general information about the X Property Library functions and panels. The X Property Library Function Reference section contains an alphabetical list of function descriptions.
X Property Library Chapter 9 Table 9-1.
Chapter 9 X Property Library With the LabWindows/CVI X Property Library functions, you can connect to X displays and obtain the root window ID, read and write properties on windows, and monitor when specific properties change. Property Handles and Types Before you can read or write properties on windows, you must create the property and its type. The function CreateXProperty takes a property name and a property type and returns a property handle you can use to access properties on windows.
X Property Library Chapter 9 not delete it, the property remains there indefinitely. Second, because there is only one root window, there may be conflicts when multiple applications attempt to access the same properties. To overcome those disadvantages, LabWindows/CVI provides a hidden window. Before it runs your program, LabWindows/CVI creates a window that never displays. The X window ID for this window is available in the X Property Library from the global variable CVIXHiddenWindow.
Chapter 9 X Property Library Table 9-3. X Property Library Error Types and Descriptions Constant Name NoXErr Value Description 0 The function was successful. InvalidParamXErr -1 The value passed to one or more of the parameters was invalid. Refer to each function description for specific information. InvalidDisplayXErr -2 The display argument is not a valid display. The value for this argument must either be the value returned by ConnectToXDisplay or be the predefined value CVIXDisplay.
X Property Library Chapter 9 Table 9-3. X Property Library Error Types and Descriptions (Continued) DupPropTypeXErr -9 A property type with the same typeName, but with different size or unit already exists. PropertyInUseXErr -10 A property callback was installed with InstallPropertyCallback for this property. It is not possible to destroy properties for which callbacks are installed. PropTypeInUseXErr -11 There is a property created by CreateXProperty that has this property type.
Chapter 9 X Property Library Using the Library Outside of LabWindows/CVI You can use the LabWindows/CVI X Property Library in applications developed outside of LabWindows/CVI. By linking your program with the library file libxprop.a in the misc/lib directory of the LabWindows/CVI installation directory, you can use all the functions of the X Property Library in your program. You cannot use the libxprop.a library within LabWindows/CVI.
X Property Library Chapter 9 Parameters Input displayName Output display rootWindow string Determines the X server connection and which communication domain to use. DisplayPtrX (passed by reference) Pointer to the display of the remote X server. Use this value as the argument to other library functions to communicate with the remote X server. WindowX (passed by reference) Root window of the remote X server.
Chapter 9 X Property Library See Also Refer to the Xlib Programming Manual or to Xlib—C Language X Interface, MIT X Consortium Standard for more information about the XOpenDisplay and DefaultRootWindow functions. _____________________________________________________________________________ CreateXProperty PropLibXErrType status = CreateXProperty (const char *propertyName, PropTypeHandleX propertyType, PropertyHandleX *property); Purpose Create X property information.
X Property Library Chapter 9 Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to one or more of the parameters. InvalidPropTypeXErr -5 The propertyType argument is not a valid property type. This value must either be one of the predefined property types or be a value returned by CreateXPropType.
Chapter 9 X Property Library There are three predefined property types that you do not need to create using this function. These types, listed below, are useful for defining properties to store window IDs, integers and strings. Property Type WINDOW_X_PROP_TYPE INTEGER_X_PROP_TYPE STRING_X_PROP_TYPE Name "WINDOW" "INTEGER" "STRING" Size/Unit sizeof(WindowX) sizeof(int) sizeof(char) Note: You can create a maximum of 64 different property types.
X Property Library Chapter 9 Parameter Discussion Usually, you can use the expression sizeof(TYPE) for the size parameter, where TYPE is the C data type (char, int, and others) used to store the property value. This value must be a multiple of the unit argument. unit specifies how the X server should view the property item (as an array of 1-byte, 2-byte or 4-byte objects) and is necessary to perform simple byte-swapping between different types of computers.
Chapter 9 X Property Library Parameter Input property PropertyHandleX Handle to the property information to be destroyed. This value must either be one of the predefined property types or be a value returned by CreateXPropType. Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful.
X Property Library Chapter 9 Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidPropTypeXErr PropTypeInUseXErr -5 The propertyType argument is not a valid property type. This value must either be one of the predefined property types or be a value returned by CreateXPropType.
Chapter 9 X Property Library See Also Refer to the Xlib Programming Manual or to Xlib—C Language X Interface, MIT X Consortium Standard for more information about the XCloseDisplay function. GetXPropErrorString char *message = GetXPropErrorString (PropLibXErrType errorNum) Purpose Converts the error number returned by an X Property Library function into a meaningful error message. Parameters Input PropLibXErrType Status returned by an X Property function.
X Property Library Warning: Chapter 9 The propertyName pointer points to memory allocated by CreateXProperty. You must not attempt to free this pointer or to change its contents. Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to the name parameter.
Chapter 9 X Property Library Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to the parameter. InvalidPropertyXErr -4 The property argument is not a valid property handle. This argument must be the value returned by CreateXProperty.
X Property Library Chapter 9 See Also CreateXPropType GetXPropTypeSize PropLibXErrType status = GetXPropTypeSize (PropTypeHandleX propertyType, unsigned int *size); Purpose Gets a property type size. This function returns the size associated with the property type. The size is the number of bytes in a single property item. Parameters Input propertyType Output size PropTypeHandleX Handle to property type for which the size is to be obtained.
Chapter 9 X Property Library GetXPropTypeUnit PropLibXErrType status = GetXPropTypeUnit (PropTypeHandleX propertyType, unsigned int *unit); Purpose Get a property type unit. This function returns the unit associated with the property type. The unit is the number of bytes (1, 2, or 4) in the basic objects that make up a property item. Parameters Input propertyType Output unit PropTypeHandleX Handle to property type for which the unit is to be obtained.
X Property Library Chapter 9 GetXWindowPropertyItem PropLibXErrType status = GetXWindowPropertyItem (DisplayPtrX display, WindowX window, PropertyHandleX property, void *propertyItem); Purpose Get a single property item from a window. This function obtains the value of the specified property on the window and copies a single item into the supplied buffer. When there are more than one item in the property value, this function obtains only the first one. This function does not change the property value.
Chapter 9 X Property Library Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to one or more parameters. InvalidDisplayXErr -2 The display argument is not a valid display. This argument must either be the predefined value CVIXDisplay or be the value returned by ConnectToXDisplay.
X Property Library Chapter 9 See Also Refer to the Xlib Programming Manual or to Xlib—C Language X Interface, MIT X Consortium Standard for more information about the XGetWindowProperty function.
Chapter 9 X Property Library Parameters Input display DisplayPtrX A pointer to the display of the X server to which the window belongs. window WindowX The window from which the property value is to be obtained. property PropertyHandleX Handle of the property to be obtained. This value must have been obtained with CreateXProperty. index unsigned integer Index into the property value where reading is to begin. Specify the number of property items to skip from the start of the property value.
X Property Library Chapter 9 Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to one or more parameters. InvalidDisplayXErr -2 The display argument is not a valid display. This argument must either be the predefined value CVIXDisplay or be the value returned by ConnectToXDisplay.
Chapter 9 X Property Library See Also Refer to the Xlib Programming Manual or to Xlib—C Language X Interface, MIT X Consortium Standard for more information about the XGetWindowProperty function.
X Property Library Chapter 9 Parameters (Continued) numberofProperties unsigned integer Number of properties in the Property List. callbackData generic pointer Pointer to data to be passed to the callback function. This value is passed to the callback function as the userData parameter. callbackFunction PropertyCallbackTypeX * Pointer to the function to be called when the properties change. Return Values The return value indicates the success or failure status of the function call.
Chapter 9 X Property Library default root window of the display used by LabWindows/CVI. Use &CVIXHiddenWindow to specify the hidden window associated with your application. If numberofProperties is 0 or the propertyList value is ANY_X_PROPERTY, the callback function is called whenever any property changes on any of the windows in the windowList. The values in the propertyList array must have been obtained with CreateXProperty.
X Property Library Chapter 9 Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to one or more parameters. InvalidDisplayXErr -2 The display argument is not a valid display. This argument must either be the predefined value CVIXDisplay or be the value returned by ConnectToXDisplay.
Chapter 9 X Property Library PutXWindowPropertyValue PropLibXErrType status = PutXWindowPropertyValue (DisplayPtrX display, WindowX window, PropertyHandleX property, unsigned int numberofItems, int mode, void *propertyValue); Purpose This function stores the supplied value with the property on the window. To store a single property item, you can use the function PutXWindowPropertyItem. Parameters Input display DisplayPtrX A pointer to the display of the X server to which the window belongs.
X Property Library Chapter 9 Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to one or more parameters. mode is not ReplaceXPropMode, PrependXPropMode or AppendXPropMode. InvalidDisplayXErr -2 The display argument is not a valid display.
Chapter 9 X Property Library The following values are valid for the mode parameter: ReplaceXPropMode—Replace the existing property value with the new value. PrependXPropMode—Add the new property value to the beginning of the existing value. AppendXPropMode—Add the new property value to the end of the existing value. See Also Refer to the Xlib Programming Manual or to Xlib—C Language X Interface, MIT X Consortium Standard for more information about the XChangeProperty function.
X Property Library Chapter 9 Return Values The return value indicates the success or failure status of the function call. A negative value indicates an error. The following table shows status values. NoXErr 0 The function was successful. InvalidParamXErr -1 NULL was passed to one or more parameters. InvalidDisplayXErr -2 The display argument is not a valid display. This argument must either be the predefined value CVIXDisplay or be the value returned by ConnectToXDisplay.
Chapter 9 X Property Library UninstallXPropertyCallback PropLibXErrType status = UninstallXPropertyCallback (PropertyCallbackTypeX *callbackFunction); Purpose Uninstall a property callback function. After a callback function is uninstalled, it is no longer called when properties change. All property callback functions are automatically uninstalled when the program terminates.
Chapter 10 Easy I/O for DAQ Library This chapter describes the functions in the Easy I/O for DAQ Library. The Easy I/O for DAQ Library Function Overview section contains general information about the functions, and guidelines and restrictions you should know when using the Easy I/O for DAQ Library. The Easy I/O for DAQ Library Function Reference section contains an alphabetical list of function descriptions.
Easy I/O for DAQ Library Chapter 10 The Easy I/O for DAQ functions are device independent which means that you can use the same function on a Lab series board, an MIO board, an EISA-A2000 or SCXI module. Limitations of Using the Easy I/O for DAQ Library The Easy I/O for DAQ Library currently only works with Analog I/O, Counter/Timers, and simple Digital I/O. The Easy I/O for DAQ Library does not currently work with multirate scanning.
Chapter 10 Easy I/O for DAQ Library Table 10-1.
Easy I/O for DAQ Library Chapter 10 Device Numbers The first parameter to most of the Easy I/O for DAQ functions is the device number of the DAQ device you want to use for the given operation. After you have followed the installation and configuration instructions in Chapter 1, Introduction to NI-DAQ, of the NI-DAQ User Manual for PC Compatibles, the configuration utility displays the device number for each device you have installed in the system.
Chapter 10 Easy I/O for DAQ Library • If you are using a Lab-PC+, DAQCard-500/700/1200, DAQPad-1200, PC-LPM-16: These devices can only sample input channels in descending order, and you must end with channel 0 ("3:0"). If you are using a Lab-PC+ or 1200 product in differential mode, you must use even-numbered channels ("6,4,2,0").
Easy I/O for DAQ Library Chapter 10 Command Strings You can use command strings within the Channel String to set per-channel limits and an interchannel sample rate. For example, "cmd hi 10.0 low -10.0; 7:4; cmd hi 5.0 low -5.0; 3:0" specifies that channels 7 through 4 should be scanned with limits of +/- 10.0 volts and channels 3 through 0 should be scanned with limits of +/- 5.0 volts.
Chapter 10 Easy I/O for DAQ Library Channel String for Analog Output Functions The second parameter to most of the analog output functions is the channel string containing the analog output channels that are to be driven. Refer to the chapter specific to your DAQ device in the DAQ Hardware Overview Guide to determine what channels are valid for your hardware. The document is an Adobe Acrobat file, daqhwov.pdf, that you can view on screen and also print. daqhwov.pdf is part of a set of .
Easy I/O for DAQ Library Chapter 10 Easy I/O for DAQ Function Reference This section describes each function in the Easy I/O for DAQ Library. The function descriptions are arranged alphabetically.
Chapter 10 Easy I/O for DAQ Library Parameters Input Output device short integer Assigned by configuration utility. channelString string Analog input channels that are to be sampled. numberOfScans long integer Number of scans to be acquired complete. One scan involves sampling every channel in the channelString once. scansPerSecond double Number of scans performed per second. Any particular channel to be scanned at this rate. highLimitVolts double Maximum voltage to be measured.
Easy I/O for DAQ Library Chapter 10 Parameter Discussion channelString is the analog input channels that are to be sampled. Refer to the Channel String for Analog Input Functions subsection of the Easy I/O for DAQ Library Function Overview section of this chapter for the syntax of this string. triggerType is the trigger type.
Chapter 10 Easy I/O for DAQ Library For example, if the A/D conversions (represented by x's) on the waveform shown below are placed side-by-side, they represent one cycle of the waveform. _ _ _ x _ _ _ / \ / \ x \ / \ / x / \ / \ / \ x \ / \ / \ / \ / x / \ x \_/ \_/ \_/ \_/ \_/ \_/ x_/ x x x x x x x Equivalent Time Sampling is accomplished in this function as follows: 1.
Easy I/O for DAQ Library Chapter 10 When the A/D conversions are placed side-by-side, they represent the original waveform as if it had been sampled at a high frequency. x x x x x x x edgeSlope specifies whether the trigger occurs when the trigger signal voltage is leading (POSITIVE_SLOPE) or trailing (NEGATIVE_SLOPE). triggerLevelV the voltage at which the trigger is to occur. triggerLevelV is valid only when the Trigger Type is hardware or software analog trigger.
Chapter 10 Easy I/O for DAQ Library waveforms is an array containing the voltages acquired on the channels specified in the channelString. The acquired voltages are placed into the array in the order specified by fillMode. This array must be declared as large as: (number of channels) * (numberOfScans) You can determine the number of channels using the GetNumChannels function.
Easy I/O for DAQ Library Chapter 10 Return Value error short integer Refer to error codes in Table 10-5. Parameter Discussion channelString is the analog input channels that are to be sampled. Refer to the Channel String for Analog Input Functions subsection of the Easy I/O for DAQ Library Function Overview section of this chapter for the syntax of this string. fillMode specifies whether the waveforms array is grouped by channels or grouped by scans.
Chapter 10 Easy I/O for DAQ Library AICheckAcquisition short error = AICheckAcquisition (unsigned long taskID, unsigned long *scanBacklog); Purpose This function can be used to determine the backlog of scans that have been acquired into the circular buffer but have not been read using AIReadAcquisition. If AIReadAcquisition is called with read mode set to LATEST_MODE, scanBacklog is reset to zero. Parameters Input taskID unsigned long integer The task ID that was returned from AIStartAcquisition.
Easy I/O for DAQ Library Chapter 10 AIReadAcquisition short error = AIReadAcquisition (unsigned long taskID, long scanstoRead, unsigned short readMode, unsigned long *scanBacklog, short fillMode, double waveforms[]); Purpose This function reads the specified number of scans from the internal circular buffer established by AIStartAcquisition. If the specified number of scans is not available in the buffer, the function waits until the scans are available.
Chapter 10 Easy I/O for DAQ Library from the internal circular buffer, where n is scanstoRead. Calling AIReadAcquisition in this mode resets the scanBacklog to zero. scanBacklog returns the backlog of scans that have been acquired into the circular buffer but have not been read using AIReadAcquisition. If AIReadAcquisition is called in "latest" read mode, the scan backlog is reset to zero. You can also call AICheckAcquisition to determine the scan backlog before calling AIReadAcquisition.
Easy I/O for DAQ Library Chapter 10 Parameter Discussion singleChannel is the analog input channel that is to be sampled. See the Channel String for Analog Input Functions subsection of the Easy I/O for DAQ Library Function Overview section in this chapter for the syntax of this string.
Chapter 10 Easy I/O for DAQ Library AIStartAcquisition short error = AIStartAcquisition (short device, char channelString[], int bufferSize, double scansPerSecond, double highLimitVolts, double lowLimitVolts, double *actualScanRate, unsigned long *taskID); Purpose This function starts a continuous asynchronous acquisition on the analog input channels specified in the channelString. Data is acquired into an internal circular buffer. Use AIReadAcquisition to retrieve scans from the internal buffer.
Easy I/O for DAQ Library Chapter 10 AOClearWaveforms short error = AOClearWaveforms (unsigned long taskID); Purpose This function clears the waveforms generated by AOGenerateWaveforms when you passed 0 for its Iterations parameter. Parameters Input taskID unsigned long integer The task ID that was returned from AOGenerateWaveforms. Return Value error LabWindows/CVI Standard Libraries short integer Refer to error codes in Table 10-5.
Chapter 10 Easy I/O for DAQ Library AOGenerateWaveforms short error = AOGenerateWaveforms (short device, char channelString[], double updatesPerSecond, int updatesPerChannel, int iterations, double waveforms[], unsigned long *taskID); Purpose This function generates a timed waveform of voltage data on the analog output channels specified in the channelString. Parameters Input Output device short integer Assigned by configuration utility.
Easy I/O for DAQ Library Chapter 10 updatesPerChannel is the number of D/A conversions that compose a waveform for a particular channel. If updatesPerChannel is 10, then each waveform is composed of 10 elements from the waveforms array. iterations is the number of waveform iterations that are performed before the operation is complete. If you pass 0, the waveform(s) are generated continuously and you need to call AOClearWaveforms to clear waveform generation.
Chapter 10 Easy I/O for DAQ Library Parameters Input device short integer Assigned by configuration utility. singleChannel string The analog output channel to which the voltage are applied. voltage double The voltage that is applied to the analog output channel. short integer Refer to error codes in Table 10-5. Return Value error Parameter Discussion singleChannel is the analog output channel to which the voltage are applied.
Easy I/O for DAQ Library Chapter 10 Parameter Discussion channelString is the analog output channels to which the voltages are applied. Refer to the Channel String for Analog Output Functions subsection of the Easy I/O for DAQ Library Function Overview section of this chapter for the syntax of this string. voltageArray is the voltages that are applied to the specified analog output channels.
Chapter 10 Easy I/O for DAQ Library Parameters Input Output device short integer Assigned by configuration utility. counter string The counter to be used for the counting operation. frequency double The desired repetition rate of the continuous pulse train. dutyCycle double The desired ratio of the duration of the pulse phase (phase 2) to the period (phase 1 + phase 2). gateMode unsigned short integer Specifies how the signal on the counter's GATE pin is used.
Easy I/O for DAQ Library Chapter 10 gateMode specifies how the signal on the counter's GATE pin is used. The options are: • UNGATED_SOFTWARE_START—ignore the gate signal and start when CounterStart is called. • COUNT_WHILE_GATE_HIGH—count while the gate signal is TTL high after CounterStart is called. • COUNT_WHILE_GATE_LOW—count while the gate signal is TTL low after CounterStart is called.
Chapter 10 Easy I/O for DAQ Library Parameters Input Output device short integer Assigned by configuration utility. counter string The counter to be used for the counting operation. counterSize unsigned short integer Determines the size of the counter used to perform the operation. sourceTimebase double USE_COUNTER_SOURCE: count TTL edges at counter’s SOURCE pin; or supply a valid internal timebase frequency to count the TTL edges of an internal clock.
Easy I/O for DAQ Library • Chapter 10 If you use TWO_COUNTERS, counter+1 is cascaded with the specified counter. Counter+1 is defined as shown in Table 10-3. Table 10-3. Definition of Am 9513: Counter +1 counter counter+1 1 2 2 3 3 4 4 5 5 1 6 7 7 8 8 9 9 10 10 6 sourceTimebase determines whether the counter uses its SOURCE pin or an internal timebase as its signal source.
Chapter 10 Easy I/O for DAQ Library sourceEdge is the edge of the counter source or timebase signal on which it increments, and this parameter accepts the following attributes: • COUNT_ON_RISING_EDGE • COUNT_ON_FALLING_EDGE gateMode specifies how the signal on the counter's GATE pin is used. The options are: • UNGATED_SOFTWARE_START—ignore the gate signal and start when CounterStart is called. • COUNT_WHILE_GATE_HIGH—count while the gate signal is TTL high after CounterStart is called.
Easy I/O for DAQ Library Chapter 10 Table 10-4. Adjacent Counters Am9513 counter-1 counter counter+1 5 1 2 1 2 3 2 3 4 3 4 5 4 5 1 10 6 7 6 7 8 7 8 9 8 9 10 9 10 6 counter-1 counter counter+1 1 0 1 0 1 0 DAQ-STC This function is useful for relatively high frequency signals when many cycles of the signal occur during the timing period. Use the PulseWidthOrPeriodMeasConfig function for relatively low frequency signals.
Chapter 10 Easy I/O for DAQ Library Parameters Input Output device short integer Assigned by configuration utility. counter string The counter to be used for the counting operation. counterSize unsigned short integer Determines the size of the counter used to perform the operation: ONE_COUNTER or TWO_COUNTERS. gateWidthSampleTimeinSec double The desired length of the pulse used to gate the signal. The lower the signal frequency, the longer the Gate Width must be.
Easy I/O for DAQ Library Chapter 10 Return Value short integer error Refer to error codes in Table 10-5. Parameter Discussion counter is the counter to be used for the counting operation. The valid counters are shown in Table 10-2, which is found in the Valid Counters for the Counter/Timer Functions subsection of the Easy I/O for DAQ Library Function Overview section of this chapter. counterSize determines the size of the counter used to perform the operation.
Chapter 10 Easy I/O for DAQ Library Parameters Input taskID unsigned long integer The reference number assigned to the counting operation by one of the counter configuration functions. Output overflow short integer 1 = counter rolled past terminal count; 0 = counter did not roll past terminal count. count long integer The value of the counter at the time it is read. short integer Refer to error codes in Table 10-5.
Easy I/O for DAQ Library Chapter 10 CounterStop short error = CounterStop (unsigned long taskID); Purpose Stops a count operation immediately. Parameters Input taskID unsigned long integer The reference number assigned to the counting operation by one of the counter configuration functions. Return Value error short integer Refer to error codes in Table 10-5.
Chapter 10 Easy I/O for DAQ Library Parameters Input Output device short integer Assigned by configuration utility. counter string The counter to be used for the counting operation. pulseDelay double The desired duration of the delay (phase 1) before the pulse. pulseWidth double The desired duration of the pulse (phase 2) after the delay. timebaseSource unsigned short integer The signal that causes the counter to count.
Easy I/O for DAQ Library Chapter 10 • pulseWidth is the desired duration of the pulse (phase 2) after the delay • The unit is seconds if timebaseSource is USE_INTERNAL_TIMEBASE and cycles if timebaseSource is USE_COUNTER_SOURCE. • If pulseDelay = 0.0 and timebaseSource is internal, the function selects a minimum delay of three cycles of the timebase used. timebaseSource is the signal that causes the counter to count.
Chapter 10 Easy I/O for DAQ Library FrequencyDividerConfig short error = FrequencyDividerConfig (short device, char counter[], double sourceTimebase, double timebaseDivisor, unsigned short gateMode, unsigned short outputBehavior, short sourceEdge, unsigned long *taskID); Purpose This function configures the specified counter to count the number of signal transitions on its SOURCE pin or on an internal timebase signal, and to strobe or toggle the signal on its OUT pin.
Easy I/O for DAQ Library Chapter 10 Parameters Input Output device short integer Assigned by configuration utility. counter string The counter to be used for the counting operation. sourceTimebase double USE_COUNTER_SOURCE: count TTL edges at counter’s SOURCE pin; or supply a valid internal timebase frequency to count the TTL edges of an internal clock. timebaseDivisor double The source frequency divisor.
Chapter 10 Easy I/O for DAQ Library timebaseDivisor is the source frequency divisor. For example, if the source signal is 1000 Hz, the timebaseDivisor is 10, and the output is pulsed, the frequency of the counter's OUT signal is 100 Hz. If the output is toggled, the frequency is 50 Hz. gateMode specifies how the signal on the counter's GATE pin is used. This parameter accepts the following attributes: • UNGATED_SOFTWARE_START—ignore the gate signal and start when CounterStart is called.
Easy I/O for DAQ Library Chapter 10 GetAILimitsOfChannel short error = GetAILimitsOfChannel (short device, char channelString[], char singleChannel[], double initialHighLimitVolts, double initialLowLimitVolts, double *highLimitVolts, double *lowLimitVolts); Purpose Returns the high and low limits for a particular channel in the channel string. Parameters Input Output device short integer Assigned by configuration utility. channelString string Analog input channels that are to be sampled.
Chapter 10 Easy I/O for DAQ Library initialHighLimitVolts specifies the maximum voltage that is measured for all channels in the channel string listed before a command string that specifies a new high limit. For the following channel string: "0,1; cmd hi 10.0 low -10.0; 2,3" If initialHighLimitVolts is 5.0, channels "0" and "1" have a high limit of 5.0 and channels "2" and "3" have a high limit of 10.0.
Easy I/O for DAQ Library Chapter 10 Parameters Input Output device short integer Assigned by configuration utility. channelString string The analog channel string. channelSubString string A sub-string of the channelString. channelType short integer Specifies whether the channelString is ANALOG_INPUT or ANALOG_OUTPUT. channelIndices long integer array Returns the indices of the channels in the channelSubString. Return Value error short integer Refer to error codes in Table 10-5.
Chapter 10 Easy I/O for DAQ Library Parameters Input Output device short integer Assigned by configuration utility. channelString string Analog input channels that are to be sampled. index long integer The index of a particular channel in the channelString. channelType short integer Specifies whether the channelString is ANALOG_INPUT or ANALOG_OUTPUT. channelName string Returns the name of the particular channel in the channelString indicated by index.
Easy I/O for DAQ Library Chapter 10 GetNumChannels short error = GetNumChannels (short device, char channelString[], short channelType, unsigned long *numberOfChannels); Purpose Determines the number of channels contained in the channelString. You need to know the number of channels in the channelString so that you can interpret (for analog input) or build (for analog output) waveform arrays correctly. Parameters Input Output device short integer Assigned by configuration utility.
Chapter 10 Easy I/O for DAQ Library If you acquire data in "grouped by scan" mode, you need to reorder the array into "grouped by channel" mode before it can be passed to graph plotting functions, analysis functions, and others. See the description of the fillMode parameter of AIAcquireWaveforms for an explanation of "grouped by scan" versus "grouped by channel". Parameters Input/ array Output double array Pass in the “grouped by scan” array and it is grouped by channel in place.
Easy I/O for DAQ Library Chapter 10 Parameters Input Output device short integer Assigned by configuration utility. counter short integer The counter to be controlled (valid counters are 0 through 2). controlCode short integer Determines the counter's operating mode. count unsigned short integer The period between output pulses.
Chapter 10 Easy I/O for DAQ Library • 5: I_HARDWARE_TRIGGERED_STROBE—similar to mode 4, except that a rising edge at the gate input triggers the count to start. • 6: I_READ—read the counter and return the value in the readValue parameter. • 7: I_RESET—resets the counter and sets its output to outputState. count is the period between output pulses.
Easy I/O for DAQ Library Chapter 10 PulseWidthOrPeriodMeasConfig short error = PulseWidthOrPeriodMeasConfig (short device, char counter[], unsigned short typeOfMeasurement, double sourceTimebase, unsigned long *taskID); Purpose Configures the specified counter to measure the pulse width or period of a TTL signal connected to its GATE pin. The measurement is done by counting the number of cycles of the specified timebase between the appropriate starting and ending events.
Chapter 10 Easy I/O for DAQ Library Parameter Discussion typeOfMeasurement identifies the type of pulse width or period measurement to make. This parameter accepts the following attributes: • MEASURE_HIGH_PULSE_WIDTH—measure high pulse width from rising to falling edge. • MEASURE_LOW_PULSE_WIDTH—measure low pulse width from falling to rising edge. • MEASURE_PERIOD_BTW_RISING_EDGES—measure period between adjacent rising edges.
Easy I/O for DAQ Library Chapter 10 Parameters Input Output device short integer Assigned by configuration utility. portNumber string Specifies the digital port this function configures. line short integer Specifies the individual bit or line within the port to be used for I/O (zero-based). portWidth short integer The total width in bits of the port. For example, you can combine two 4-bit ports into an 8-bit port on an MIO (non E-Series) board by setting portWidth to 8.
Chapter 10 • Easy I/O for DAQ Library The portWidth for the 8255-based digital I/O ports (including all digital ports on Lab boards, SCXI-1200, DAQPad-1200, DAQCard-1200, DIO-24, DIO-32F, DIO-96, and AT-MIO-16DE-10/AT-MIO-16D ports 2, 3 and 4) should be at least 8. configure specifies whether to configure the digital port before reading. • When this function is called in a loop, it can be optimized by only configuring the digital port on the first iteration.
Easy I/O for DAQ Library Chapter 10 Return Value error short integer Refer to error codes in Table 10-5. Parameter Discussion portNumber specifies the digital port this function configures. A portNumber value of 0 signifies port 0, a portNumber of 1 signifies port 1, and so on. If you use an SCXI-1160, SCXI-1161, SCXI-1162, or SCXI-1163 module, use the "SCx!MDy!0" syntax, where x is the chassis ID and y is the module device number, to specify the port on a module.
Chapter 10 Easy I/O for DAQ Library SetEasyIOMultitaskingMode void SetEasyIOMultitaskingMode (int multitaskingMode); Purpose By default, if you call the non-timed Easy I/O for DAQ functions repetitively, these functions do not reconfigure the hardware unless you change the parameters to the functions. Thus, the performance of these functions is improved by only reconfiguring the hardware when necessary.
Easy I/O for DAQ Library Chapter 10 Parameters Input device short integer Assigned by configuration utility. portNumber string Specifies the digital port this function configures. line short integer Specifies the individual bit or line within the port to be used for I/O. portWidth short integer The total width in bits of the port. For example, you can combine two 4-bit ports into an 8-bit port on an MIO (non E-Series) board by setting portWidth to 8.
Chapter 10 • Easy I/O for DAQ Library The portWidth for the 8255-based digital I/O ports (including all digital ports on Lab boards, SCXI-1200, DAQPad-1200, DAQCard-1200, DIO-24, DIO-32F, DIO-96, and AT-MIO-16DE-10/AT-MIO-16D ports 2, 3 and 4) should be at least 8. configure specifies whether to configure the digital port before writing. • When this function is called in a loop, it can be optimized by only configuring the digital port on the first iteration.
Easy I/O for DAQ Library Chapter 10 Return Value error short integer Refer to error codes in Table 10-5. Parameter Discussion portNumber specifies the digital port this function configures. A portNumber value of 0 signifies port 0, a portNumber of 1 signifies port 1, and so on. If you use an SCXI-1160, SCXI-1161, SCXI-1162, or SCXI-1163 module, use the "SCx!MDy!0" syntax, where x is the chassis ID and y is the module device number, to specify the port on a module.
Chapter 10 Easy I/O for DAQ Library Error Conditions All of the functions in the Easy I/O for DAQ Library return an error code. A negative number indicates that an error occurred. If the return value is positive, it has the same description as if it were negative, but it is considered a warning. Table 10-5. Easy I/O for DAQ Error Codes 0 Success.
Easy I/O for DAQ Library Chapter 10 Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10019 badClkFrequencyErr The frequency parameter is invalid. -10020 badTimebaseErr The timebase parameter is invalid. -10021 badLimitsErr The limits are beyond the range of the device.
Chapter 10 Easy I/O for DAQ Library Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10091 badIterationsErr The analog output buffer iterations count is invalid. It must be 0 (for indefinite iterations) or 1. -10100 badPortWidthErr The requested digital port width is not a multiple of the hardware port width. -10240 noDriverErr The driver interface could not locate or open the driver. -10241 oldDriverErr The driver is out of date.
Easy I/O for DAQ Library Chapter 10 Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10340 noConnectErr No RTSI signal/line is connected, or the specified signal and the specified line are not connected. -10341 badConnectErr The RTSI signal/line cannot be connected as specified. -10342 multConnectErr The specified RTSI signal is already being driven by a RTSI line, or the specified RTSI line is already being driven by a RTSI signal.
Chapter 10 Easy I/O for DAQ Library Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10414 reservedPinErr Selected signal indicates a pin reserved by NI-DAQ. You cannot configure this pin yourself. -10440 sysOwnedRsrcErr The specified resource is owned by the driver and cannot be accessed or modified by the user. -10441 memConfigErr No memory is configured to work with the current data transfer mode, or the configured memory does not work with the current data transfer mode.
Easy I/O for DAQ Library Chapter 10 Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10457 badDMAGroupErr DMA cannot be configured for the specified group because it is too small, too large, or misaligned. Consult the user manual for the device in question to determine group ramifications with respect to DMA. -10459 DLLInterfaceErr The DLL could not be called due to an interface error. -10460 interfaceInteractionErr You have attempted to mix LabVIEW 2.2 VIs and LabVIEW 3.0 VIs.
Chapter 10 Easy I/O for DAQ Library Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10614 badGroupDirErr The specified group does not support the specified transfer direction. -10615 masterClkErr The clock configuration for the clock master is invalid. -10616 slaveClkErr The clock configuration for the clock slave is invalid. -10617 noClkSrcErr No source signal has been assigned to the clock resource. -10618 badClkSrcErr The specified source signal cannot be assigned to the clock resource.
Easy I/O for DAQ Library Chapter 10 Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10684 badChanInputModeErr All channels of this device must have the same input range. -10685 clkExceedsBrdsMaxConvRate The clock rate selected exceeds the recommended maximum rate for this device. -10686 scanListInvalidErr A configuration change has invalidated the scan list. -10687 bufferInvalidErr A configuration change has invalidated the allocated buffer.
Chapter 10 Easy I/O for DAQ Library Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10780 sc2040InputModeErr When you have an SC2040 attached to your device, all analog input channels must be configured for differential input mode. -10800 timeOutErr The operation could not complete within the time limit. -10801 calibrationErr An error occurred during the calibration process.
Easy I/O for DAQ Library Chapter 10 Table 10-5. Easy I/O for DAQ Error Codes (Continued) -10848 noDMACountAvailErr The driver could not obtain a valid reading from the transfer-count register in the DMA controller. -10849 openFileErr Unable to open a file. -10850 closeFileErr Unable to close a file. -10851 fileSeekErr Unable to seek within a file. -10852 readFileErr Unable to read from a file. -10853 writeFileErr Unable to write to a file. -10854 miscFileErr An error occurred accessing a file.
Appendix A Customer Communication For your convenience, this appendix contains forms to help you gather the information necessary to help us solve technical problems you might have as well as a form you can use to comment on the product documentation. Filling out a copy of the Technical Support Form before contacting National Instruments helps us help you better and faster. National Instruments provides comprehensive technical assistance around the world. In the U.S.
Customer Communication Appendix A FTP Support To access our FTP site, log on to our Internet host, ftp.natinst.com, as anonymous and use your Internet address, such as joesmith@anywhere.com, as your password. The support files and documents are located in the /support directories. E-Mail Support (currently U.S. only) You can submit technical support questions to the appropriate applications engineering team through email at the Internet addresses listed below.
Technical Support Form Photocopy this form and update it each time you make changes to your software or hardware, and use the completed copy of this form as a reference for your current configuration. Completing this form accurately before contacting National Instruments for technical support helps our applications engineers answer your questions more efficiently.
Hardware and Software Configuration Form Record the settings and revisions of your hardware and software on the line to the right of each item. Complete a new copy of this form each time you revise your software or hardware configuration, and use this form as a reference for your current configuration. When you complete this form accurately before contacting National Instruments for technical support, our applications engineers can answer your questions more efficiently.
Documentation Comment Form National Instruments encourages you to comment on the documentation supplied with our products. This information helps us provide quality products to meet your needs. Title: LabWindows®/CVI Standard Libraries Reference Manual Edition Date: July 1996 Part Number: 320682C-01 Please comment on the completeness, clarity, and organization of the manual.
Glossary Prefix Meaning Value n- nano- 10 µ- micro- 10 m- milli- 10 k- kilo- 10 M- mega- 10 -9 -6 -3 3 6 Numbers/Symbols 1D One-dimensional. 2D Two-dimensional. A A Analog input. A/D Analog-to-digital. AC Alternating current. ADC A/D converter An electronic device, often an integrated circuit, that converts an analog voltage to a digital number. ADC resolution The resolution of the ADC, which is measured in bits.
Glossary in hardware, no data is transferred to system memory until the trigger condition has occurred. ANSI American National Standards Institute. AO Analog output. asynchronous (1) Hardware—A property of an event that occurs at an arbitrary time, without synchronization to a reference clock. (2) Software—A property of a function that begins an operation and returns prior to the completion or termination of the operation.
Glossary D D/A Digital-to-analog. DAC D/A converter An electronic device, often an integrated circuit, that converts a digital number into a corresponding analog voltage or current. Data acquisition (1) Collecting and measuring electrical signals from sensors, transducers, and test probes or fixtures and inputting them to a computer for processing.
Glossary G G gain The factor by which a signal is amplified, sometimes expressed in decibels. gender Refers to cable connector types. A male connector is one with protruding pins, like a lamp plug. A female connector has holes, like an outlet. gender changer A small device that can be attached to serial cable connectors or PC sockets, among others, to convert a female connector into a male, or a male connector into a female.
Glossary K KB Kilobytes of memory. kS 1,000 samples. ksamples 1,000 samples. L LSB Least significant bit. M manual scaling Where SetAxRange is called to explicitly set the maximum and minimum X and Y values. MB Megabytes of memory. MIO Multifunction I/O. ms Milliseconds. mux Multiplexer; a switching device with multiple inputs that sequentially connects each of its inputs to its output, typically at high speeds, in order to measure several signals with a single analog input channel.
Glossary pretriggering The technique used on a DAQ board to keep a continuous buffer filled with data, so that when the trigger conditions are met, the sample includes the data leading up to the trigger condition. pts Points. R resolution The smallest signal increment that can be detected by a measurement system. Resolution can be expressed in bits, in proportions, or in percent of full scale. For example, a system has 12-bit resolution, one part in 4,096 resolution, and 0.0244 percent of full scale.
Glossary T TC Terminal count. throughput rate The data, measured in bytes/s, for a given continuous operation, calculated to include software overhead. Throughput Rate = Transfer Rate - Software Overhead Factor. transfer rate The rate, measured in bytes/s, at which data is moved from source to destination after software initialization and set up operations; the maximum rate at which the hardware can operate. U unipolar A signal range that is always positive (for example, 0 to +10 V). V V Volts.
Index Numbers/Symbols 1D array functions. See one-dimensional array operation functions. 1D complex operation functions. See onedimensional complex operation functions. 2D array functions. See two-dimensional array operation functions. * (asterisks) in format specifiers formatting functions, 2-39 scanning functions, 2-48 A Abs1D function, 3-4 to 3-5 accessing physical memory. See physical memory access functions. accessing window properties. See window properties, accessing.
Index MaxMin2D, 3-24 to 3-25 Mean, 3-25 to 3-26 Mul1D, 3-26 to 3-27 Mul2D, 3-27 Neg1D, 3-28 Set1D, 3-28 Sort, 3-29 StdDev, 3-29 to 3-30 Sub1D, 3-30 to 3-31 Sub2D, 3-31 Subset1D, 3-32 ToPolar, 3-32 to 3-33 ToPolar1D, 3-33 to 3-34 ToRect, 3-34 to 3-35 ToRect1D, 3-35 Transpose, 3-36 overview, 3-1 reporting analysis errors, 3-4 ANSI C Library C locale, 1-2 to 1-5 information values (table), 1-3 LC_COLLATE, 1-5 LC_CTYPE, 1-4 to 1-5 LC_MONETARY, 1-4 LC_NUMERIC, 1-4 LC_TIME, 1-5 character processing, 1-5 classes
Index B Beep function, 8-5 board control functions, GPIB, 4-7 board control functions, GPIB Library, 4-3 break on library error functions DisableBreakOnLibraryErrors, 8-11 to 8-12 EnableBreakOnLibraryErrors, 8-15 GetBreakOnLibraryErrors, 8-17 GetBreakOnProtectionErrors, 8-18 SetBreakOnLibraryErrors, 8-63 to 8-64 SetBreakOnProtectionErrors, 8-64 to 8-65 Breakpoint function, 8-6 BroadcastDDEDataReady function, 6-8 to 6-9 bus control functions, GPIB Library, 4-3 byte count variable (ibcntl), 4-6 C C locale,
Index CxRecip, 3-13 to 3-14 CxSub, 3-14 CxSub1D, 3-15 ToPolar, 3-32 to 3-33 ToPolar1D, 3-33 to 3-34 ToRect, 3-34 to 3-35 ToRect1D, 3-35 ComRd function, 5-11 ComRdByte function, 5-12 ComRdTerm function, 5-12 to 5-13 ComSetEscape function, 5-14 to 5-15 ComToFile function, 5-3, 5-15 to 5-16 ComWrt function, 5-16 to 5-17 ComWrtByte function, 5-17 to 5-18 configuration functions, GPIB Library, 4-2 ConnectToDDEServer function, 6-2, 6-13 to 6-15 ConnectToTCPServer function, 7-5 to 7-7 ConnectToXDisplay function,
Index DateStr, 8-9 GetSystemDate, 8-38 GetSystemTime, 8-39 SetSystemDate, 8-76 SetSystemTime, 8-77 TimeStr, 8-83 DCE device, 5-5 DDE Library functions callback function, 6-2 to 6-4 functions capable of trigger callback function (table), 6-4 parameter prototypes (table), 6-3 clients and servers, 6-2 connecting to DDE server, 6-2 DDE data links, 6-4 error conditions, 6-23 to 6-24 function reference AdviseDDEDataReady, 6-6 to 6-8 BroadcastDDEDataReady, 6-8 to 6-9 ClientDDEExecute, 6-10 ClientDDERead, 6-10 to
Index DisconnectTCPClient function, 7-7 Div1D function, 3-16 to 3-17 Div2D function, 3-17 to 3-18 documentation conventions used in manual, xix LabWindows/CVI documentation set, xx organization of manual, xvii-xviii related documentation, xx DotProduct function, 3-18 DTE device, 5-5 Dynamic Data Exchange (DDE). See DDE Library functions.
Index error conditions Analysis Library functions, 3-37 DDE Library functions, 6-23 to 6-24 Easy I/O for DAQ Library, 10-57 to 10-66 RS-232 Library functions, 5-36 to 5-37 TCP Library functions, 7-12 Error control, GPIB, 4-6 Error (iberr) global variable, 4-6, 4-11 error reporting Analysis Library functions, 3-4 RS-232 Library functions, 5-3 error-related functions. See also status functions.
Index using literals, 2-40 scanning functions, 2-41 to 2-43 examples, 2-41 form of, 2-41 format codes, 2-42 to 2-43 using literals, 2-48 to 2-49 Formatting and I/O Library functions function panels classes and subclasses, 2-2 to 2-3 function tree (table), 2-2 function reference ArrayToFile, 2-4 to 2-6 CloseFile, 2-7 CompareBytes, 2-7 to 2-8 CompareStrings, 2-8 to 2-9 CopyBytes, 2-9 to 2-10 CopyString, 2-10 FileToArray, 2-11 to 2-12 FillBytes, 2-13 FindPattern, 2-13 to 2-14 Fmt, 2-14 to 2-15, 2-32 FmtFile,
Index integer modifiers (%i, %d, %x, %o, %c), 2-35 to 2-37 string modifiers (%s), 2-38 to 2-39 FrequencyDividerConfig function, 10-37 to 10-39 G gender changer, 5-6 GetAILimitsOfChannel function, 10-40 to 10-41 GetAnalysisErrorString function, 3-19 GetBreakOnLibraryErrors function, 8-17 GetBreakOnProtectionErrors function, 8-18 GetChannelIndices function, 10-41 to 10-42 GetChannelNameFromIndex function, 10-42 to 10-43 GetComStat function, 5-19 to 5-20 GetCurrentPlatform function, 8-19 GetCVIVersion functi
Index hardware interrupts and autopolling, 4-8 to 4-9 overview, 4-1 platform and board considerations, 4-10 to 4-11 read and write termination, 4-9 status and error controls, 4-6 timeouts, 4-9 Windows 95 support, 4-10 to 4-11 compatibility driver, 4-11 native 32-bit driver, 4-10 Windows NT and GPIB driver, 4-11 limitations on transfer size, 4-11 multithreading, 4-11 notification of SRQ and other GPIB events, 4-12 writing instrument modules (note), 4-7 GPIB device drivers, 4-5 to 4-6 GPIB.
Index hardware interrupts and autopolling, 4-8 to 4-9 InvMatrix function, 3-20 to 3-21 K keyboard utility functions GetKey, 8-30 to 8-31 KeyHit, 8-43 to 8-44 L LaunchExecutable function, 8-44 to 8-46 LaunchExecutableEx function, 8-47 to 8-48 launching executables. See standalone executables, launching.
Index N physical memory access functions Neg1D function, 3-28 null modem cable, 5-5 NumFmtdBytes function, 2-20 ReadFromPhysicalMemory, 8-57 ReadFromPhysicalMemoryEx, 8-58 WriteToPhysicalMemory, 8-85 to 8-86 WriteToPhysicalMemoryEx, 8-86 to 8-87 PlotLastAIWaveformsPopup function, 10-47 port I/O utility functions inp, 8-42 inpw, 8-42 to 8-43 outp, 8-56 outpw, 8-56 properties. See also X Property Library functions.
Index R read termination, GPIB, 4-9 ReadFile function, 2-22 to 2-23 ReadFromDigitalLine function, 10-49 to 10-51 ReadFromDigitalPort function, 10-51 to 10-52 ReadFromPhysicalMemory function, 8-57 ReadFromPhysicalMemoryEx function, 8-58 ReadLine function, 2-23 to 2-24 RegisterDDEServer function, 6-2, 6-16 to 6-18 RegisterTCPServer function, 7-2, 7-8 to 7-10 ReleaseExternalModule function, 8-59 remote functions, GPIB-488.
Index S scanning function programming examples ASCII file to two integers with error checking, 2-68 ASCII file with comma separated numbers to real array, with number of elements at beginning of file, 2-68 to 2-69 binary file to integer array, assuming fixed number of elements, 2-69 binary file to real array assuming fixed number of elements, 2-69 assuming variable number of elements, 2-69 to 2-70 integer array containing 1-byte integers to real array, 2-66 to 2-67 integer array to real array, 2-66 with by
Index SetStdioWindowOptions function, 8-72 to 8-74 SetStdioWindowPosition function, 8-74 to 8-75 SetStdioWindowSize function, 8-75 SetStdioWindowVisibility function, 8-76 SetSystemDate function, 8-76 SetSystemTime function, 8-77 SetUpDDEHotLink function, 6-2, 6-4, 6-20 to 6-21 SetUpDDEWarmLink function, 6-2, 6-4, 6-21 to 6-22 SetXMode function, 5-6, 5-31 software handshaking, 5-6 Sort function, 3-29 SplitPath function, 8-77 to 8-78 SRQ functions, GPIB-488.
Index synchronous callbacks, 4-12 SyncWait function, 8-79 system control functions, GPIB-488.
Index DeleteDir, 8-10 DeleteFile, 8-10 to 8-11 DisableBreakOnLibraryErrors, 8-11 to 8-12 DisableInterrupts, 8-12 DisableTaskSwitching, 8-12 to 8-15 EnableBreakOnLibraryErrors, 8-15 EnableInterrupts, 8-15 to 8-16 EnableTaskSwitching, 8-16 ExecutableHasTerminated, 8-16 to 8-17 GetBreakOnLibraryErrors, 8-17 GetBreakOnProtectionErrors, 8-18 GetCurrentPlatform, 8-19 GetCVIVersion, 8-18 to 8-19 GetDir, 8-20 GetDrive, 8-20 to 8-21 GetExternalModuleAddr, 8-21 to 8-22 GetFileAttrs, 8-23 to 8-24 GetFileDate, 8-24 to
Index TruncateRealNumber, 8-84 UnloadExternalModule, 8-84 to 8-85 WriteToPhysicalMemory, 8-85 to 8-86 WriteToPhysicalMemoryEx, 8-86 to 8-87 V va_arg() macro, 1-2 variable argument functions, LabWindows/CVI support of, 1-2 vector and matrix algebra functions Determinant, 3-16 DotProduct, 3-18 InvMatrix, 3-20 to 3-21 MatrixMul, 3-23 Transpose, 3-36 void HandlePropertyNotifyEvent function, 9-7 void_InitXPropertyLib function, 9-7 X W wait utility functions. See timer/wait utility functions.
Index PutXWindowPropertyValue, 9-29 to 9-31 RemoveXWindowProperty, 9-31 to 9-32 UninstallXPropertyCallback, 9-4, 9-33 void HandlePropertyNotifyEvent, 9-7 void_InitXPropertyLib, 9-7 function tree (table), 9-2 hidden window, 9-3 overview, 9-1 property handles and types, 9-3 to 9-4 predefined property types (table), 9-3 using outside of LabWindows/CVI, 9-7 X interclient communication, 9-2 to 9-3 XModem file transfer functions purpose and use, 5-3 XModemConfig, 5-4, 5-31 to 5-33 XModemReceive, 5-3, 5-4, 5-33 t
