Home

Using External Code in LabVIEW

1. MgErr FGetEOF fd sizep Purpose Returns the size of the specified file Parameters Name Type Description fd File File descriptor associated with the file sizep int32 Address at which FGet EOF stores the size of the file in bytes If an error occurs sizep is undefined Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr No error mgArgErr Not a valid file descriptor fIOErr Unspecified I O error Using External Code in LabVIEW 6 68 ni com FGetinfo Chapter 6 Function Descriptions MgErr FGetInfo path infop Purpose Returns information about the specified file or directory Parameters Name Type Description path Path Path of the file or directory about which you want information infop FInfoPtr Address where FGet Info stores information about the file or directory If an error occurs infop is undefined Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter FInfoPtr is a data structure that defines the attributes of a file or directory The following code lists the file directory information record FInfoPtr typedef struct National Instruments Corporation int32 int32 int32 int32 int32 uint32 uint32 type creator permissi
2. err FAddPath basepath path path the new pa th writes over the old relative path Parameters Name Type Description basePath Path Absolute path to which you want to append a relative path relPath Path Relative path you want to append to the existing base path newPath Path Path returned by FAddPath Return Value MgErr which can contain the following errors noErr mgArgErr mFullErr National Instruments Corporation No error A bad argument was passed to the function Verify the path Insufficient memory 6 47 Using External Code in LabVIEW Chapter 6 Function Descriptions FAppendName MgErr FAppendName path name Purpose Appends a file or directory name to an existing path Parameters Name Type Description path Path Base path to which you want to append a new file or directory name FAppendName returns the resulting path in this parameter name PStr File or directory name you want to append to the existing path Return Value MgErr which can contain the following errors No error A bad argument was passed to the function Verify the path noErr mgArg BIE mFull Using External Code in LabVIEW E EE Insufficient memory 6 48 ni com Chapter 6 Function Descriptions FAppPath MgErr FAppPath p Purpose Indicates the path to the LabVIEW application currently running P
3. National Instruments Corporation 6 87 Using External Code in LabVIEW Chapter 6 Function Descriptions Name Type Description openMode int32 Access mode to use in opening the file The following values are defined in the file extcode h openReadOnly Open for reading openWriteOnly Open for writing file is not truncated data is not removed In Mac OS this mode provides true write only access to files In Windows or UNIX LabVIEW I O functions are built in the C standard I O library with which you have write only access to a file only if you are truncating the file or making the access append only Therefore this mode actually allows both read and write access to files in Windows or UNIX e openReadwrite Open for both reading and writing openWriteOnlyTruncate Open for writing truncates the file denyMode int32 Mode that determines what level of concurrent access to the file is allowed The following values are defined in the file extcode h e denyReadwWrite Prevents others from reading from and writing to the file while it is open e denyWriteOnly Prevents others from writing to the file only while it 1s Open denyNeither Allows others to read from and write to the file while it is open Using External Code in LabVIEW 6 88 ni com Chapter 6 Function Descriptions Return Value MgErr which can contain the following errors noErr No error
4. National Instruments Corporation 5 13 Using External Code in LabVIEW Function Descriptions This chapter describes the CIN functions you can use with LabVIEW You can use these functions to perform simple and complex operations These functions organized into libraries called managers range from low level byte manipulation to routines for sorting data and managing memory All CIN manager routines are platform independent so you can create CINs that work on all platforms supported by LabVIEW Refer to the Manager Overview section of Chapter 4 Programming Issues for CINs for general information about the manager routines Memory Manager Functions The memory manager functions can dynamically allocate manipulate and release memory You can perform the following operations by using the functions listed e Handles and pointers verifying AZCheckHandle DSCheckHandle AZCheckPtr DSCheckPtr e Handles allocating and releasing AZCopyHandle DSCopyHandle SetCINArraySize NumericArrayResize AZDispose Handle DSDisposeHandle AZGetHandleSize DSGetHandleSize AZNewHandle DSNewHandle AZNewHClr DSNewHClr AZRecoverHandle DSRecoverHandle AZSetHandleSize DSSetHandleSize AZSetHSzClr DSSetHSzClr National Instruments Corporation 6 1 Using External Code in LabVIEW Chapter 6 Function Descriptions e Handles manipulating properties AZHLock AZHPurge AZHNoPurge
5. the resulting path If nonzero the function assumes it is a valid path resizes the path and fills in its value If NULL the function creates a new path fills in its value and stores the path at the address referred to by p Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value Using External Code in LabVIEW Err which can contain the following error No error Mg no mFullErr Err 6 116 Insufficient memory ni com Chapter 6 Function Descriptions FTextToPath MgErr FTextToPath text tlen p Purpose Creates a path from a string at the address text that represents a path in the platform specific syntax for a path Parameters Name Type Description text UPtr String that contains the path in platform specific syntax tlen int32 Number of characters in text p Path Address at which FTextToPath stores the resulting path If nonzero the function assumes it is a valid path resizes the path and fills in its value If NULL the function creates a new path fills in its value and stores the path at the address referred to by p Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following error noErr No error mFullErr Insufficient memory National Instruments Corporatio
6. Return Value MgErr which can contain the following error noErr mgArgErr Using External Code in LabVIEW No error Badly formed path or invalid type 6 114 ni com Chapter 6 Function Descriptions FStrFitsPat Bool32FStrFitsPat pat str pLen sLen Purpose Determines whether a file name str matches a pattern pat Parameters Name Type Description pat uChar Pattern string to which filename is to be compared The following characters have special meanings in the pattern is literal not treated as having a special meaning A single backslash at the end of pat is the same as two backslashes matches any one character matches zero or more characters str uChar File name string to compare to pattern pLen int32 Number of characters in pat sLen int32 Number of characters in str Return Value Boo132 which can contain the following values TRUE File name fits the pattern FALSI File name does not match the pattern Ej O National Instruments Corporation 6 115 Using External Code in LabVIEW Chapter 6 Function Descriptions FStringToPath MgErr FStringToPath text p Purpose Creates a path from an LStr The LStr contains the platform specific syntax for a path Parameters Name Type Description text LstrHandle String that contains the path in platform specific syntax p Path Address at which FstringToPath stores
7. append the data from the second string to first string MoveBlock LStrBuf strh2 LStrBuf strh1 sizel size2 update the dimension length of the first string LStrLen strh1 newSize out return err In this example CINRun is the only routine that performs substantial operations CINRun concatenates the contents of strh2 to the end of strh1 with the resulting string stored in strh1 Before performing the concatenation NumericArrayResize resizes strh1 to hold the additional data If NumericArrayResize fails it returns a non zero value of type MgErr In this example NumericArrayResize could fail if LabVIEW does not have enough memory to resize the string Returning the error code gives LabVIEW a chance to handle the error If CINRun reports an error LabVIEW aborts the calling VIs Aborting the VIs might free up enough memory so LabVIEW can continue running After resizing the string handle MoveBlock copies the second string to the end of the first string MoveBlock is a support manager routine that moves blocks of data Finally this example sets the size of the first string to the length of the concatenated string Computing the Cross Product of Two Two Dimensional Arrays In this example the CIN accepts two two dimensional arrays and computes the cross product of the arrays The CIN returns the cross product in a third parameter and a Boolean value as a fourth parameter The Boolean parameter
8. 1 Parameters Name Type Description arrayp UPtr Pointer to an array of data n int32 Number of elements in the array you want to sort elmtSize int32 Size in bytes of an array element compareProcP CompareProcPtr Comparison routine you want QSort to use to compare array elements QSort passes this routine the addresses of two elements that it needs to compare National Instruments Corporation 6 161 Using External Code in LabVIEW Chapter 6 Function Descriptions RandomGen void RandomGen xp Purpose Generates a random number between 0 and 1 and stores it at xp Parameters Name Type Description xp float64 Location to store the resulting Using External Code in LabVIEW 6 162 double precision floating point random number Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter ni com SecsToDate Chapter 6 Function Descriptions void SecsToDate secs Purpose dateRecordP Converts the seconds since January 1 1904 12 00 a m UT into a data structure containing numerical information about the date including the year 1904 through 2040 the month 1 through 12 the day of the year 1 through 366 the day of the month 1 through 31 the day of the week 1 through 7 the hour 0 through 23 the minute 0 through 59 and the second 0 through 59 and a value indicating whether
9. AZHUnlock e Memory utilities ClearMem MoveBlock SwapBlock e Memory zone utilities AZHeapCheck DSHeapCheck AZMaxMem DSMaxMem AZMemStats DSMemStats e Pointers allocating and releasing AZDisposePtr DSDisposePtr AZNewPClr DSNewPClr AZNewPtr DSNewPtr File Manager Functions The file manager functions can create open and close files write data to files and read data from files In addition file manager routines can create directories determine characteristics of files and directories and copy files The file manager defines the Path data type for use in describing paths to files and directories The data structure for the Path data type is private Use file manager routines to create and manipulate the Path data type Permissions for Files and Directories Using External Code in LabVIEW The file manager uses the int 32 data type to describe permissions for files and directories The manager uses only the least significant nine bits of the int32 UNIX The nine bits of permissions correspond exactly to nine UNIX permission bits governing read write and execute permissions for user group and others Figure 6 1 shows permission bits in UNIX 6 2 ni com Chapter 6 Function Descriptions User Group Others Permission rwxrwxrwx Bit 31 876543210 r Read Permission w Write Permission x Execute Permission Figure 6 1 Permission Bits
10. Changes the size of the block of memory referenced by the specified handle and sets any new memory to zero Do not use this function on a locked handle Parameters Name Type Description h UHandle Handle you want to resize size int32 New size in bytes of the handle Return Value MgErr which can contain the following errors No error Not enough memory to perform the operation noErr mFull Err mZonel O National Instruments Corporation Err Handle or pointer not in specified zone 6 31 Using External Code in LabVIEW Chapter 6 Function Descriptions BinSearch int32 BinSearch arrayp Purpose n elmtSize compareProcP Searches an array of an arbitrary data type using the binary search algorithm In addition to passing the array you want to search to this routine you also pass a comparison procedure that this sort routine then uses to compare elements in the array The comparison routine should return a number less than zero if a is less than b zero if a is equal to b and a number greater than zero if a is greater than b You should declare the comparison routine to have the following parameters and return type int32 compareProcP UPtr a UPtr b Parameters Name Type Description arrayp UPtr Pointer to an array of data n int32 Number of elements in the array you want to search elmtSize int32 Size in bytes of an array element k
11. Creates a new pointer to a non relocatable block of memory of the specified size and initializes the memory to zero Parameters Name Type Description size int32 create Size in bytes of the pointer you want to Return Value A pointer to a block of size bytes filled with zeros If an error occurs this function returns NULL National Instruments Corporation 6 27 Using External Code in LabVIEW Chapter 6 Function Descriptions AZNewPtr DSNewPtr UPtr AZNewPtr size UPtr DSNewPtr size Purpose Creates a new pointer to a non relocatable block of memory of the specified size Parameters Name Type Description size int32 Size in bytes of the pointer you want to create Return Value A pointer to a block of size bytes If an error occurs this function returns NULL Using External Code in LabVIEW 6 28 ni com AZRecoverHandle DSRecoverHandle Chapter 6 Function Descriptions UHandle AZRecoverHandle p UHandle DSRecoverHandle p Purpose Given a pointer to a block of memory that was originally declared as a handle this function returns a handle to the block of memory This function is useful when you have the address of a block of memory that you know is a handle and you need to get a true handle to the block of memory Parameters Name Type Description p UPtr Pointer to a relocatable block of mem
12. The heap is corrupt ni com AZHLock Chapter 6 Function Descriptions MgErr AZHLock h Purpose Locks the memory referenced by the application zone handle h so the memory cannot move This means the memory manager cannot move the block of memory to which the handle refers Do not lock handles more than necessary Locking handles interferes with efficient memory management Also do not enlarge a locked handle Parameters Name Type Description h Return Value UHandle Application zone handle you want to lock MgErr which can contain the following errors noErr mZoneErr National Instruments Corporation No error Handle or pointer not in specified zone Using External Code in LabVIEW Chapter 6 Function Descriptions AZHNoPurge void AZHNoPurge h Purpose Marks the memory referenced by the application zone handle h as not purgative Parameters Name Type Description h UHandle Application zone handle you want to mark as not purgative Using External Code in LabVIEW 6 20 ni com AZHPurge Chapter 6 Function Descriptions void AZHPurge h Purpose Marks the memory referenced by the application zone handle h as purgative This means that in tight memory conditions the memory manager can perform an AZEmptyHandle on h Use AZReallocHandle to reuse a handle if the manager purges it If you mark a handle as purga
13. e Task 1 Build the Function Prototype in LabVIEW e Task 2 Complete the c File e Task3 Build a Library Project in an External IDE Using External Code in LabVIEW 2 8 ni com Chapter 2 Shared Libraries DLLs This section uses a simple shared library example to describe the three basic tasks for building external code libraries to call from LabVIEW In the Example 1 Call a Shared Library that You Built section you call the shared library that you build here Task 1 Build the Function Prototype in LabVIEW To build a function prototype for your shared library you must build a prototype in LabVIEW and then fill in all the details of your code When you allow LabVIEW to generate this C source code you help ensure that the basic syntax of the code in your shared library is valid The prototype source file you create is a c file and contains C declarations for the parameters you want to pass Complete the following steps to build your prototype source file myshared c 1 Create a new VI named Array Average 2 Place a Call Library Function Node on the block diagram 3 Right click the Call Library Function Node icon and select Configure from the shortcut menu to open the Call Library Function dialog box 4 Leave the Library Name or Path field empty 3 Note Use the Library Name or Path field to specify the shared library the Call Library Function Node calls For this example you provide the file path in the Example 1 Call
14. int8 HiByte x Purpose Returns the high order int8 of an int16 Parameters Name Type Description x int16 int16 for which you want to determine the high ints National Instruments Corporation 6 123 Using External Code in LabVIEW Chapter 6 Function Descriptions HiNibble Macro uInt8 HiNibble x Purpose Returns the value stored in the high four bits of an uInt8 Parameters Name Type Description x uInt8 uInt8 whose high four bits you want to extract Using External Code in LabVIEW 6 124 ni com IsAlpha Chapter 6 Function Descriptions Bool32 IsAlpha c Purpose Returns TRUE if the character e is a lowercase or uppercase letter that is in the set a to z or Ato Z In SPARCstation this function also returns TRUE for international characters such as a a A and so on Parameters Name Type Description uChar Character you want to analyze Return Value Boo132 which can contain the following values The character is alphabetic TRUE FALSE National Instruments Corporation Otherwise 6 125 Using External Code in LabVIEW Chapter 6 Function Descriptions IsDigit Bool32 IsDigit c Purpose Returns TRUE if the character c is between 0 and 9 Parameters Name Type Description c uChar Character you want to analyze Return Value Boo132 which ca
15. new string Parameters Name Type Description sih CPStrHandle Handle to a concatenated list of Pascal strings s2 PStr Pointer to a Pascal string index int32 Position you want the new Pascal string to have in the list of Pascal strings with 0 as the first string Return Value MgErr which can contain the following error noErr mFullErr National Instruments Corporation No error Insufficient memory 6 39 Using External Code in LabVIEW Chapter 6 Function Descriptions CPStrLen Macro int32 CPStrLen sp Purpose Returns the number of Pascal strings in a concatenated list of Pascal strings that is sp gt cnt Use the CPStrsize function to get the total number of characters in the list Parameters Name Type Description sp CPStrPtr Pointer to a concatenated list of Pascal strings Return Value The number of strings in the concatenated list of Pascal strings Using External Code in LabVIEW 6 40 ni com CPStrRemove Chapter 6 Function Descriptions void CPStrRemove sih Purpose index Removes a Pascal string from a list of Pascal strings If index is greater than or equal to the number of strings in the list this function removes the last string The function resizes the list after removing the string Parameters Name Type Description sih CPStrHandle Handle to a concatenated list of Pascal strings i
16. The following conventions appear in this manual The symbol leads you through nested menu items and dialog box options to a final action The sequence File Page Setup Options directs you to pull down the File menu select the Page Setup item and select Options from the last dialog box This icon denotes a tip which alerts you to advisory information This icon denotes a note which alerts you to important information This icon denotes a caution which advises you of precautions to take to avoid injury data loss or a system crash Bold text denotes items that you must select or click in the software such as menu items and dialog box options Bold text also denotes parameter names Italic text denotes variables emphasis a cross reference or an introduction to a key concept This font also denotes text that is a placeholder for a word or value that you must supply Text in this font denotes text or characters that you should enter from the keyboard sections of code programming examples and syntax examples This font is also used for the proper names of disk drives paths directories programs subprograms subroutines device names functions operations variables filenames and extensions and code excerpts Bold text in this font denotes the messages and responses that the computer automatically prints to the screen This font also emphasizes lines of code that are different from the other examples National Instr
17. Your library call can fail when your external code uses identifiers in place of constants Many APIs define identifiers for constants to make the code easier to read LabVIEW must receive the actual value of the constant rather than the identifier that a particular API uses Constants are usually numeric but they might also be strings or other values To identify all constants inspect the header file for the API to find the definitions The definition might either be in define statements or in enumerations which use the enum keyword The Constants section presents an example of this identification process Calling Conventions Your library call can fail when certain operating systems use calling conventions other than the C calling convention and the Standard __stdcal11 calling convention The calling convention defines how data is passed to a function and how clean up occurs after the function call is National Instruments Corporation 2 19 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs complete The documentation for the API should say which calling convention s you must use The Standard __stdca11 calling convention is also known as the WINAPI convention or the Pascal convention Use of calling conventions other than the C or Standard calling conventions frequently causes the failure of library calls in LabVIEW because those other calling conventions use an incompatible method for maintaining the stack E
18. creates the makefile 3 14 ni com Chapter 3 CINs You then can use the MPW make tool to build your CIN as shown in the following commands make f myCIN ppc make gt myCIN makeout creates the build commands myCIN makeout executes the build commands Load the 1sb file that this application creates into your LabVIEW CIN Microsoft Windows To build CINs for LabVIEW for Windows use the Microsoft Visual C or Symantec C compilers Visual C IDE Complete the following steps to build CINs using the Visual C integrated development environment IDE 1 Select File New to create a new DLL project 2 Select Win32 Dynamic Link Library as the project type You can name your project whatever you want 3 Select An empty DLL project when prompted to choose the type of DLL that you want to create and click Finish 4 Select Project Add To Project Files and navigate to your c file Select your c file and click the Open button to add the c file to the project 5 Select Project Add To Project Files to add CIN objects and libraries to the project Select cin obj labview lib lvsb 1ib and lvsbmain def from the Cintools subdirectory You need these files to build a CIN 6 Select Project Settings and change Settings For to All Configurations Click the C C tab and set the category to Preprocessor Add the path to your Cintools directory in the Additional include directories field 7 Select Project Se
19. gt dimSizes 0 error LVTRUE goto out error LVFALSE rows A gt dimSizes 0 number of rows in cols B gt dimSizes 1 number of cols in A and result B and result newNumElmts rows cols if err SetCINArraySize UHandle AxB ParamNumber newNumElmts goto out AxB gt dimSizes 0 rows AxB gt dimSizes 1 cols aElmtp A gt argl bElmtp B gt argl resultElmtp AxB gt argl for i 0 i lt rows i for j 0 j lt cols j resultElmtp 0 for 1 0 1 lt k 1 resultElmtp a bl Elmtp Elmtp result QUE return err National Instruments Corporation Elmtp i k 1 1 cols j f 4 13 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs In this example CINRun is the only routine performing substantial operations CINRun cross multiplies the two dimensional arrays A and B LabVIEW stores the resulting array in resulth If the number of columns in A is not equal to the number of rows in B CINRun sets error to LVTRUE to inform the calling diagram of invalid data SetCINArraySize the LabVIEW routine that accounts for alignment and padding requirements resizes the array The two dimensional array data structure is the same as the one dimensional array data structure except the 2D array has two dimension fields instead of one The two dimensions indicate the number of
20. Builder development environment from Apple Computer Inc It is possible to build a CIN with Metrowerks CodeWarrior but LabVIEW does not provide a template or instructions Project Builder To set up a CIN project for Mac OS X you must first install the CIN template into Project Builder Install the CIN template into Project Builder by dragging the LabVIEW Templates folder from the LabVIEW cintools Project Builder Files directory into the Project Templates folder in the Developer ProjectBuilder Extras directory National Instruments Corporation 3 9 Using External Code in LabVIEW Chapter 3 CINs Using External Code in LabVIEW Complete the following steps to create a new CIN project 1 Open Project Builder and select File New Project 2 Select LabVIEW Templates CIN and specify a name and location for the project 3 Add source code by selecting Project Add Files 4 Builda 1sb file LabVIEW places the 1sb file next to the project file The LabVIEW CIN template specifies the location of the cintools directory in the LabVIEW directory Project Builder assumes that you installed LabVIEW in the Applications directory Complete the following steps if Lab VIEW is not installed in the Applications directory 1 Select Target Settings Expert View and change the LABVIEW_PATH variable to the path to the LabVIEW directory 2 Select Target Settings Search Path and change the Libraries Search Path so it specifies the cinto
21. Declared in winuser h The header file named in the preceding statement usually declares the constants Searching through that header file you should be able to find a define statement or an enumeration that assigns the constant text a value winuser h defines values for some of the MessageBox constants as follows define MB_OK 0x00000000L define MB _ABORTRETRYIGNORE 0x00000002L define MB _ICONWARNING MB_ICONEXCLAMATION Thus MB_OK has the decimal value 0 MB_ABORTRETRYIGNORE has the decimal value 2 MB_TCONWARNING is defined as MB_TCONEXCLAMATION Elsewhere in winuser h you find the following statement defining MB_ICONEXCLAMATION define MB_ICONEXCLAMATION 0x00000030L A hexadecimal value of 30 translates to a decimal value of 48 e Tips Keep in mind that constants in the SDK often are used in bitfields A bitfield is usually a single integer in which each bit controls a certain property The uType parameter in MessageBox is an example of a bitfield Often you can combine multiple constants in order to set multiple properties through one parameter In order to combine these constants you use a bit wise OR operation For example to set the MessageBox to have a warning icon and the buttons Abort Retry and Ignore you pass the following value of uType to MessageBox MB_ABORTRETRYIGNORE MB_ICONEXCLAMATION 0x32 In LabVIEW you combine multiple constants by wiring integer types to the OR operator
22. Megabytes of memory Macintosh Programmer s Workshop Most significant bit Compiled version of source code Object code is not standalone because you must load it into LabVIEW to run it G 2 ni com P Pascal string PStr portable private data structures R RAM reentrant execution relocatable S sink terminal shortcut menu source code source terminal T type descriptor U UT O National Instruments Corporation Glossary A series of unsigned characters with the value of the first character indicating the length of the string Used in the Pascal programming language Able to compile on any platform that supports LabVIEW Data structures whose exact format is not described usually subject to change Random Access Memory Mode in which calls to multiple instances of a subVI can execute in parallel with distinct and separate data storage Able to be moved by the memory manager to a new memory location Terminal that absorbs data Also called a destination terminal Menu that you access by right clicking an object Menu items pertain to that object specifically Original uncompiled text code Terminal that emits data See data type descriptor Universal Time G 3 Using External Code in LabVIEW
23. Refer to the Solaris 2 x and Linux subsections of the Step 4 Compile the CIN Source Code section of this chapter for information about creating a CIN on Solaris and Linux Resolving Multithreading Issues Using External Code in LabVIEW You must resolve the following issues to make multithreaded CINs e Make LabVIEW recognize your CIN as being multithreaded e Use C code that is completely multithread safe 3 2 ni com Chapter 3 CINs Making LabVIEW Recognize a CIN as Thread Safe The CIN node on the block diagram is orange if you have not set the node to be thread safe A thread safe node is yellow Complete the following steps to make LabVIEW recognize a CIN node as thread safe 1 Add the CINProperties function to your CIN code in the prototypes section of your c source file as shown in the following example code CIN MgErr CINProperties int32 prop void data 2 Add the following function statement to the functions section of your c source file CIN MgErr CINProperties int32 prop void data switch prop case kCINIsReentrant Bool32 data TRUE return noErr return mgNotSupported Using C Code that is Thread Safe The CINProperties function only labels your CIN as being safe to run from multiple threads Whether the CIN is actually thread safe depends entirely upon what C code has been written For information about what makes C code safe or unsafe to be run from multiple threads
24. dsGlobalStruct dsGlobals MgErr err noErr if dsGlobals dsGlobalStruct DSNewHandle sizeof dsGlobalStruct if 0 ran out of memory err mFullErr goto out dsGlobals gt numElements 0 dsGlobals gt total 0 SetDSStorage int32 dsGlobals out return err CIN MgErr CINDispose dsGlobalStruct dsGlobals dsGlobals dsGlobalStruct GetDSStorage if dsGlobals DSDisposeHandle dsGlobals return noErr CIN MgErr CINRun float64 new_num float64 avg CIN MgErr CINRun float64 new_num float64 avg dsGlobalStruct dsGlobals dsGlobals dsGlobalStruct GetDSStorage Using External Code in LabVIEW 5 12 ni com Chapter 5 Advanced Applications if dsGlobals dsGlobals gt total new_num dsGlobals gt numElements avg dsGlobals gt total dsGlobals gt numElements return noErr A handle for the global data is allocated in CINInit and stored in the CIN data space storage using SetDSStorage When LabVIEW calls the CINInit CINDispose CINAbort or CINRun routines it makes sure GetDSStorage and SetDSStorage return the 4 byte CIN data space value for that node or CIN data space When you want to access the data in the CIN data space use Get DSStorage to retrieve the handle and then dereference the appropriate fields Finally use the CINDispose routine you need to dispose of the handle
25. for a description of the CPStr data type If typeH is not NULL the function fills the AZ handle passed in typeH with the file type information for each file name or directory name stored in list Parameters Name Type Description path Path Path of the directory whose contents you want to determine list CPStrHandle Application zone handle in which FListDir stores a series of concatenated Pascal strings preceded by a 4 byte integer field ent that indicates the number of items in the buffer typeH FileType Application zone handle in which FListDir stores a series of FileType records If typeH is not NULL FListDir stores one FileType record in typeH for each Pascal string in list The n FileType in typeH denotes the file type information about the file or directory named in the n string in list The following code shows the file type record typedef struct int32 flags int32 type FileType Only the least significant four bits of lags contain useful information The remaining bits are reserved for use by LabVIEW You can test these four bits using the following four masks define kIsFile 0x01 define kRecognizedType 0x02 National Instruments Corporation 6 81 Using External Code in LabVIEW Chapter 6 Function Descriptions define kIsLink 0x04 define kFIsInvisible 0x08 The kIsFile bit is set if the item described by the file type record is a file Otherwise kIsFile is clear The
26. int32 newNumElements size clusterTableh gt dimSize tmpp clusterTableh gt argl positionp 1 presentp LVFALSE for i 0 i lt size i if tmpp gt number elementp gt number if LStrCmp tmpp gt string elementp gt string 0 break tmpp if i lt size positionp i presentp LVTRU goto out E Using External Code in LabVIEW 4 16 ni com Chapter 4 Programming Issues for CINs DSCopyHandle will allocate a new handle since this is NULL newStringh NULL if err DSCopyHandle amp newStringh elementp gt string goto out newNumElements size 1 if err SetCINArraySize UHandle clusterTableh ParamNumber newNumElements DSDisposeHandle newStringh goto out clusterTableh gt dimSize size 1 newElementp clusterTableh gt argl size newElementp gt number elementp gt number newElementp gt string newStringh positionp size out return err In this example CINRun is the only routine performing substantial operations CINRun first searches through the table to see if the single cluster is present CINRun then compares string components using the LabVIEW routine LStrCmp If CINRun finds the single cluster the routine returns the position the single cluster occupies in the array of clusters If the routine does not find the single cluster in the array of clusters the CIN adds a new element to the array o
27. Call Library Function dialog box to specify the library function parameters return value for the object and calling conventions in Windows When you click OK in the Call Library Function dialog box LabVIEW updates the Call Library Function Node according to your settings displaying the correct number of terminals and setting the terminals to the correct data types O National Instruments Corporation 2 1 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Call Library Function gt Run in UI Thread femme o o oid FuncName void Figure 2 1 Call Library Function Dialog Box As you configure parameters the Function Prototype area displays the C prototype for the function you are building This area is a read only display Configuring for Multiple Thread Operation In a multithreaded operating system you can make multiple calls to a DLL or shared library simultaneously By default all call library objects run in the user interface thread The control below the Browse button in the Call Library Function dialog box reflects your selection of Run in UI Thread or Reentrant Before you configure a Call Library Function Node to be reentrant make sure that multiple threads can call the function simultaneously The following characteristics are the basic characteristics of thread safe code in a shared library e The code is thread safe when it does not store any global data s
28. Numeric section of this chapter for information about numeric data types Specify the dimensions of the array in Dimensions National Instruments Corporation 2 5 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Use the Array Format pull down menu to make one of the following choices e Array Data Pointer passes a one dimensional pointer to the array data Array Handle passes a pointer to a pointer that points to a four byte value for each dimension followed by the data Array Handle Pointer passes a pointer to an array handle J Caution Do not attempt to resize an array with system functions such as realloc Doing so might crash your system Instead use one of the Code Interface Node CIN manager functions such as NumericArrayResize Refer to Chapter 4 Programming Issues for CINs for information about CIN manager functions String Use the String Format pull down menu to indicate the string format You can choose from the following string formats e CString Pointer a string followed by a null character e Pascal String Pointer a string preceded by a length byte String Handle a pointer to a pointer to four bytes for length information followed by string data String Handle Pointer Select a string format that the library function expects Most standard libraries expect either a C string or a Pascal string If the library function you are calling is written for LabVIEW you might want t
29. a LabVIEW string LStr indicate the length of the string The specified number of characters follow the length of the string LStr is the string data type used by LabVIEW block diagrams The following code is the type definition for a LStr string typedef struct int32 cnt number of bytes that follow uChar str 1 cnt bytes LStr LStrPtr LStrHandle Concatenated Pascal String CPStr Many algorithms require manipulation of lists of strings Arrays of strings are usually the most convenient representation for lists However arrays of strings can place a burden on the memory manager because of the large number of dynamic objects it must manage To make working with lists more efficient LabVIEW supports the concatenated Pascal string CPStr data type which is a list of Pascal style strings concatenated into a single block of memory Using the CPStr data structure you can use support manager routines to create and manipulate lists The following code is the type definition for a CPStr string typedef struct int32 cnt number of pascal strings that follow uChar str 1 Using External Code in LabVIEW 4 22 ni com Chapter 4 Programming Issues for CINs cnt concatenated pascal strings CPStr CPStrPtr CPStrHandle Paths A path pathname indicates the location of a file or directory in a file system LabVIEW has a separate data type for a path represented as Path which the file manager d
30. a debugger trap You must do this to force Visual C to load your debugging symbols The trap call must be done after the CIN is in memory The easiest way to do this is to place it in the CINLoad procedure After the debugging symbols are loaded 3 22 ni com National Instruments Corporation Chapter 3 CINs you can set normal debug points inside Visual C Windows Me 98 has a single method of setting a debugger trap while Windows 2000 NT XP can use the Windows Me 98 method or another The method common to Windows is to insert a debugger break using an in line assembly command as shown in the following code _asm int 3 Adding this to CINLoad gives you the following code CIN MgErr CINLoad RsrcFile reserved Unused reserved _asm int 3 return noErr When the debugger trap is hit Visual C invokes a debug window highlighting that line In Windows 2000 NT XP you can use the DebugBreak function The DebugBreak function exists in Windows Me 98 but does not produce suitable results for debugging CINs To use DebugBreak include lt windows h gt at the top of your file and place the call where you want to break as shown in the following example code include lt windows h gt CIN MgErr CINLoad RsrcFile reserved Unused reserved DebugBreak return noErr When that line runs you will be in assembly Step out of that function to get to the point of the DebugBreak call Rebuild
31. a global in a CIN code resource LabVIEW creates storage for only one instance of the global regardless of whether the VI is reentrant or whether you have multiple references to the same code resource in memory In some cases you might want globals for each reference to the code resource multiplied by the number of usages of the VI if the VI is reentrant For each instance of one of these globals LabVIEW allocates the CIN data space for the use of the CIN Within the CINInit CINDispose CINAbort and CINRun routines you can call the GetDSStorage routine to retrieve the value of the CIN data space for the current instance You also can call SetDSStorage to set the value of the CIN data space for this instance You can use the storage location set by SetDSStorage to store any 4 byte quantity you want to have for each instance of one of these globals If you need more than four bytes of global data store a handle or pointer to a structure containing your globals National Instruments Corporation 5 9 Using External Code in LabVIEW Chapter 5 Advanced Applications The following code examples show the exact syntax of the GetDSStorage and SetDSStorage routines defined in extcode h int32 GetDSStorage void This routine returns the value of the 4 byte quantity in the CIN data space LabVIEW allocates for each CIN code resource or for each use of the surrounding VI if the VI is reentrant Call this routine only from CINInit CINDispo
32. by value as 3d d representing horizontal vertical coordinates Q Point passed by value as hv 3d 3d representing horizontal vertical coordinates r Rectangle passed by reference as 3d 3d 3d d representing top left bottom right coordinates R Rectangle passed by reference as t1br d 3d d d representing top left bottom right coordinates s C String null terminated u Unsigned decimal integer x Hex integer Zz Path National Instruments Corporation 6 151 Using External Code in LabVIEW Chapter 6 Function Descriptions PStrBuf Macro uChar PStrBuf s Purpose Returns the address of the string data of a Pascal string that is the address following the length byte Parameters Name Type Description s PStr Pointer to a Pascal string Using External Code in LabVIEW 6 152 ni com PStrCaseCmp Chapter 6 Function Descriptions int32 PStrCaseCmp s1 Purpose s2 Lexically compares two Pascal strings to determine whether one is less than equal to or greater than the other This comparison ignores differences in case Parameters Name Type Description sl PStr Pointer to a Pascal string s2 PStr Pointer to a Pascal string Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an initial substring of s2 National Instruments Corporation 6 15
33. check for the following problems in your use of the Call Library Function Node National Instruments Corporation Make sure the path to the DLL file is correct Make sure the version of your DLL matches the version of LabVIEW for example a 16 bit DLL instead of a 32 bit LabVIEW DLL If LabVIEW gives you the error message function not found in library double check your spelling of the name of the function you want to call Remember that function names are case sensitive Also be sure that your compiler has not decorated the function Refer to the Preventing C Name Decoration section of this chapter for information about name decoration If you receive an error message that a secondary DLL cannot be found yet you properly specified the path to the primary DLL in the Call Library Function Node the primary DLL needs additional functions from one or more other DLLs You need to find the other DLLs and place them in the same directory as the DLL that needs them or in a directory that is in the search path Refer to KnowledgeBase document 1F39A18U LabVIEW Error Message A Secondary DLL Cannot Be Found at ni com for more information about finding missing DLLs 2 31 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs If your VI crashes make sure that you are passing exactly the parameters that the function in the DLL expects For example make sure that you are passing an int16 and not an int32 when the function exp
34. code written in a conventional programming language to LabVIEW They appear on the block diagram as icons with input and output terminals Linking external code to LabVIEW includes the following actions 1 You compile the source code and link it to form executable code If you already have a compiled DLL this step is not necessary 2 LabVIEW calls the executable code when the Call Library Function Node or CIN executes 3 LabVIEW passes input data from the block diagram to the executable code 4 LabVIEW returns data from the executable code to the block diagram The LabVIEW compiler can generate code fast enough for most programming tasks Call CINs and shared libraries from LabVIEW to accomplish tasks a text based language can accomplish more easily such as time critical tasks Also use CINs and shared libraries for tasks you cannot perform directly from the block diagram such as calling system 1 2 ni com Chapter 1 Introduction routines for which no corresponding LabVIEW functions exist CINs and shared libraries also can link existing code to LabVIEW although you might need to modify the code so it uses the correct LabVIEW data types CINs and shared libraries execute synchronously so LabVIEW cannot use the execution thread used by these objects for any other tasks When a VI runs LabVIEW monitors the user interface including the menus and keyboard In multithreaded applications LabVIEW uses a separate thread for user i
35. compilers of each platform extcode h defines some constants and types whose definitions might conflict with the definitions of system header files The cintools directory also contains hosttype h which resolves the differences between definitions in extcode h and definitions in system header files hosttype h also includes many of the common header files for a given platform 3 Note Always use include extcode h at the beginning of your source code If your code needs to make system calls also use include hosttype h immediately after include extcode h and then include your system header files hosttype h includes only a subset of the h files for a given operating system If the h file you need O National Instruments Corporation 4 1 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs is not included in hosttype h you can include it in the c file for your CIN after you include hosttype h If you write a CIN that accepts a single 32 bit signed integer the c file indicates the CINRun routine is passed as int 32 by reference extcode h defines an int32 to the appropriate data type for the LabVIEW supported compiler you use Therefore you can use the int32 data type in external code you write Passing Fixed Size Data to CINs As described in the Creating a CIN section of Chapter 3 CINs you can designate terminals on the CIN as either input output or output only Regardless of the designation LabVIEW pass
36. continue running correctly Examples with Scalars The following examples describe how to create CINs that work with scalar data types Refer to Chapter 3 CINs for more information about creating CINs Creating a CIN That Multiplies Two Numbers Complete the following steps to create a CIN that takes two single precision floating point numbers and returns their product 1 Place the CIN on the block diagram 2 Add two input and output terminals to the CIN 3 Place two single precision numeric controls and one single precision numeric indicator on the front panel Wire the node as shown in Figure 4 1 A B is wired to an output only terminal pair National Instruments Corporation 4 3 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs Figure 4 1 mult vi Block Diagram 4 Save the VI as mult vi Right click the CIN and select Create c File LabVIEW prompts you to select a name and a storage location for a c file 6 Name the file mult c LabVIEW creates the following c file CIN source file zy include extcode h CIN MgErr CINRun float32 A float32 B float32 A_B CIN MgErr CINRun float32 A float32 B float32 A_B ENTER YOUR CODE HERE return noErr The preceding c file contains a prototype and a template for the CINRun routine of the CIN LabVIEW calls the CINRun routine when the CIN executes In this example Lab
37. enough to contain pstr Parameters Name Type Description pstr PStr Pointer to a Pascal string cstr cstr Pointer to a C string Return Value The length of the string O National Instruments Corporation 6 159 Using External Code in LabVIEW Chapter 6 Function Descriptions PToLStr int32 PToLStr pstr Purpose lstrp Converts a Pascal string to a long Pascal string This function works even if the pointers pstr and Istrp refer to the same memory location The function assumes Istrp is large enough to contain pstr Parameters Name Type Description pstr PStr Pointer to a Pascal string Istrp LStrPtr Pointer to a long Pascal string Return Value The length of the string Using External Code in LabVIEW 6 160 ni com QSort Chapter 6 Function Descriptions void QSort arrayp n Purpose elmtSize compareProcP Sorts an array of an arbitrary data type using the QuickSort algorithm In addition to passing the array you want to sort to this routine you also pass a comparison procedure that this sort routine then uses to compare elements in the array The comparison routine should return a number less than zero if a is less than b zero if a is equal to b and a number greater than zero if a is greater than b You should declare the comparison routine to have the following parameters and return type int32 compareProcP UPtr a UPtr b
38. function works even if the pointers Istrp and pstr refer to the same memory location The function assumes pstr is large enough to contain Istrp Parameters Name Type Description Istrp LStrPtr Pointer to a long Pascal string pstr PStr Pointer to a Pascal string Return Value The length of the string truncated to a maximum of 255 characters Using External Code in LabVIEW 6 136 ni com Max Chapter 6 Function Descriptions int32 Max n m Purpose Returns the maximum of two int32 parameters Parameters Name Type Description n m int32 int32 parameters whose maximum value you want to determine National Instruments Corporation 6 137 Using External Code in LabVIEW Chapter 6 Function Descriptions MilliSecs uint32 MilliSecs Return Value The time in milliseconds since an undefined system time The actual resolution of this timer is system dependent Using External Code in LabVIEW 6 138 ni com Min Chapter 6 Function Descriptions int32 Min n m Purpose Returns the minimum of two int32 parameters Parameters Name Type Description n m int32 int32 parameters whose minimum value you want to determine O National Instruments Corporation 6 139 Using External Code in LabVIEW Chapter 6 Function Descriptions MoveBlock void MoveBlock ps size Purpose Moves size bytes from one address to ano
39. if they were one string Parameters Name Type Description slp CPStrPtr Pointer to a concatenated list of Pascal strings s2p CPStrPtr Pointer to a concatenated list of Pascal strings Return Value lt 0 0 or gt 0 if slp is less than equal to or greater than s2p respectively Returns lt 0 if s1p is an initial substring of s2p National Instruments Corporation 6 37 Using External Code in LabVIEW Chapter 6 Function Descriptions CPStrindex PStr CPStrIindex slh Purpose index Returns a pointer to the Pascal string denoted by index in a list of strings If index is greater than or equal to the number of strings in the list this function returns the pointer to the last string Parameters Name Type Description slh CPStrHandle Handle to a concatenated list of Pascal strings index int32 Number of the string you want with 0 as the first string Return Value A pointer to the specified Pascal string Using External Code in LabVIEW 6 38 ni com CPSitrinsert Chapter 6 Function Descriptions MgErr CPStrIinsert slh Purpose s2 index Inserts a new Pascal string before the index numbered Pascal string in a concatenated list of Pascal strings If index is greater than or equal to the number of strings in the list this function places the new string at the end of the list The function resizes the list to make room for the
40. in LabVIEW 6 144 ni com Pin Chapter 6 Function Descriptions int32 Pin i low high Purpose Returns i coerced to fall within the range from low to high inclusive Parameters Name Type Description i int32 Value you want to coerce to the specified range low int32 Low value of the range to which you want to coerce i high int32 High value of the range to which you want to coerce i Return Value i coerced to the specified range National Instruments Corporation 6 145 Using External Code in LabVIEW Chapter 6 Function Descriptions PostLVUserEvent MgErr PostLVUserl Purpose Event LVUser EventRef ref void data Posts the given user event The event and associated data are queued for all event structures registered for the event Parameters Name Type Description ref LVUserEventRef Event refnum for the event for which you want to post data data void Address of the data to post The data must match the type used to create the user event Return Value MgErr which can contain the following error noErr mgArg Using External Code in LabVIEW BCE No error Not a valid user event 6 146 ni com PPStrCaseCmp Chapter 6 Function Descriptions int32 PPStrCaseCmp slp Purpose s2p Lexically compares two Pascal strings and determines whether one is less than equal to or greater t
41. in areentrant VI CINAbort is called for each CIN data space as well CINs in VIs not currently running are not notified by LabVIEW of the abort event My Note CINAbort only works if the VI containing the CIN is running If a top level VI is running and the program is aborted CINAbort only works if the top level VI is currently running the subVI in which the CIN is located If the top level VI is running another subVI in the hierarchy CINAbort does not work National Instruments Corporation 5 5 Using External Code in LabVIEW Chapter 5 Advanced Applications CINs are synchronous Therefore when a CIN begins execution the CIN takes control of its thread until execution is completed If your version of LabVIEW is single threaded you cannot abort the CIN because no other LabVIEW tasks can run while a CIN executes Multiple References to the Same CIN in a Single VI Using External Code in LabVIEW If you loaded the same code resource into multiple CINs or if you duplicated a given CIN LabVIEW gives each reference to the code resource a chance to perform initialization or deallocation No matter how many references you have in memory to a given code resource LabVIEW calls the CINLoad routine only once when the resource is first loaded into memory although it is also called if you load a new version of the resource When you unload the VI LabVIEW calls CINUn1load once After LabVIEW calls CINLoad it calls CINInit once for each
42. int32 sec 0 59 int32 min 0 59 int32 hour 0 23 int32 mday day of the month 1 31 int32 mon month of the year 1 12 int32 year year 1904 2040 int32 wday day of the week 1 7 for Sun Sat int32 yday day of year julian date 1 366 int32 isdst 1 if daylight savings time DateRec National Instruments Corporation 4 33 Using External Code in LabVIEW Advanced Applications CIN Routines This chapter describes several options needed only in advanced applications including how to use the CINInit CINDispose CINAbort CINLoad CINUnload CINSave and CINProperties routines This chapter also describes how global data works within CIN source code and how Windows users can call a DLL from a CIN A CIN consists of several routines The routines are described by the c file LabVIEW creates when you right click the CIN on the block diagram and select Create c File from the shortcut menu Previous chapters have described only the CINRun routine Other routines include CINLoad CINInit CINAbort CINSave CINDispose CINUnload and CINProperties For most CINs you need to write only the CINRun routine The other routines are supplied mainly for special initialization needs such as when your CIN is going to maintain information across calls and you want to preallocate or initialize global state information If you want to preallocate or initialize global state information you
43. it If another node on the block diagram uses the input data LabVIEW does not copy the data The source code should not modify the value passed into the input terminal of a terminal pair if you do not wire the output terminal If the CIN does modify the input value nodes connected to the input terminal wire might receive the modified data Output Only Terminals If you use a terminal pair only to return a value make it an output only terminal pair by resizing the CIN right clicking the terminal pair and selecting Output Only from the shortcut menu If a terminal pair is output only the input terminal is gray as shown Figure 3 4 Figure 3 4 CIN with an Output Only Terminal Pair For output only terminals LabVIEW creates storage space for a return value and passes the value by reference to the CIN the same way it passes values for input output terminal pairs If you do not wire a control to the left terminal LabVIEW determines the type of the output parameter by checking the type of the indicator wired to the output terminal This can be ambiguous if you wire the output to two destinations that have different data types To solve this problem wire a control to the input terminal of the terminal pair as shown in Figure 3 4 In this case the output terminal takes on the same data type as the input terminal LabVIEW uses the input data type only to determine the data type for the output terminal The CIN does not use or affe
44. location pointed to by fp Parameters Name Type Description path fp Path UPtr Path you want to flatten Address in which FFlattenPath stores the resulting flattened path If NULL FFlattenPath does not write anything to this address but does return the size that the flattened path would require Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value int32 indicating the number of bytes required to store the flattened path Using External Code in LabVIEW 6 64 ni com FFlush Chapter 6 Function Descriptions MgErr FFlush fd Purpose Writes any buffered data for the specified file out to the disk Parameters Name Type Description fd File File descriptor associated with the file Return Value MgErr which can contain the following errors No error Not a valid file descriptor Unspecified I O error noErr mgArgErr fIOErr O National Instruments Corporation 6 65 Using External Code in LabVIEW Chapter 6 Function Descriptions FGetAccessRights MgErr FGetAccessRights path owner group permPtr Purpose Returns access rights information about the specified file or directory Parameters Name Type Description path Path Path of the file or directory about which you want access rights information owner PStr Address at which
45. more complicated data types using clusters which can in turn contain scalars arrays and other clusters The first four bytes of a LabVIEW array indicate the number of elements in the array The elements of the array follow the length field Refer to the Passing Parameters section of this chapter for examples of manipulating arrays Strings LabVIEW supports C and Pascal style strings lists of strings and LStr a special string data type you use for string parameters to external code modules The support manager contains routines for manipulating strings and converting them among the different types of strings O National Instruments Corporation 4 21 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs C Style Strings CStr A C style string CStr is a series of zero or more unsigned characters terminated by a zero C strings have no effective length limit Most manager routines use C strings unless you specify otherwise The following code is the type definition for a C string typedef uChar CStr Pascal Style Strings PStr A Pascal style string PStr is a series of unsigned characters The value of the first character indicates the length of the string A PStr can have a range of 0 to 255 characters The following code is the type definition for a Pascal string typedef uChar Str255 256 Str31 32 StringPtr StringHandle typedef uChar PStr LabVIEW Strings LStr The first four bytes of
46. need to understand more of how LabVIEW manages data and CINs as described in the following sections Data Spaces and Code Resources When you create a CIN you compile your source into an object code file and load the code into the CIN After the object code is loaded into the CIN LabVIEW loads a copy of the code resource into memory and attaches it to the CIN When you save the VI the code resource is saved along with the VI as an attached component Because the code resource is saved along with the VI as an attached component the original object code file is no longer needed When LabVIEW loads a VI it allocates a data space for that VI A data space is a block of data storage memory LabVIEW uses the data space to National Instruments Corporation 5 1 Using External Code in LabVIEW Chapter 5 Advanced Applications Using External Code in LabVIEW store information such as the values in shift registers If the VI is reentrant LabVIEW allocates a data space for each usage of the VI Refer to the LabVIEW Help for more information about reentrancy and other execution properties Within your CIN code resource you might have declared global data Global data includes variables declared outside of the scope of all routines and variables declared as static variables within routines LabVIEW allocates space for this global data As with the code itself only one instance of the global data is in memory Regardless of how many nodes
47. not change Parameters Name Type Description fd File File descriptor associated with the file size int32 New file size in bytes Return Value MgErr which can contain the following errors noErr mgArgE rr fDiskFull fNoPerm fIOErr No error Not a valid file descriptor or size lt 0 Disk is full Access was denied the file already exists or the disk is locked or protected Unspecified I O error National Instruments Corporation 6 111 Using External Code in LabVIEW Chapter 6 Function Descriptions FSetinfo MgErr FSetInfo path infop Purpose Sets information for the specified file or directory If an error occurs no information changes Parameters Name Type Description path Path Path of the file or directory for which you want to set information infop FInfoPtr Address of information FSet Info sets for the file or directory FInfoPtr is a data structure that defines the attributes of a file or directory The following code lists the file directory information record FInfoPtr typedef struct Using External Code in LabVIEW int32 int32 int32 int32 int32 uint32 uint32 Boo132 type creator permissions size rfSize cdate mdate folder 6 112 system specific file type 0 for directories system specific file creator 0 for folders on Mac only system specific file access
48. or uL Single precision floating point number 09 or fs National Instruments Corporation 6 141 Using External Code in LabVIEW Chapter 6 Function Descriptions Data Type Type Code numbers in hexadecimal Double precision floating point number OA or fD Extended precision floating point number OB or fX Complex single precision floating point OC or cS number Complex double precision floating point OD or cD number Complex extended precision OE or cX floating point number Using External Code in LabVIEW 6 142 ni com Occur Chapter 6 Function Descriptions MgErr Occur Ocurrence o Purpose Triggers the specified occurrence All block diagrams that are waiting for this occurrence stop waiting Parameters Name Type Description o Occurrence Occurrence refnum you want to trigger Return Value MgErr which can contain the following error noErr mgArgErr National Instruments Corporation No error Not a valid user event 6 143 Using External Code in LabVIEW Chapter 6 Function Descriptions Offset Macro int16 Offset type field Purpose Returns the offset of the specified field within the structure called type Parameters Name Type Description type Structure that contains field field Field whose offset you want to determine Return Value An offset as an int16 Using External Code
49. parameter or local variable Using External Code in LabVIEW 6 178 ni com Chapter 6 Function Descriptions Word Macro int16 Word hi lo Purpose Creates an int16 from two int8 parameters Parameters Name Type Description hi int8 High int8 for the resulting int16 lo int8 Low int8 for the resulting int16 Return Value The resulting int16 O National Instruments Corporation 6 179 Using External Code in LabVIEW Technical Support and Professional Services Visit the following sections of the National Instruments Web site at ni com for technical support and professional services e Support oOnline technical support resources include the following Self Help Resources For immediate answers and solutions visit our extensive library of technical support resources available in English Japanese and Spanish at ni com support These resources are available for most products at no cost to registered users and include software drivers and updates a KnowledgeBase product manuals step by step troubleshooting wizards conformity documentation example code tutorials and application notes instrument drivers discussion forums a measurement glossary and so on Assisted Support Options Contact NI engineers and other measurement and automation professionals by visiting ni com support Our online system helps you define your question and connects you to the experts by phone di
50. reference to the CIN because the CIN data space for the CIN might need initialization Thus if you have two CINs in the same VI and both reference the same code LabVIEW calls the CINLoad routine once and CINInit twice If you later load another VI referencing the same code resource LabVIEW calls CINInit again for the new version Because LabVIEW has already called CINLoad once for the code resource it does not call CINLoad again for this new reference LabVIEW calls CINDispose and CINAbort for each individual CIN data space LabVIEW calls CINSave only once regardless of the number of references to a given code resource within the VI you are saving Figure 5 2 shows an example of three CINs referencing the same code resource 5 6 ni com Chapter 5 Advanced Applications E l Mg Yi Diagram Global Storage 4 byte CIN Data Space 4 byte CIN Data Space 4 byte CIN Data Space Data Space Globals Figure 5 2 Three CINs Referencing the Same Code Resource Multiple References to the Same CIN in Different Vis Making multiple references to the same CIN in different VIs is different for single threaded operating systems than for mutlithreaded operating systems ays Note Mac Classic is the only single threaded operating system supported by LabVIEW Single Threaded Operating Systems When you make a VI reentrant Lab VIEW creates a separate data space for each i
51. rights file size in bytes data fork on Mac or entries in directory resource fork size on Mac only creation date seconds since system reference time A last modification date seconds since system ref time ES indicates whether path refers to a folder ni com Return Value Bool132 Point Str255 Str255 isInvisible location owner group Chapter 6 Function Descriptions indicates whether file is visible in File Dialog on Mac only system specific desktop geographical location on Mac only owner in pascal string form of file or folder group in pascal string form of file or folder FiInfoRec FInfoPtr MgErr which can contain the following errors No error A bad argument was passed to the function Verify the path File not found Unspecified I O error noErr mgArgErr fNotFound fIOErr National Instruments Corporation 6 113 Using External Code in LabVIEW Chapter 6 Function Descriptions FSetPathType MgErr FSetPathType path type Purpose Changes the type of a path which must be a valid path to the specified type relative or absolute Parameters Name Type Description path Path Path whose type you want to change type int32 New type you want the path to have type can have the following values e fAbsPath The path is absolute e f RelPath The path is relative
52. rows and the number of columns in the array respectively The data is declared as a one dimensional C style array LabVIEW stores data row by row as shown in Figure 4 6 c columns 0 0 0 1 0 c 1 1 0 1 1 2 1 c 1 r rows r1 0 r1 1 r1 c 1 in memory dimSizes argi o m 0 H le 1 fc c 1 r c 1 r c 00 0 1 0Oc 1 1 0 1 1 r 1 c 1 Figure 4 6 LabVIEW Data Storage For an array with r rows and c columns you can access the element at row i and column 3 as shown in the following code value arrayh gt argl i c 31 Working with Clusters In this example the CIN takes an array of clusters and a single cluster as inputs The clusters contain a 16 bit signed integer and a string The top terminal of the CIN is an input output terminal The top terminal takes the array of clusters as an input and returns the new array of clusters as an output In addition to the new array of clusters the CIN returns a Boolean parameter and a 32 bit signed integer If the single cluster is already present in the array of clusters the CIN sets the Boolean parameter to TRUE If the Boolean parameter is TRUE the CIN returns in the 32 bit integer output the position the single cluster occupies in the array of clusters Using External Code in LabVIEW 4 14 ni com Chapter 4 Programming Issues for CINs If the single cluster is not present in the array of clusters the CIN adds it to the array s
53. simultaneously please consult C programming documentation The following characteristics are the basic characteristics of thread safe code in a CIN e The code is thread safe when it does not store any unprotected global data such as global variables files on disk and so on e The code is thread safe when it does not access any hardware In other words the code does not contain register level programming e The code is thread safe when it does not make any calls to any functions shared libraries or drivers that are not thread safe e The code is thread safe when it uses semaphores or mutexes to protect access to global resources e The CIN call is thread safe when only one non reentrant VI calls the CIN National Instruments Corporation 3 3 Using External Code in LabVIEW Chapter 3 CINs Creating a CIN e The CIN call is thread safe when the code does not access any global resources through CIN housekeeping routines such as CINInit CINAbort CINDispose and others Complete the following general steps to create a CIN 1 Describe in LabVIEW the data you want to pass to the CIN 2 Write and compile the code for the CIN using one of the supported programming languages 3 Runa utility that puts the compiled code into a format LabVIEW can use 4 Instruct LabVIEW to load the CIN If you run the VI after completing the preceding steps and the block diagram needs to execute the CIN Lab VIEW calls the CIN object
54. statistics about the memory in a zone Parameters Name Type Description msrp MemStatRec Statistics about the zone s free memory in a MemStatRec structure Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter The following code defines the MemStatRec structure typedef struct int32 totFreeSize maxFreeSize nFreeBlocks int32 totAllocSize maxAllocSize int32 nPointers nUnlockedHdls nLockedHdls int32 reserved 4 The free memory in a zone consists of a number of blocks of contiguous memory In the MemStatRec structure totFreeSize is the sum of the sizes of the contiguous memory blocks maxFreeSize is the largest of the contiguous memory blocks as returned by XXMaxMem nFreeBlocks is the number of the contiguous memory blocks Similarly the allocated memory in a zone consists of a number of blocks of contiguous memory In the MemStatRec structure totAllocSize is the sum of the sizes of the contiguous memory blocks maxAllocSize is the largest of the contiguous memory blocks Because there are three different varieties of allocated blocks the numbers of blocks of each type is returned separately nPointers int32 is the number of pointers nUnlockedHdls int32 is the number of unlocked handles nLockedHdls int32 is the number of locked handles Add the values of nPointers nUnlockedHdls and nLockedHdls together to find the total number of allocated b
55. the format string is a Pascal string instead of a C string As with PPrintf PPrint fp sets the length byte of the Pascal string to reflect the size of the resulting string FPrintf FPrintf prints to a file specified by the refnum in fd FPrint does not embed a length count or a terminating NULL character in the data written to the file O National Instruments Corporation 6 149 Using External Code in LabVIEW Chapter 6 Function Descriptions LStrPrintf LStrPrintf prints to a LabVIEW string specified by destLsh Because the string is a handle that might be resized LStrPrintf can return memory errors just as DSSetHandleSize does Special Chracters These functions accept the following special characters b Backspace v Form feed n New line which inserts the system dependent end of line char s for example CR on Mac OS NL on UNIX CRNL on DOS Vr Carriage return s Space t Tab vv Percentage character to print Formats These functions accept the following formats Left justifies what is printed if not specified the data is right justified field size Indicates the minimum width of the field to print into If not specified the default is 0 If less than the specified number of characters are in the data to print the function pads with spaces on the left if you specified Otherwise the function pads on the right precision Sets the precision for floating point numbers that is the number of
56. the hardware e Description of the shared library file xbus d11 that contains these functions e Instructions on including a header file xbus h 3 Note Although LabVIEW does not permit you to include such header files you can open header files and extract information about function prototypes and constants e A statement about the Standard __stdca11 calling convention that the X bus library uses One of the functions you want to use with this hypothetical hardware is XBusRead16 which reads a 16 bit integer from a certain address The documentation describes XBusRead16 as follows long XBusRead16 unsigned long offset short data Puts 16 bits from the register at offset into the memory location pointed to by data Returns 1 if successful or 0 if it fails Given the preceding information from the X bus documentation complete the following steps to configure the LabVIEW Call Library Function Node 1 Create a new VI named Read Data 2 Place a Call Library Function Node on the block diagram 3 Right click the Call Library Function Node object and select Configure from the shortcut menu 4 Make the following settings in the Call Library Function dialog box Enter XbusRead16 in the Function Name control Select stdcall WINAPD from the Calling Conventions pull down menu c Select Numeric from the Type pull down menu for return type d Select Signed 32 bit Integer from the Data Type pul
57. use e Function Name Decoration This pitfall appears when certain functions have their names decorated when they are linked A typical C compiler tracks name decoration and when it looks for a function in a shared library it recognizes the decorated name However because LabVIEW is not a C compiler it does not recognize decorated names If you suspect that function name decoration is causing difficulty inspect the shared library s exported functions B Note Ifthe function name that appears in the function prototype section has characters such as appended to it the function was decorated when the DLL was built This is most common with C compilers In LabVIEW the Function Name control in the Call Library Function dialog box is a pull down list where you can access a list of all functions within the library you have selected In addition most operating systems have a utility you can use to view a library s exports for example QuickView on the Windows operating system and the nm command on most UNIX systems 3 Note Windows and Mac If the Function Name list contains entries but the function you want to call does not appear in the list the most likely reason is that the function has not been exported Refer to the documentation for your compiler for information about how to mark functions for export UNIX The Function Name list always appears as an empty list You must enter the name of the function you want to call Using
58. 04 12 00 a m UT O National Instruments Corporation 6 175 Using External Code in LabVIEW Chapter 6 Function Descriptions ToLower uChar ToLower c Purpose Returns the lowercase value of c if e is an uppercase alphabetic character Otherwise this function returns c unmodified In SPARCstation this function also works for international characters A to and so on Parameters Name Type Description int32 Character you want to analyze Return Value The lowercase value of c Using External Code in LabVIEW 6 176 ni com ToUpper Chapter 6 Function Descriptions uChar ToUpper c Purpose Returns the uppercase value of if e is a lowercase alphabetic character Otherwise this function returns e unmodified In SPARCstation this function also works for international characters 4 to A and so on Parameters Name Type Description int32 Character you want to analyze Return Value The uppercase value of c National Instruments Corporation 6 177 Using External Code in LabVIEW Chapter 6 Function Descriptions Unused Macro void Unused x Purpose Indicates that a function parameter or local variable is not used by that function This is useful for suppressing compiler warnings for many compilers This macro does not use a semicolon Parameters Name Type Description Unused
59. 1b Play Sound vi directory lets you play Windows WAV sound files on your computer from LabVIEW if you have a sound card with Windows sound drivers installed on your system e Ifyou do not have a sound card you can generate a sound in your PC speaker by calling the MessageBeep function in User32 DLL The function prototype is as follows VOID MessageBeep UINT uType Using External Code in LabVIEW 2 30 ni com Chapter 2 Shared Libraries DLLs The Hostname VI located in the examples d11 hostname hostname vi directory returns the host name of your computer demonstrating how to use LabVIEW string handles You can programmatically position your cursor anywhere on your monitor using the SetCursorPos function in User32 DLL The function prototype is as follows BOOL SetCursorPos INT x INT y x and y are the coordinates you want referenced from the upper left corner of the screen The return value is TRUE if the function was successful and FALSE if it was unsuccessful Remember that the value returned is type BOOL which is defined in the Win32 API as a 32 bit signed integer with values 0 FALSE and 1 TRUE Debugging DLLs and Calls to DLLs When you debug your LabVIEW calls to DLLs you must be prepared to trace problems in the DLL you are calling and in your implementation of the Call Library Function Node in LabVIEW Troubleshooting the Call Library Function Node When your LabVIEW calls to DLLs generate errors
60. 3 Using External Code in LabVIEW Chapter 6 Function Descriptions PStrCat int32 PStrCat sl Purpose Concatenates a Pascal string s2 to the end of another Pascal string s1 and returns the result in s1 This function assumes sl is large enough to contain the resulting string If the resulting string is larger than 255 characters the function limits the resulting string to 255 characters Parameters Name Type Description s1 PStr Pointer to a Pascal string s2 PStr Pointer to a Pascal string Return Value The length of the resulting string Using External Code in LabVIEW 6 154 ni com PStrCmp Chapter 6 Function Descriptions int32 PStrCmp sl Purpose Lexically compares two Pascal strings to determine whether one is less than equal to or greater than the other This comparison is case sensitive Parameters Name Type Description sl PStr Pointer to a Pascal string s2 PStr Pointer to a Pascal string Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an initial substring of s2 National Instruments Corporation 6 155 Using External Code in LabVIEW Chapter 6 Function Descriptions PStrCpy PStr PStrCpy dst Purpose src Copies the Pascal string src to the Pascal string dst This function assumes dst is large enough to contain sre Par
61. 32 Address at which FGet PathType stores the type typePtr can have the following values fAbsPath The path is absolute e f RelPath The path is relative e f NotAPath The path is the canonical invalid path or an error occurred Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path National Instruments Corporation 6 71 Using External Code in LabVIEW Chapter 6 Function Descriptions FGetVollnfo MgErr FGetVolInfo path vinfo Purpose Gets a path specification and information for the volume containing the specified file or directory Parameters Name Type Description path Path Path of a file or directory contained on the volume from which you want to get information This path is overwritten with a path specifying the volume containing the specified file or directory If an error occurs path is undefined vinfo VinfoRec Address at which FgetVol Info stores the information about the volume If an error occurs vinfo is undefined Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter The following code describes the volume information record VInfoRec typedef struct uint32 size uint32 used u
62. 5 POSTE PY iia il ln 6 156 PS E lao ais eae erat 6 157 PSr NEDY irae ci aii ria iia 6 158 PLoC rutina ta iii di 6 159 PTOS Titi aid 6 160 QS Ol accionista tt iban de 6 161 A O 6 162 O National Instruments Corporation xi Using External Code in LabVIEW Contents Appendix A SOCSTOD ate sininen RE EREE E EA ESEE REEK RE NERE 6 163 SeA OAA ii daa ss 6 164 SECIN ATT SIZE ita tt til 6 165 UCC AL A OS 6 166 SUG MP radiata a oe 6 167 SUC PY wane ida 6 168 SU adi 6 169 SUNCascCmp rica ii ltda 6 170 SNCM D ei A A dd 6 171 SENCPY aaar e a a A a E a E ita 6 172 SwapBlock A NT 6 173 TIME ESO ii ei tai ini 6 174 TimeInS ecc ati 6 175 TOMO Wet it ts ai 6 176 SS 6 177 A ccesteseceetessctascabeegesanctenssavesvideses sgeaug ca iesieeamenes a a E E Aa 6 178 Worde ieaiai ieni ete tes csi Rides cede ea vals Ae ae eens edo edev ase 6 179 Technical Support and Professional Services Glossary Using External Code in LabVIEW xii ni com About This Manual Conventions This manual describes the Call Library Function Node and the Code Interface Node CIN The Call Library Function Node and the CIN are the LabVIEW programming objects you use to call compiled code from text based programming languages This manual includes reference information about libraries of functions memory and file manipulation routines and diagnostic routines that you can use with calls to external code Y 3 A bold italic monospace monospace bold
63. 7 Using External Code in LabVIEW Chapter 6 Function Descriptions StrCpy CStr StrCpy dst Purpose src Copies the C string sre to the C string dst This function assumes dst is large enough to contain src Parameters Name Type Description dst Cstr Pointer to a C string src CStr Pointer to a C string Return Value A copy of the destination C string pointer Using External Code in LabVIEW 6 168 ni com StrLen Chapter 6 Function Descriptions int32 StrLen s Purpose Returns the length of a C string Parameters Name Type Description S cstr Pointer to a C string Return Value The number of characters in the C string not including the NULL terminating character O National Instruments Corporation 6 169 Using External Code in LabVIEW Chapter 6 Function Descriptions StrNCaseCmp int32 StrNCaseCmp sl Purpose s2 n Lexically compares two strings to determine whether one is less than equal to or greater than the other limiting the comparison to n characters This comparison ignores differences in case Parameters Name Type Description s1 cstr Pointer to a C string s2 CStr Pointer to a C string n uInt32 Maximum number of characters you want to compare Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an init
64. C style string pointer All parameters are defined to be passed by the correct method such as value or pointer Pascal strings do not exceed 255 characters in length Remember that C strings are NULL terminated If your DLL function returns numeric data in a binary string format for example through GPIB or the serial port it might return NULL values as part of the data string For arrays or strings of data always pass a buffer or array that is large enough to hold any results that the function places in the buffer However if you are passing them as LabVIEW handles use CIN functions to resize them under Visual C Code Warrior or Symantec compilers When you are using __ stdcal1 list DLL functions in the EXPORTS section of the module definition file DLL functions that other applications call appear in the module definition file EXPORTS section or you include the _declspec dllexport keyword in the function declaration When you use a C compiler export functions with the extern C statement in your header file in order to prevent name mangling For a DLL that you have written never recompile the DLL while the DLL is loaded into memory by another application for example by your VI Before recompiling a DLL make sure that all applications making use of the DLL are unloaded from memory This ensures that the DLL itself is not loaded into memory during a recompile The DLL might fail to rebuild correctly if yo
65. DisposePtr MgErr AZDisposePtr p MgErr DSDisposePtr p Purpose Releases the memory referenced by the specified pointer Parameters Name Type Description p UPtr Pointer you want to dispose of Return Value MgErr which can contain the following errors No error Handle or pointer not in specified zone noErr mZoneErr Using External Code in LabVIEW ni com AZGetHandleSize DSGetHandleSize Chapter 6 Function Descriptions int32 AZGetHandleSize h int32 DSGetHandleSize h Purpose Returns the size of the block of memory referenced by the specified handle Parameters Name Type Description h UHandle Handle whose size you want to determine Return Value The size in bytes of the relocatable block referenced by the handle h If an error occurs this function returns a negative number National Instruments Corporation Using External Code in LabVIEW Chapter 6 Function Descriptions AZHeapCheck DSHeapCheck int32 AZHeapCheck Bool32 d int32 DSHeapCheck Bool32 d Purpose Verifies that the specified heap is not corrupt This function returns 0 for an intact heap and a nonzero value for a corrupt heap Parameters Name Type Description d Return Value Bool132 Heap you want to verify int32 which can contain the following errors noErr mCorruptErr Using External Code in LabVIEW The heap is intact
66. E R xiii Related Documentation etica tienda A A EA aS xiv Chapter 1 Introduction Calling Code in Various Platforms esesseseesesesesesssesresrstestsresteresteresresresesresresesteetseeses 1 1 Characteristics of the Two Calling Approaches ooonconncnonnnonconononoononanonnnonccnnonnnonncnnncnnos 1 2 Details of the Call Library Function Node oooooncononionononconnnanonnnonccnncnnnonccrnncnnos 1 3 Details ota CIN inene an ies pia 1 4 Using the Flatten To String Function oooconconicnnoconcnonncononnnonnnonocan ono nonn non ncnn non nono non ncnncrnno 1 4 Chapter 2 Shared Libraries DLLs Configuring the Call Library Function Node ooooonconncnicnnonononinnonancnnconnconcnnconcnon corn nonncnnos 2 1 Configuring for Multiple Thread OperatiON oooconnnnnninnnonnnonconnnnnonncnnncnncnnncnnos 2 2 Setting the Calling Convention ocoocnocnconnoononnnononnncnnnnnncnnonnnonn con ncnn cnn ncnncnnncnnonns 2 3 Config rins Parameters aiii iia 2 3 Configuring Return Type oooconccnocnnonconononcnnnonnnonncononononn non cnn cono rnncnnos 2 4 Adding and Deleting Parameters ooooonnnccnnnccnocononncinnnnnaccnnccnnnnconccnnnos 2 4 Editing Parameters imita ii 2 4 Selecting the Parameter Type oooooncninnnocnocnonnconcnoncnnnonncnnoranonnccnnonnnnns 2 4 Calling Functions That Expect Other Data Types cece eects eeeeeeees 2 8 Building a Shared Library DLL oo eee eeeecesecececeeeeneceeeeaeeseeeseeseeseesseseaeeneeaes 2 8 Task 1 Build the Functi
67. Each element contains eight bytes for the double precision number followed by four bytes for the integer Each cluster is followed by four bytes of padding which makes sure the next element is properly aligned You can use SetCINArraySize and NumericArrayResize to solve the preceding problems Refer to Chapter 6 Function Descriptions for information about the SetCINArraySize and NumericArrayResize functions Arrays and Strings Paths LabVIEW passes arrays by handle as described in the Alignment Considerations section For an n dimensional array the handle begins with n 4 byte values describing the number of values stored in a given dimension of the array Thus for a one dimensional array the first four bytes indicate the number of elements in the array For a two dimensional array the first four bytes indicate the number of rows The second four bytes indicate the number of columns These dimension fields can be followed by filler and then the actual data Each element can also have padding to meet alignment requirements LabVIEW stores strings and Boolean arrays in memory as one dimensional arrays of 8 bit unsigned integers Refer to the Using the Flatten To String Function section of Chapter 1 Introduction for information about using the Flatten to String function to convert Lab VIEW data into a string Note LabVIEW 4 x stored Boolean arrays in memory as a series of bits packed to the nearest 16 bit integer LabVIEW 4 x ignored u
68. External Code in LabVIEW 2 18 ni com Chapter 2 Shared Libraries DLLs Data Types Your library call can fail when you do not use the correct data types LabVIEW only supports basic numeric data types and C strings Also you can select Adapt to Type from the Type pull down menu of the Call Library Function dialog box and direct LabVIEW to pass its own internal data types for a given parameter You might encounter the following specific problems Non Standard Data Type Definitions Frequently other APIs use non standard definitions for data types For example instead of using char short and long the Windows API uses BYTE WORD and DWORD If an API that you are using makes use of such data types you need to find the equivalent basic C data type so that you can properly configure the Call Library Function Node The Example 3 Call the Win32 API section presents an example of this process e Structure and Class Data Types Some APIs have structure and in the case of C class data types LabVIEW cannot use these data types If you need to use a function that has a structure or class as an argument you should write a CIN or shared library wrapper function that takes as inputs the data types that LabVIEW supports and that appropriately packages them before LabVIEW calls the desired function Windows Refer to the examples d11l data passing Call Native Code 11b for an example of using data types in shared libraries Constants
69. FGetAccessRights stores the owner of the file or directory group PStr Address at which FGetAccessRights stores the group of the file or directory permPtr int32 Address at which FGetAccessRights stores the permissions of the file or directory Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path fNotFound File not found fIOErr Unspecified I O error Using External Code in LabVIEW 6 66 ni com FGetDefGroup Chapter 6 Function Descriptions LStrHandle FGetDefGroup groupHandle Purpose Gets the LabVIEW default group for a file or directory Parameters Name Type Description groupHandle LStrHandle Handle that represents the LabVIEW default Return Value group for a file or directory If groupHandle is NULL FGetDefGroup allocates a new handle and returns the default group in it If groupHandle is a handle FGetDefGroup returns it and groupHandle resizes to hold the default group The resulting LStrHandle If groupHandle was not NULL the return value is the same LStrHandle as groupHandle If an error occurs this function returns NULL National Instruments Corporation 6 67 Using External Code in LabVIEW Chapter 6 Function Descriptions FGetEOF
70. Info Filenames and patterns matching FStrFitsPat Files and directories moving and deleting FMove FRemove Files copying FCopy Path type determining FGetPathType FlsAPathOfType FSetPathType 6 4 ni com National Instruments Corporation Chapter 6 Path extracting information Depth DirName FVolName Paths comparing FlsAPath FlsAPathOrNotAPath FlsEmptyPath FPathCmp Paths converting to and from other representations FArrToPath FFlattenPath FPathToArr FPathToAZString FPathToDSString FStringToPath FTextToPath FUnFlattenPath Paths creating FAddPath FAppendName FAppPath FEmptyPath FMakePath FNotAPath FRelPath Paths disposing FDestroyPath Paths duplicating FPathCpy FPathToPath 6 5 Using External Code in LabVIEW Function Descriptions Chapter 6 Function Descriptions Support Manager Functions Using External Code in LabVIEW You can use the support manager functions for bit or byte manipulation of data string manipulation mathematical operations sorting searching and determining the current time and date You can perform the following operations by using the functions listed e Byte manipulation operations Cat4Chrs GetALong Hil6 HiByte HiNibble Lo16 LoByte Long LoNibble Offset SetALong Word e Mathematical operations Abs Max Min Pin RandomGen String manipulation BlockCm
71. Instruments Corporation No error A bad argument was passed to the function Verify the path 6 119 Using External Code in LabVIEW Chapter 6 Function Descriptions GetALong Macro int32 GetALong p Purpose Retrieves an int32 from a void pointer In SPARC station this function can retrieve an int32 at any address even if the int32 is not long word aligned Parameters Name Type Description void Address from which you want to read an int32 Return Value int32 stored at the specified address Using External Code in LabVIEW 6 120 ni com HexChar Chapter 6 Function Descriptions int32 HexChar n Purpose Returns the ASCII character in hex that represents the specified value n O lt n lt 15 Parameters Name Type Description n int32 Decimal value between 0 and 15 Return Value The corresponding ASCII hex character If n is out of range the function returns the ASCII character corresponding to n modulo 16 National Instruments Corporation 6 121 Using External Code in LabVIEW Chapter 6 Function Descriptions Hi16 Macro int16 Hil6 x Purpose Returns the high order int16 of an int32 Parameters Name Type Description x int32 int32 for which you want to determine the high int16 Using External Code in LabVIEW 6 122 ni com HiByte Macro Chapter 6 Function Descriptions
72. L Never resize a string concatenate a string or perform operations that might increase the length of string data passed from LabVIEW if you are using the C or Pascal string pointers e Ifyou must return data as a string allocate a string of the appropriate length in LabVIEW and pass this string into the DLL to act as a buffer e Ifyou pass a LabVIEW String Handle from the Call Library Function Node to the DLL you can use the LabVIEW CIN functions such as DSSetHandleSize to resize the LabVIEW string handle In order to call LabVIEW CIN functions your compile must include the correct LabVIEW library file which is located within the LabVIEW cintools directory Table 2 4 lists different compilers and the correct Lab VIEW library file to use with the compiler Array and String Tip Using External Code in LabVIEW When you are not passing LabVIEW handles and your DLL function must create an array resize an array or resize a string of data you should break the DLL function into the following two DLL functions Determine the number of elements that the array requires or the length of the string to be returned Have the first DLL function return the desired size to LabVIEW e In LabVIEW initialize an array or string with default values and pass this array to the second DLL function in your DLL which actually places the data into the array If you are working with string based instrument control it might be easier to pass an ar
73. LabVIEW Using External Code in LabVIEW Wy NATIONAL April 2003 Edition gt INSTRUMENTS Part Number 370109B 01 Worldwide Technical Support and Product Information ni com National Instruments Corporate Headquarters 11500 North Mopac Expressway Austin Texas 78759 3504 USA Tel 512 683 0100 Worldwide Offices Australia 61 2 9672 8846 Austria 43 0 662 45 79 90 0 Belgium 32 0 2 757 00 20 Brazil 55 11 3262 3599 Canada Calgary 403 274 9391 Canada Montreal 514 288 5722 Canada Ottawa 613 233 5949 Canada Qu bec 514 694 8521 Canada Toronto 905 785 0085 Canada Vancouver 514 685 7530 China 86 21 6555 7838 Czech Republic 420 2 2423 5774 Denmark 45 45 76 26 00 Finland 385 0 9 725 725 11 France 33 0 1 48 14 24 24 Germany 49 0 89 741 31 30 Greece 30 2 10 42 96 427 Hong Kong 2645 3186 India 91 80 51190000 Israel 972 0 3 6393737 Italy 39 02 413091 Japan 81 3 5472 2970 Korea 82 02 3451 3400 Malaysia 603 9059 6711 Mexico 001 800 010 0793 Netherlands 31 0 348 433 466 New Zealand 64 09 914 0488 Norway 47 0 32 27 73 00 Poland 48 0 22 3390 150 Portugal 351 210 311 210 Russia 7 095 238 7139 Singapore 65 6 226 5886 Slovenia 386 3 425 4200 South Africa 27 0 11 805 8197 Spain 34 91 640 0085 Sweden 46 0 8 587 895 00 Switzerland 41 56 200 51 51 Taiwan 886 2 2528 7227 United Kingdom 44 0 1635 523545 For further support information refer to the Technical Support and Professional Services appendix To comment on the
74. Mode to control concurrent access to the file from within LabVIEW You can use the group parameter to assign the file to a UNIX group In Windows or Mac OS group is ignored If the function creates the file the resulting file descriptor is stored in the address referred to by fdp If an error occurs the function stores 0 in the address referred to by fdp and returns an error Sy Note Before you call this function make sure that you understand how to use the fdp parameter Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using the fdp parameter Using External Code in LabVIEW 6 52 ni com Parameters Chapter 6 Function Descriptions Name Type Description fdp File Address at which FCreate stores the file descriptor for the new file If Fcreate fails it stores 0 in the address fdp Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter path Path Path of the file you want to create permissions int32 Permissions to assign to the new file openMode int32 Access mode to use in opening the file The following values are defined in the file extcode h openReadOnly Open for reading e openWriteOnly Open for writing openReadwrite Open for both reading and writing denyMode int32 Mode that determines what level of concurrent access to the file is allowed The fo
75. Ns Refer to Chapter 6 Function Descriptions for descriptions of functions or file manager data structures Sy Note When you call the LabVIEW manager functions from a DLL use include extcode h in any files that use manager functions and link to labview lib Set the structure alignment of the compiler to 1 byte Some of the manager functions such as SetCINArraySize are CIN specific and you cannot call them from a DLL Pointers as Parameters Using External Code in LabVIEW Some manager functions have a parameter that is a pointer These parameter type descriptions are identified by a trailing asterisk such as the ph parameter AZCopyHandle DSCopyHanal e allocating and releasing function or are type defined as such such as the name parameter of the FNamePtr function In most cases the manager function writes a value to pre allocated memory In some cases such as FStrFitsPath or GetALong the function reads a value from the memory location so you do not have to pre allocate memory for a return value The following functions have parameters that return a value for which you must pre allocate memory AZMemStats FNamePtr AZCopyHandle DSCopyHandle FNewRefNum DateToSecs FPathToArr DSMemStats FPathToAZString FCreate FPathToDString FCreateAlways FPathToPath FFlattenPath FRefNumToFD FGetAccessRights FStringToPath FGetEOF FTextToPath FGetInfo FUnflattenPath FGetPathType GetAlong FMOpen SetALong FMRead RandomGen 3 20 n
76. S based systems support multiple drives connected to the system For most of these hierarchical file systems you must include the volume name to specify the location of a file On other systems such as UNIX you do not need to specify the volume name because the physical implementation of the file system is hidden from the user How you identify a target depends upon whether the target is an open or closed file If a target is a closed file or a directory specify the target using the path of the target The path describes the volume containing the target the directories between the top level and the target and the name of the target If the target is an open file use a file descriptor to specify that LabVIEW should perform an operation on the open file The file descriptor is an identifier the file manager associates with the file when you open it When you close the file the file manager dissociates the file descriptor from the file Path Specifications LabVIEW uses the following types of file path specifications e Conventional Empty e LabVIEW specifications Conventional All platforms have a method for describing the paths for files and directories These path specifications are similar but they are usually incompatible from one platform to another You usually specify a path as a series of names separated by separator characters Typically the first name is the top level of the hierarchical specification of the path The last name i
77. SNewHandl8 oconoooocnccnnnonnnncnnononnnonononanononconononanccconnnannnconnns 6 25 AZNewHClr DSNewHCTH benaren n a e a 6 26 AZNewPClr DSNEWPCIL cccccccsssccceesssseeceeesessseeccesesseeecccesssseeceeessseeeeeees 6 27 AZNewPtr DSNeWP lleida ta ad 6 28 AZRecoverHandle DSRecoverHandle ooooocnonnnonoooncccnooaonnnocononnnnnncconanancnncnnnns 6 29 AZSetHandleSize DSSetHandleSize coonoocccnncnooononccononnnnncconononnnonccnnnnnncnncnnnnns 6 30 AZSetHSzClr DSSetHSZCIr coooocccnnnnononnnccononnnnnnnonnoncnonononnonnncononnnnnnconnnnnnnncnnnns 6 31 BO a o ST S 6 32 BlockCmP esteis aero atlas 6 33 CAES a aia 6 34 OET A EAEE ERNE A E NE E NEE ENE lada 6 35 LE oa DAt i EE a 6 36 CPT CMPuscasosti aia 6 37 CPSU it nl ai aa 6 38 CPStrins rti illa is 6 39 EPT a ia i 6 40 EPStTREMO Vea da 6 41 CPStrReplace cierro ati 6 42 ORS SIZ a dit o Cosa alcoi E 6 43 ET Mii a hd 6 44 Date EST i nninnna nan e a E 6 45 BEITA KERIA E A E E EEE P SR OEE 6 46 FA dd Pat PEENE EATE iii 6 47 FApp nd ame sierra o ria ar o n Eaa EE EA E EEE ei EEE 6 48 FAppP alevines 6 49 EAT NOI Path tes ts ia o 6 50 FEOPY ea a dd 6 51 ILO Et E EEEE E E a S eked ea ES 6 52 ECreate AlWAYS cosita EE E a 6 55 FDepth aiei ni ie aee A a A dde 6 58 FDestr y Pathi e en rarae di 6 59 Dad BOTT ON F210 Uae ee ee a as 6 60 FDisposeRefNum cti idad gos 6 61 BE mptyPath cinco tot vsti sieisr ha tiei hat dita ciedad 6 62 AKA S Ss schists ties ad cotati tocaban A de 6 63 PPlattenP
78. This chapter describes the data structures LabVIEW uses when passing data to a CIN and describes the function libraries or managers that you can use in external code modules The function libraries include the memory manager the file manager and the support manager Passing Parameters LabVIEW passes parameters to the CINRun routine The parameters correspond to each of the wires connected to the CIN You can pass any data type to a CIN you can construct in LabVIEW CINs do not have a limit to the number of parameters you can pass to and from them Parameters in the CIN c File When you right click a CIN on a block diagram and select Create c File from the shortcut menu LabVIEW creates a c file in which you can enter your CIN code The CINRun function and its prototype are given CINRun function parameters correspond to the data types being passed to the CIN on the block diagram The c file created is a standard C file except LabVIEW gives the data types unambiguous names C does not define the size of low level data types for example the int data type might correspond to a 16 bit integer for one compiler and a 32 bit integer for another compiler The c file uses names that are explicit about data type size such as int 16 int32 float32 and so on In the cintools directory LabVIEW includes a header file extcode h that contains type definitions that associate LabVIEW data types with the corresponding data type for the supported
79. Unlike LabVIEW and Pascal strings C strings do not contain any information that directly gives the length of the string Instead C strings use a special character called the NULL character to indicate the end of the string NULL is defined to have a value of zero in the ASCII character set Notice that NULL is the number zero and not the character 0 Thus in C a string containing n characters requires n 1 bytes of memory to store n bytes for the characters in the string and one additional byte for the NULL termination character Figure 2 14 illustrates how a C style string is stored in memory t e x t 00 String Data NULL Character Figure 2 14 C String Format National Instruments Corporation 2 39 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs The advantage of C style strings is that they are limited in size only by available memory However if you are acquiring data from an instrument that returns numeric data as a binary string as is common with serial or GPIB instruments values of zero in the string are possible If you treat the string as a C style string your program incorrectly assumes that the end of the string has been reached when in fact your instrument is returning a numeric value of zero For binary data that might contain NULL values consider using an array of 8 bit unsigned integers Observe the following guidelines when passing string data to a DL
80. VI the file containing the object code does not need to be resident on the computer running LabVIEW for the VI to run If you modify the source code you can load the new version of the object code using the Load Code Resource shortcut menu item The file containing the object code for the CIN must have an extension of 1sb There is no limit to the number of CINs per block diagram LabVIEW Manager Routines LabVIEW has a suite of routines that you can call from CINs This suite of routines performs user specified routines using the appropriate instructions for a given platform These routines which manage the functions of a specific operating system are grouped into the following categories e Memory manager e File manager e Support manager External code written using the managers is portable that is you can compile it without modification on any platform that supports LabVIEW This portability has the following advantages e The LabVIEW application is built on top of the managers Except for the managers the LabVIEW source code is identical across platforms e The analysis VIs are built mainly from CINs The source code for these CINs is the same for all platforms Refer to the Manager Overview section of Chapter 4 Programming Issues for CINs for more information about the memory manager the file manager and the support manager National Instruments Corporation 3 19 Using External Code in LabVIEW Chapter 3 CI
81. VIEW passes CINRun the addresses of the three 32 bit floating point numbers The parameters are listed left to right in the same order as they are wired to the CIN that is top to bottom Thus A B and A_B are pointers to A B and A B respectively As described in the Parameters in the CIN c File section the loat32 data type is not a standard C data type For most C compilers the 1o0at32 data type corresponds to the float data type However this might not be true in all cases because the C standard does not define the sizes for the various data types You can use these LabVIEW data types in your code because ext code h associates these data types with the corresponding C data type for the compiler you are using In addition to defining LabVIEW data types extcode h also prototypes LabVIEW routines you can access Refer to the Manager Overview section of this chapter for descriptions of these data types and routines Using External Code in LabVIEW 4 4 ni com Chapter 4 Programming Issues for CINs 7 Fill in the code for the CINRun routine for this multiplication example You do not have to use the variable names LabVIEW gives you in CINRun You can change the variable names to increase the readability of the code Replace ENTER YOUR CODE HERE in the c file with the following example code CIN MgErr CINRun float32 A float32 B float32 A_B A B A B return noErr CINRun mu
82. WARE COMPATIBILITY PROBLEMS MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL DEVICES TRANSIENT FAILURES OF ELECTRONIC SYSTEMS HARDWARE AND OR SOFTWARE UNANTICIPATED USES OR MISUSES OR ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER ADVERSE FACTORS SUCH AS THESE ARE HEREAFTER COLLECTIVELY TERMED SYSTEM FAILURES ANY APPLICATION WHERE A SYSTEM FAILURE WOULD CREATE A RISK OF HARM TO PROPERTY OR PERSONS INCLUDING THE RISK OF BODILY INJURY AND DEATH SHOULD NOT BE RELIANT SOLELY UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE TO AVOID DAMAGE INJURY OR DEATH THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO PROTECT AGAINST SYSTEM FAILURES INCLUDING BUT NOT LIMITED TO BACK UP OR SHUT DOWN MECHANISMS BECAUSE EACH END USER SYSTEM IS CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS TESTING PLATFORMS AND BECAUSE A USER OR APPLICATION DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT EVALUATED OR CONTEMPLATED BY NATIONAL INSTRUMENTS THE USER OR APPLICATION DESIGNER IS ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER NATIONAL INSTRUMENTS PRODUCTS ARE INCORPORATED IN A SYSTEM OR APPLICATION INCLUDING WITHOUT LIMITATION THE APPROPRIATE DESIGN PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION Contents About This Manual CONVENTIONS osie deus vie Heavies cus Teed iii
83. Warrior labview export stub Symantec labview sym lib Visual C labview lib The types of your string pointers must match the types of string pointers that your function uses or errors occur The Call Library Function Node offers the following choices e CString Pointer is a pointer to the string followed by a NULL character Most Win32 API functions use this C style string pointer e Pascal String Pointer is a pointer to the string preceded by a length byte e LabVIEW String Handle is a pointer to a pointer to the string preceded by four bytes of length information e LabVIEW String Handle Pointer is a pointer to a handle for a string preceded by four bytes of length information You can think of a string as an array of characters Assembling the characters in order forms a string LabVIEW stores a string in a special format in which the first four bytes of the array of characters form a 32 bit signed integer that stores how many characters appear in the string Thus a string with n characters requires n 4 bytes to store in memory For example in Figure 2 12 the string text contains four characters 00 WO 00 04 t e x t String Length String Data Figure 2 12 LabVIEW String Format When LabVIEW stores the string the first four bytes contain the value 4 as a 32 bit signed number and each of the following four bytes contains a character of the string The advanta
84. Zones Most memory manager functions have a DS routine and an AZ routine In this section XXFunctionName refers to a function in a general context where XX can be either Ds or AZ When a difference exists between the two zones the specific function name is given Create a handle using XXNewHandle with which you specify the size of the memory block Create a pointer using XXNewPtr XXNewHandleClr and XXNewPC1r are variations that create the memory block and set it to all zeros When you are finished with the handle or pointer release it using XXDisposeHandle or XXDisposePtr If you need to resize an existing handle use the XxSetHandleSize routine which determines the size of an existing handle Because pointers are not relocatable you cannot resize them A handle is a pointer to a pointer In other words a handle is the address of an address The second pointer or address is a master pointer which means it is maintained by the memory manager Languages that support pointers provide operators for accessing data by its address With a handle you use this operator twice once to get to the master pointer and a second time to get to the actual data Using External Code in LabVIEW 4 26 ni com Chapter 4 Programming Issues for CINs While operating within a single call of a CIN node an AZ handle does not move unless you specifically resize it In this context you do not need to lock or unlock handles If your CIN maintains an AZ ha
85. a Shared Library that You Built section 5 Enter the following general specifications a Type avg_num in the Function Name field b Select C from the Calling Conventions pull down menu 6 Define the return value using the following specifications a Change the default name in the Parameter field from return type to the more descriptive name error b Select Numeric from the Type pull down menu c Select Signed 32 bit Integer from the Data Type pull down menu 7 Define the a parameter using the following specifications a Click the Add Parameter After button b Replace the default name arg1 in the Parameter field with the precise name a National Instruments Corporation 2 9 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs c Select Array from the Type pull down menu d Select 4 byte Single from the Data Type pull down menu e Select Array Data Pointer from the Array Format pull down menu 3 Note The Array and String Options section describes the available settings for arrays and strings in the Call Library Function Node icon 8 Define the size parameter using the following specifications a Click the Add Parameter After button b Replace the default name arg2 in the Parameter field with the precise name size c Select Numeric from the Type pull down menu d Select Signed 32 bit Integer from the Data Type pull down menu e Select Value from the Pass pull down menu 9 Define the avg p
86. age Format for Extended Precision Numbers on Various Platforms Platform Storage Format Windows 80 bit structure with two int32 components mhi and mlo and an int16 component e Mac OS 128 bit double double format Sun 128 bit floating point numbers Concurrent Same as float64 Complex Numbers The complex data types are structures with two floating point components re and im As with floating point numbers complex numbers can have 32 bit 64 bit and extended precision components Table 4 4 contains the code for the type definitions for each of these complex data types Using External Code in LabVIEW 4 20 ni com char Chapter 4 Programming Issues for CINs Table 4 4 Code for Complex Numbers Complex Number Type Code 32 bit typedef struct float32 re im cmpl1x64 64 bit typedef struct float64 re im cmp1x128 Extended precision typedef struct floatExt re im cmplxExt The char data type is defined by C to be an 8 bit signed integer LabVIEW defines an unsigned char data type with the following type definition typedef ulnt8 uChar Dynamic LabVIEW defines a number of data types you must allocate and deallocate dynamically Arrays strings and paths have data types you must allocate using memory manager and file manager routines Arrays LabVIEW supports arrays of any of the basic data types described in this section You can construct
87. al Instruments Corporation 6 101 Using External Code in LabVIEW Chapter 6 Function Descriptions FPathToArr MgErr FPathToArr path relativePtr arr Purpose Converts a path to a one dimensional LabVIEW array of strings and determines whether the path is relative Each component name of the path is converted in order into a string in the resulting array If no error occurs arr is set to an array of strings containing the component names of path If an error occurs arr is set to an empty array Parameters Name Type Description path Path Path you want to convert to an array of strings relativePtr Bool32 Address at which to store a Boolean value indicating whether the specified path is relative Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter arr UHandle DS handle where FPathToArr stores the resulting array of strings This handle must already have been allocated Return Value MgErr which can contain the following errors noErr No error mgArgErr Badly formed path or unallocated array mFullErr Insufficient memory Using External Code in LabVIEW 6 102 ni com Chapter 6 Function Descriptions FPathToAZString MgErr FPathToAZString p txt Purpose Converts a path to an LStr and stores the string as an application zone handle The LStr contains the platform specific syntax for the path Pa
88. allocate space for the returned data Therefore name must specify allocated memory of sufficient size to hold the component name Parameters Name Type Description path name Path PStr Path whose last component name you want to determine Address at which FNamePtr stores the last component name as a Pascal string This address must specify allocated memory of sufficient size to hold the name Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr mgArgE mFullE Using External Code in LabVIEW No error Badly formed path or path is root directory Insufficient memory 6 96 ni com Chapter 6 Function Descriptions FNewDir MgErr FNewDir path permissions Purpose Creates a new directory with the specified permissions If an error occurs the function does not create the directory Parameters Name Type Description path Path Path of the directory you want to create permissions int32 Permissions for the new directory Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path fNoPerm Access was denied the file directory or disk is locked or protected fDupPath Directory already exists fIOErr Unspecif
89. ally you can use the LabVIEW Call Library Function Node to accomplish this goal You must provide the following information to the Call Library Function Node excess external APIs from within Labview Code Function name as it appears in the library Function prototype e Library or module in which the function resides e Calling conventions of the function Thread safe status of the function Common Pitfalls with the Call Library Function Node The function reference documentation for any API should provide most of the information that the Call Library Function Node requires However you should keep in mind the common errors listed in this section O National Instruments Corporation 2 17 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Incorrect Function Name Your library call can fail when the name of the function as it appears in the library is different than is expected Usually this error occurs due to function name redefinition or to function name decoration as in the following examples e Redefinition This pitfall appears when an API manufacturer uses a define mechanism such as define directive in ANSI C to define an abstracted function name to one of many functions present in the library based on some external condition such as language or debug mode In such cases you can look in the header h file for the API to determine whether a tdefine directive redefined the name of a function you want to
90. alue FEmptyPath allocates a new path and returns the value If p is a path FEmptyPath sets the existing path to an empty path and returns the new p The resulting path if p was not NULL the return value is the same empty absolute path as p If an error occurs this function returns NULL Using External Code in LabVIEW 6 62 ni com FExists Chapter 6 Function Descriptions int32 FExists path Purpose Returns information about the specified file or directory It returns less information than FGetIn o but it is much quicker on most platforms Parameters Name Type Description path Path Path of the file or directory about which you want information Return Value int32 which can contain the following values kFIsFile kFIsFolder kFNotExist National Instruments Corporation Specified item is a file Specified item is a directory or folder Specified item does not exist 6 63 Using External Code in LabVIEW Chapter 6 Function Descriptions FFlattenPath int32 FFlattenPath p Purpose fp Converts path into a flat form that you can use to write the path as information to a file This function stores the resulting flat path in a pre allocated buffer and returns the number of bytes To determine the size needed for the flattened path pass NULL for fp The function returns the necessary size without writing anything into the
91. ameters Name Type Description dst PStr Pointer to a Pascal string src PStr Pointer to a Pascal string Return Value A copy of the destination Pascal string pointer Using External Code in LabVIEW 6 156 ni com PStrLen Macro Chapter 6 Function Descriptions uInt8 PStrLen s Purpose Returns the length of a Pascal string that is the value at the first byte at the specified address Parameters Name Type Description s PStr Pointer to a Pascal string National Instruments Corporation 6 157 Using External Code in LabVIEW Chapter 6 Function Descriptions PStrNCpy PStr PStrNCpy dst Purpose n Copies the Pascal string sre to the Pascal string dst If the source string is greater than n this function copies only n bytes The function assumes dst is large enough to contain sre Parameters Name Type Description dst PStr Pointer to a Pascal string src PStr Pointer to a Pascal string n int32 Maximum number of bytes you want to copy including the length byte Return Value A copy of the destination Pascal string pointer Using External Code in LabVIEW 6 158 ni com PToCStr Chapter 6 Function Descriptions int32 PToCStr pstr Purpose ESETE Converts a Pascal string to a C string This function works even if the pointers pstr and estr refer to the same memory location The function assumes cstr is large
92. arameter using the following specifications a Click the Add Parameter After button b Replace the default name arg3 in the Parameter field with the precise name avg c Select Numeric from the Type pull down menu d Select 4 byte Single from the Data Type pull down menu e Select Pointer to Value from the Pass pull down menu 10 Check that the Function Prototype field displays the return value and three parameters in the correct order as follows long avg_num float a long size float avg nye Note The syntax you see in the Function Prototype field is technically correct However the c file that LabVIEW generates in the next section is more precise because the first parameter appears as float a l 11 12 13 14 Using External Code in LabVIEW Click the OK button to save your settings and close the dialog box Notice how the Call Library Function Node icon updates to reflect your settings Right click the Call Library Function Node icon and select Create c file from the shortcut menu Save the file as myshared c 2 10 ni com Chapter 2 Shared Libraries DLLs B Note In this example you use a c source file When you work with C libraries change the extension of the source file to cpp Preventing C Name Decoration When you build shared libraries for C you must prevent the C compiler from decorating the function names in the final object code To do this wrap the function declaration in an ex
93. arameters Name Type Description p Path Path in which FAppPath stores the path to the current application p must already be an allocated path Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path mFullErr Insufficient memory fNotFound File not found fIOErr Unspecified I O error National Instruments Corporation 6 49 Using External Code in LabVIEW Chapter 6 Function Descriptions FArrToPath MgErr FArrToPath arr Purpose relative path Converts a one dimensional LabVIEW array of strings to a path of the type specified by relative Each string in the array is converted in order into a component name of the resulting path If no error occurs path is set to a path whose component names are the strings in arr If an error occurs path is set to the canonical invalid path Parameters Name Type Description arr UHandle DS handle containing the array of strings you want to convert to a path relative Boo132 If TRUE the resulting path is relative Otherwise the resulting path is absolute path Path Path where FArrToPath stores the resulting path This path must already have been allocated Return Value MgErr which can contain the following errors No error A bad argument was passed to the function Verify the path noErr mgArgErr mFull Using E
94. as shown in Figure 2 8 Figure 2 8 Combining Function Constants in LabVIEW National Instruments Corporation 2 27 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Using External Code in LabVIEW Determining the Proper Library and Function Name Before you can configure the call to the Win32 API you must identify the DLL that contains MessageBox and the specific name of MessageBox within the DLL Refer to the description of MessageBox in the documentation that comes with your SDK or search for MessageBox on the Microsoft Web site A Requirements section follows the function description for MessageBox and contains the following information Requirements Windows NT Requires version 3 1 or later Windows Requires Windows 98 or later Windows CE Requires version 1 0 or later Header Declared in winuser h Import Library Use user32 lib Unicode Implemented as Unicode and ANSI versions on Windows and Windows NT The Import Library line names the static library user32 1ib that you need to link to in order to build a program in the C language Every static library in the SDK has a dynamic counterpart that has the same file name but a d11 extension instead of a 1ib extension The DLL contains the actual implementation of the desired function So in this case you know that user32 d11 contains MessageBox Unicode Versions and ANSI Versions of Functions MessageBox uses two string argu
95. ascal string even if the pointers cstr and pstr refer to the same memory location If the length of estr is greater than 255 characters this function converts only the first 255 characters The function assumes pstr is large enough to contain cstr Parameters Name Type Description cstr cstr Pointer to a C string pstr PStr Pointer to a Pascal string Return Value The length of the string truncated to a maximum of 255 characters Using External Code in LabVIEW 6 44 ni com Chapter 6 Function Descriptions DateCString CStr DateCString secs fmt Purpose Returns a pointer to a string representing the date corresponding to secs seconds after January 1 1904 12 00 a m UT In SPARCstation this function accounts for international conventions for representing dates ky Note This function was formerly called DateString Parameters Name Type Description secs uInt32 Seconds since January 1 1904 12 00 a m UT fmt int32 Indicates the format of the returned date string using the following values e 0 Short date format mm dd yy where mm is a number between 1 and 12 representing the current month dd is the current day of the month 1 through 31 and yy is the last two digits of the corresponding year For example 12 31 92 e 1 Long date format dayName MonthName DayOfMonth LongYear For example Thursday December 31 1992 2 Abbreviated date format AbbrevDayNam
96. asses a pointer to the Dispatch interface of an ActiveX Automation server IUnknown Pointer passes a pointer to the Unknown interface of an ActiveX Automation server Adapt to Type Use Adapt to Type to pass arbitrary LabVIEW data types to DLLs in the same way they are passed to a CIN The arbitrary LabVIEW data types are passed to DLLs in the following ways e Scalars are passed by reference A pointer to the scalar is passed to the library e Arrays and strings are passed according to the Data Format setting You can choose from the following Data Format settings Handles by Value passes the handle to the library The handle is not NULL Pointers to Handles passes a pointer to the handle to the library If the handle is NULL treat the handle as an empty string or array To set a value when the handle is NULL you must allocate a new handle e Clusters are passed by reference National Instruments Corporation 2 7 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs e Scalar elements in arrays or clusters are in line For example a cluster containing a numeric is passed as a pointer to a structure containing a numeric e Clusters within arrays are in line e Strings and arrays within clusters are referenced by a handle 3 Note When one or more of the parameters of the function you want to call in a DLL are of types that do not exist in LabVIEW ensure that each parameter is passed to the func
97. ath 25 at 6 64 FARIS A ONO 6 65 O National Instruments Corporation ix Using External Code in LabVIEW Contents FGetAccessRights sacrer ea Rssies tides ieai airain Eaa A E ei 6 66 FGetDefGrOUp ria food ole Weasel REE 6 67 FGE OE Koreo teii uses fence did 6 68 EGO tii a 6 69 EGctPathTy Pesas ata io 6 71 FGetvVollntO A ee a eee aS 6 72 FileName CMP et adri 6 73 FileNameNdEMp it das 6 74 FileNameN mp sis a 6 75 FlsAP thriociiai dais 6 76 FISAPathOf TYPE s sieci cctvesedea artesania ric anat sent dei 6 77 FIsAPathOrNotAPath siioni naii inten crearon a do ti ib ni n ais ici 6 78 FISARC NU ia 6 79 FlsEmptyPath oionmii niia italia il decia 6 80 BRL SOD alain nia 6 81 FLockOrUnlockRange icocomosoocinccosiinca rencor ai E casgedeavecasees 6 83 BMakePathy coito ic isis 6 85 PMO OSE a di 6 86 BMO DO uuvicctii testes AA Bah E Ac eat E E A Eaa a 6 87 A O O 6 90 FMRe addict detente EEE 6 91 O O NA 6 92 BM Tell einne lee E 6 93 FM Write accio la oa E a a A iii 6 94 PINGING Sucia iii ida diles 6 95 EDNET aT ma EAEN E EPAR did E 6 96 FNewW DiN mapepe eas ra E ainda 6 97 FENewR fNUM saonenn a a a a AT R Ea ae 6 98 FNotAPath ssena aeaa ee as ened nie Beh S 6 99 PRath mips ss 4 sesi ashi vives nanana rere diria 6 100 BR ath py reciia a aden tbavtesghs ie Ml E statins waded ees EEEE ARES 6 101 A ees aishaaceganssiea oviasientandeadeasyseelate 6 102 PRath ToAZS tring caida ii idea ls A a ia eiea 6 103 PRath TODS String isisisi ioii ae eA
98. ath and returns the value If p is a path FNotAPath sets the existing path to the canonical invalid path and returns the new p The resulting path If p is not NULL the return value is the same canonical invalid path as p If an error occurs this function returns NULL National Instruments Corporation 6 99 Using External Code in LabVIEW Chapter 6 Function Descriptions FPathCmp int32 FPathCmp lsp1 lsp2 Purpose Compares two paths Parameters Name Type Description Isp1 Path First path you want to compare Isp2 Path Second path you want to compare Return Value int32 which can contain the following values Paths are of different types For example one is absolute and the other is relative 1 n 1 Using External Code in LabVIEW Paths are identical Paths have the same first n components but are not identical 6 100 ni com Chapter 6 Function Descriptions FPathCpy MgErr FPathCpy dst src Purpose Duplicates the path specified by sre and stores the resulting path in the existing path dst Parameters Name Type Description dst Path Path where FPathCpy places the resulting duplicate path This path must already have been created sre Path Path you want to duplicate Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path Nation
99. ble globally or locally respectively Each section is optional but remember that all symbols are global by default In the local section you can choose to use the wildcard rather than listing individual symbols This wildcard means any symbol not already defined as global and allows you to easily make symbol definitions in terms of symbols to be exported rather than symbols to be reduced in scope 2 16 ni com Chapter 2 Shared Libraries DLLs After you create the mapfile save it and instruct the linker to use it by appending M lt mapfile gt to the gcc command line argument list Metrowerks CodeWarrior on Mac OS Create a shared library using the process that the Metrowerks documentation describes To use this shared library with LabVIEW you must set struct alignment to 68k in the PPC Processor settings panel Be sure to export the function s that you want to call from LabVIEW Project Builder on Mac OS X Create a framework using the process described in the Project Builder documentation You must include the malign natural setting in the Other C Compiler Flags section of the GCC Compiler Settings If you want to call functions in LabVIEW from your framework you need to link against liblvexports a located in cintools Mach o Calling External APIs You might need to access external APIs from within LabVIEW code Most often you access external APIs to obtain functionality that the operating system provides Norm
100. characters after the decimal place For strings this specifies the maximum number of characters to print argument size Indicates the data size for an argument It applies only to the d o u and x conversion specifiers By default the conversion for one of the specifiers is from a 16 bit integer The flag 1 causes this conversion to convert the data so the function assumes the data is a 32 bit integer value conversion You can precede any of the numeric conversion characters x o d u b e by cc to indicate that the number is passed by reference cc can be iB iW cX depending on the corresponding numeric type If cc is an asterisk the numeric type iB through cx is an int16 in the argument list Using External Code in LabVIEW 6 150 ni com Chapter 6 Function Descriptions Conversion Specifiers These functions use the conversion specifiers listed and described in Table 6 1 Table 6 1 Conversion Specifiers and Descriptions Conversion Specifier Description b Binary integer Cc Character d Decimal integer e E Single precision floating point number in scientific notation Single precision floating point number F Double precision floating point number g G Double precision floating point number in scientific notation H String handle LStrHandle o Octal integer p Pascal string PStr P Long Pascal string LStrPtr q Point passed
101. code and passes any data wired to the CIN If you save the VI after loading the code LabVIEW saves the CIN object code along with the VI so LabVIEW no longer needs the original code to execute the CIN You can update your CIN object code with new versions at any time The examples CINs directory contains all of the examples used in this manual The names of the directories in the examples CINs directory correspond to the CIN name in the examples Complete the following specific steps to create a CIN 1 Set up input and output terminals for the CIN 2 Wire the inputs and outputs to the CIN 3 Create a c file 4 Compile the CIN source code 5 Load the CIN object code The following sections discuss each of the preceding steps Step 1 Set Up Input and Output Terminals for the CIN Using External Code in LabVIEW Place a CIN on a block diagram A CIN has terminals with which you can indicate which data passes to and from a CIN Initially the CIN has one set of terminals and you can pass a single value to and from the CIN To add additional terminals you can 3 4 ni com Chapter 3 CINs resize the node or right click the node and select Add Parameter from the shortcut menu Figure 3 1 shows how to resize the CIN to add parameters A a i l if Figure 3 1 Resizing a CIN Each pair of terminals corresponds to a parameter LabVIEW passes to the CIN The two types of terminal pairs are input output and outp
102. ct the data of the input wire To remove a pair of terminals from a CIN right click the terminal you want to remove and select Remove Parameter from the shortcut menu LabVIEW disconnects wires connected to the deleted terminal pair Wires connected to terminal pairs below the deleted pair remain attached to those terminals and stretch to adjust to the terminals new positions Step 2 Wire the Inputs and Outputs to the CIN Using External Code in LabVIEW Connect wires to all the terminal pairs on the CIN to specify the data you want to pass to the CIN and the data you want to receive from the CIN The order of terminal pairs on the CIN corresponds to the order in which parameters are passed to the code You can use any LabVIEW data types as CIN parameters so you can pass arbitrarily 3 6 ni com Chapter 3 CINs complex hierarchical data structures such as arrays containing clusters that can in turn contain other arrays or clusters to a CIN Refer to the Passing Parameters section of Chapter 4 Programming Issues for CINs for information about how LabVIEW passes parameters of specific data types to CINs Step 3 Create a c File Right click the CIN and select Create c File from the shortcut menu to create a c file in the style of the C programming language The c file describes the routines you must write and the data types for parameters that pass to the CIN For example a call to a CIN takes a 32 bit signed integer as an in
103. ction that holds all data in a VI except execution data Function that creates clusters from various types of elements A series of zero or more unsigned characters terminated by a zero used in the C programming language Original uncompiled text code See also object code Code Interface Node Special block diagram node through which you can link conventional text based code to a VI Resource containing executable machine code You link code resources to LabVIEW through a CIN A list of Pascal type strings concatenated into a single block of memory See concatenated Pascal string CPStr G 1 Using External Code in LabVIEW Glossary D data type descriptor diagram window dimension E executable icon pane IDE inplace L LabVIEW string MB MPW MSB 0 object code Using External Code in LabVIEW Code that identifies data types used in data storage and representation VI window containing the VI s block diagram code Size and structure attribute of an array A stand alone piece of code that will run or execute Region in the upper right hand corner of the front panel and block diagram windows that displays the VI icon Integrated development environment for developing computer applications for example Visual Basic Visual C and LabVIEW When the input and output data of an operation use the same memory space The string data type LStr that LabVIEW block diagrams use
104. ctiveX Adapt to Type After you select an item from the Type pull down menu you see more items you can use to indicate details about the parameter and about how to pass the data to the library function The Call Library Function Node has a number of different items for parameter types because of the variety of data types required by different libraries Refer to the documentation for the library you call to determine which parameter types to use The following sections discuss the different parameter types available from the Type pull down menu Windows Refer to the examples d11 data passing Call Native Code 11b for an example of using data types in shared libraries Numeric For numeric data types you must indicate the exact numeric type by using the Data Type pull down menu You can choose from the following data types e 8 16 and 32 bit signed and unsigned integers e 4 byte single precision numbers e 8 byte double precision numbers My Note Extended precision numbers and complex numbers can be passed by selecting Adapt to Type from the Type pull down menu However standard libraries generally do not use extended precision numbers and complex numbers Use the Pass pull down menu to indicate whether you want to pass the value or a pointer to the value Array Use the Data Type pull down menu to indicate the data type of the array You can choose from the same data types available for numeric parameters Refer to the
105. d by the backslash Indicate the path should move up a level using two periods in a row Thus the following path specifies a file README relative to the top level of the file system on a drive named c C HOME GREGG MYAPPS README The following paths are two relative paths to the same file GREGG MYAPPS README relative to the HOME directory MYAPPS README relative to a directory inside of the GREGG directory Mac OS You separate names in a path with the colon character If the path is an absolute path you begin the specification with the name of the volume containing the file If an absolute path consists of only one name that is it specifies a volume the path must end with acolon If the path is a relative path it begins with a colon The colon is optional for a relative path consisting of only one name Indicate the path should move up a level using two colons in a row Thus the following path specifies a file README relative to the top level of the file system on a drive named Hard Drive Using External Code in LabVIEW 4 30 ni com Chapter 4 Programming Issues for CINs Hard Drive Home Gregg MyApps README The following paths are two relative paths to the same file Gregg MyApps README relative to the Home directory MyApps README relative to a directory inside of the Gregg directory Empty You can de
106. data its current location might not offer enough contiguous space to hold the resulting string or array LabVIEW might have to move the data to a location that offers more space To accommodate the relocation of memory LabVIEW uses handles to refer to the storage location of variably sized data A handle is a pointer to a pointer to the desired data LabVIEW uses handles instead of simple pointers because handles allow LabVIEW to move the data without invalidating references from your code to the data If LabVIEW moves the data LabVIEW updates the intermediate pointer to reflect the new location If you use the handle references to the data go through the intermediate pointer which always reflects the correct location of the data Refer to the Using Pointers and Handles in Memory Zones section of this chapter for information about handles Refer to Chapter 6 Function Descriptions for descriptions of specific handle functions Alignment Considerations When a CIN returns variably sized data you need to adjust the size of the handle that references the array You can adjust the handle size using the memory manager routine DSSetHandleSize If the data is stored in the application zone you can use the AZSetHandleSize routine to adjust the handle size Both the DSSetHandleSize routine and the AZSetHandleSize routine work However it is difficult to calculate the size correctly in a platform independent manner because some platforms have special r
107. documentation send email to techpubseni com O 1993 2003 National Instruments Corporation All rights reserved Important Information 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 National Instruments does not warrant that the operation of the software shall be uninterrupted or error free A Return Material Authorization RMA number must be obtained from the factory and clearly marked on the outside of the package before any equipment will be accepted for warranty work National Instruments will pay the shipping costs of returning to the owner parts which are covered by warranty National Instruments believes that the information in this document is accurate The document has been carefully reviewed for technical accuracy In the event that technical or typographical errors exist National Instruments reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition The reader should consult National Instruments if errors are suspected In no event shall Nationa
108. dows case sensitive for SPARCstation This function is similar to Fi leNameCmp except you pass the function handles to the string data instead of pointers Parameters Name Type Description slp PStr Pointer to a Pascal string s2p PStr Pointer to a Pascal string Return Value lt 0 0 or gt 0 if slp is less than equal to or greater than s2p respectively Returns lt 0 if s1p is an initial substring of s2p Using External Code in LabVIEW 6 74 ni com FileNameNCmp Macro Chapter 6 Function Descriptions int32 FileNameNCmp s1 Purpose s2 n Lexically compares two file names to determine whether one is less than equal to or greater than the other limiting the comparison to n characters This comparison uses the same case sensitivity as the file system that is case insensitive for Mac OS and Windows case sensitive for SPARCstation Parameters Name Type Description sl cstr Pointer to a C string s2 CStr Pointer to a C string n uInt32 Maximum number of characters you want to compare Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an initial substring of s2 O National Instruments Corporation 6 75 Using External Code in LabVIEW Chapter 6 Function Descriptions FisAPath Bool32 FIsAPath path Purpose Determines whether path is a valid path Paramete
109. e AbbrevMonthName DayOfMonth LongYear For example Thu Dec 31 1992 Return Value The date as a C string National Instruments Corporation 6 45 Using External Code in LabVIEW Chapter 6 Function Descriptions DateToSecs uint32 DateToSecs dateRecordP Purpose Converts from a time described using the DateRec data structure to the number of seconds since January 1 1904 12 00 a m UT Parameters Name Type Description dateRecordP Return Value DateRec Pointer to a DateRec structure DateToSecs stores the converted date in the fields of the date structure referred to by dateRecordP Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter The corresponding number of seconds since January 1 1904 12 00 a m UT Using External Code in LabVIEW 6 46 ni com FAddPath Chapter 6 Function Descriptions MgErr FAddPath basePath Purpose relPath newPath Creates an absolute path by appending a relative path to an absolute path You can pass the same path variable for the new path that you use for basePath or relPath Therefore you can call this function in the following three ways err FAddPat the new pa err FAddPat the new pa h basePath relPath newPath th is returned in a third path variable h path relPath path th writes over the old base path
110. e DS e Application zone AZ National Instruments Corporation 4 25 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs LabVIEW uses the data space DS zone only to hold VI execution data LabVIEW uses the application zone AZ to hold all other data Most memory manager functions have two corresponding routines one for each of the two zones Routines that operate on the data space zone begin with Ds Routines for the application zone begin with AZ Currently the two zones are actually one zone but this might change in future releases of LabVIEW Therefore you should write applications as if the two zones actually exist External code modules work almost exclusively with data created in the DS zone although exceptions exist In most cases use the DS routines when you need to work with dynamically allocated memory All data passed to or from a CIN is allocated in the DS zone except for Path which uses AZ handles You should only use file manager functions not the AZ memory manager routines to manipulate Path Thus your CINs should use the DS memory routines when working with parameters passed from the block diagram The only exceptions to this rule are handles created using the SizeHandle function which allocates handles in the application zone If you pass a handle created using the SizeHand1e function to a CIN your CIN should use AZ routines to work with the handle Using Pointers and Handles in Memory
111. e equivalent LabVIEW data types which you can usually infer from the C data types Mapping LPCTSTR and UINT to LabVIEW is straightforward LPCTSTR is a C String and UINT is a U32 Mapping HWND is more complex Table 2 1 lists HWND as a double pointer to an integer However inspection of the function shows that MessageBox uses HWND merely as a reference number that identifies the owner of the window Because of this fact you do not need to know the integer value for which the HWND is a handle Instead you need to know the value of the HWND variable itself Because it is a double pointer and hence a pointer you can be treat it as a 32 bit unsigned integer or in LabVIEW terms a U32 Handles such as HWND are common in the Win32 SDK In LabVIEW you are almost always interested in the handle itself and not the data to which it points Therefore you can usually treat handles as U32 Handle names always begin with the letter H in the Win32 API National Instruments Corporation 2 25 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs If the SDK documentation does not make clear what C data type corresponds to a Win32 type search windef h for the appropriate define or typedef statement Table 2 2 lists the Win32 SDK data types from Table 2 1 and their corresponding LabVIEW data types Table 2 2 Mapping Win32 Data Types to LabVIEW Data Types WIN32 SDK Data Type LabVIEW Data Type HWND uInt32 LPCTSTR CStr C s
112. e exp to projectName exp where projectName is the name of the project file CodeWarrior looks in this file to determine what symbols your CIN exports LabVIEW needs these to link to your CIN National Instruments Corporation 3 11 Using External Code in LabVIEW Chapter 3 CINs Using External Code in LabVIEW e Set Project Type to Shared Library Set the file name to cinName tmp where cinName is the name of your CIN e Set Type to tmp e Set Creator to LVsb e Add your cintools folder to the list of access paths Select Project Make to build the CIN When you successfully build the cinName tmp file use the lvsbutil app application to create the cinName 1sb file In the file selection dialog box make sure the For Power PC box is checked Select any other options you want for your CIN and then select your cinName tmp file LabVIEW creates cinName 1sb in the same folder as cinName tmp Macintosh Programmer s Workshop You can use Macintosh Programmer s Workshop MPW to build CINs for Mac OS Classic The following scripts are available for the MPW environment to help you build CINs e CINMake uses a simplified form of a makefile you provide You can run it every time you need to rebuild your CIN LVMakeMake is similar to the lvmkmf LabVIEW Make Makefile script available for building CINs on UNIX This script builds a skeletal but complete makefile you can then customize and use with the MPW make tool You mu
113. ecified zone National Instruments Corporation 6 13 Using External Code in LabVIEW Chapter 6 Function Descriptions AZCopyHandle DSCopyHandle MgErr AZCopyHandle void ph MgErr DSCopyHandle void ph Purpose const void hsrc const void hsrc Copies the data referenced by the handle hsre into the handle pointed to by ph or a new handle if ph points to NULL Parameters Name Type Description ph UHandle Pointer to the handle to copy the data into This must point to a valid handle or NULL If it points to NULL a new handle is allocated hsre UHandle The handle containing the data to copy Return Value MgErr which can contain the following errors noErr mFull GJ EX mZonel Using External Code in LabVIEW BEE No error Not enough memory to perform the operation Handle or pointer not in specified zone 6 14 ni com AZDisposeHandle DSDisposeHandle Chapter 6 Function Descriptions MgErr AZDisposeHandle h MgErr DSDisposeHandle h Purpose Releases the memory referenced by the specified handle Parameters Name Type Description h UHandle Handle you want to dispose of Return Value Mg nol O National Instruments Corporation mZoneErr No error Err which can contain the following errors Handle or pointer not in specified zone Using External Code in LabVIEW Chapter 6 Function Descriptions AZDisposePtr DS
114. ects int16 Check for errors in the code of the DLL such as dereferencing a null pointer Also confirm that you are using the correct calling convention st dcall orc Make sure all the parameters are defined to be passed by the correct method such as value or pointer If you receive amemory cpp error message the cause is almost always an error in the code of the DLL such as writing past the end of the memory allocated for an array Notice that these kinds of crashes might or might not occur at the time the DLL call actually executes on the block diagram Refer to the Troubleshooting your DLL and the Troubleshooting Checklist sections of this chapter for more information about troubleshooting calls to DLLs Troubleshooting your DLL Check for the following problems in your DLL when LabVIEW calls to DLLs generate errors Using External Code in LabVIEW Remember that you need to declare the function with the _declspec dllexport keyword in the header file and the source code or define it in the exports section of the module definition file When you use the _declspec dllexport keyword and you are also using the __stdca11 calling convention you must declare the DLL function name in the EXPORTS section of the module definition def file In the absence of a def file __ st dca11 might truncate function names in an unpredictable pattern so the actual function name is unavailable to applications that call the DLL When a f
115. efines in a platform independent manner The actual data type for a path is private to the file manager and subject to change You can create and manipulate Path data types using file manager routines Memory Related LabVIEW uses pointers and handles to reference dynamically allocated memory The memory related data types have the following type definitions typedef uChar UPtr typedef uChar UHandle Refer to Chapter 6 Function Descriptions for information about the use of memory related data types with functions Constants The managers define the following constant for use with external code modules NULL 0 ulnt32 The following constants define the possible values of the Boo132 data type FALSE 0 int32 TRUE 1 int32 The following constants define the possible values of the LVBoolean data type LVFALSE 0 ulnt8 LVTRUE 1 ulnt8 Memory Manager Most applications need routines for allocating and deallocating memory on request The memory manager is a set of platform independent routines you can use to dynamically allocate manipulate and deallocate memory The LabVIEW memory manager supports dynamic allocation of both nonrelocatable and relocatable blocks using pointers and handles If you need to perform dynamic memory allocation or manipulation from external code modules use the memory manager If your external code operates on data types other than O National Instruments Corporation 4 23 Usin
116. equirements about how you align and pad memory Instead of using XXxSetHand1leSize use the LabVIEW routines that take this alignment into account when resizing handles You can use the Set CINArraySize routine to resize a string or an array of arbitrary data type Refer to the Resizing Arrays and Strings section of this chapter for information about resizing arrays The following examples highlight alignment differences for various platforms In Windows a one dimensional array of double precision floating point numbers is stored in a handle The first four bytes describe the number of elements in the array These four bytes are followed by the 8 byte elements that make up the array In Solaris and Mac OS X double precision floating point numbers must be aligned to 8 byte boundaries the 4 byte value is followed by four bytes of padding This padding makes sure the array data falls on 8 byte boundaries Ina three dimensional array of clusters each cluster contains a double precision floating point number and a 4 byte integer As in the previous example Solaris stores this array in a handle The first 12 bytes contain the number of pages rows and columns in the array These dimension fields are followed by four bytes of filler which ensures the National Instruments Corporation 4 7 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs first double precision number is on an 8 byte boundary and then the data
117. er LabVIEW stores the component cluster value as a component of the main cluster Using External Code in LabVIEW 4 2 ni com Chapter 4 Programming Issues for CINs Return Value for CIN Routines The names of the CIN routines are prefaced in the header file with the words CIN MgErr as shown in the following example code CIN MgErr CINRun The LabVIEW header file extcode h defines the word CIN to be either Pascal or nothing depending on the platform Prefacing a function with the word Pascal causes some C compilers to use Pascal calling conventions instead of C calling conventions to generate the code for the routine LabVIEW uses standard C calling conventions so the header file declares the word CIN to be equivalent to nothing The MgErr data type is a LabVIEW data type corresponding to a set of error codes the manager routines return If you call a manager routine that returns an error you can either handle the error or return the error so LabVIEW can handle it If you can handle the errors that occur return the error code noErr After calling a CIN routine LabVIEW checks the MgErr value to determine whether an error occurred If an error occurs LabVIEW aborts the VI containing the CIN If the VI is a subVI LabVIEW aborts the VI containing the subVI Aborting the running VI enables LabVIEW to handle conditions when a VI runs out of memory By aborting the running VI LabVIEW can possibly free enough memory to
118. erence a subVI and another VI with the same name already exists in memory LabVIEW references the one already in memory instead of the one you selected In the same way if you try to load references to two different code resources having the same name only one code resource is actually loaded into memory Both references to the code resources point to the same code LabVIEW can verify that a subVI call matches the subVI connector pane terminal However LabVIEW cannot verify that your source code matches the CIN call One Reference to the CIN in a Single VI The following section describes the standard case in which you have a code resource referenced by only one CIN and the VI containing the CIN is not reentrant Other cases have slightly more complicated behavior and are described in later sections of this chapter Loading a VI When you first load a VI LabVIEW calls the CINLoad routines for any CINs contained in that VI By LabVIEW calling the CINLoad routines when you first load a VI you have a chance to load any file based resources at load time because LabVIEW calls this routine only when the VI is first loaded Refer to the Loading a New Resource into the CIN section of this chapter for an exception to this rule After LabVIEW calls the CINLoad routine it calls CINInit Together CINLoad and CINInit perform any initialization you need before the VI runs LabVIEW calls CINLoad once for a given code resource regardless of the number
119. ernal Code DbgPrintf syntax Windows Using External Code in LabVIEW LabVIEW has a debugging window you can use with external code to display information at run time You can open the window display arbitrary print statements and close the window from any CIN To create this debugging window use the DogPrintf function The format for DbgPrint f is similar to the format of the SPrintf function described in Chapter 6 Function Descriptions DogPrintf takes a variable number of arguments where the first argument is a C format string int32 DbgPrintf CStr cfmt The first time you call DogPrintf LabVIEW opens a window to display the text you pass to the function Subsequent calls to DogPrintf append new data as new lines in the window You do not need to pass in the new line character to the function If you call DogPrintf with NULL instead of a format string LabVIEW closes the debugging window You cannot position or change the size of the window The following examples show how to use DbgPrintf DbgPrintf print an empty line opening the window if necessary DbgPrintf H varl print the contents of an LStrHandle LabVIEW string opening the window if necessary DbgPrintf NULL close the debugging window El Windows supports source level debugging of CINs using Microsoft s Visual C environment Complete the following steps to debug CINs in Windows 1 Modify your CIN to set
120. es data by reference to the CIN When modifying a parameter value follow the rules for each kind of terminal in the Creating a CIN section of Chapter 3 CINs LabVIEW passes parameters to the CINRun routines in the same order as you wire data to the CIN The first terminal pair corresponds to the first parameter The last terminal pair corresponds to the last parameter Scalar Numerics LabVIEW passes numeric data types to CINs by passing a pointer to the data as an argument In C this means LabVIEW passes a pointer to the numeric data as an argument to the CIN Arrays of numerics are described in the Arrays and Strings section Scalar Booleans LabVIEW stores Boolean data types in memory as 8 bit integers If any bit of the integer is 1 the Boolean data type is TRUE Otherwise the Boolean data type is FALSE LabVIEW passes Boolean data types to CINs with the same conventions it uses for numerics nye Note In LabVIEW 4 x and earlier Boolean data types were stored as 16 bit integers If the high bit of the integer was 1 it was TRUE Otherwise the Boolean data type was FALSE Refnums LabVIEW treats a refnum the same way as a scalar number and passes refnums with the same conventions it uses for numbers Clusters of Scalars For a cluster LabVIEW passes a pointer to a structure containing the elements of the cluster LabVIEW stores fixed size values directly as components inside of the structure If a cluster component is another clust
121. esreersseee 6 2 File Manager Functions and Operations sssseeseeseseerereeresrsresreresresrsersresresree 6 3 Support Manager Functions oooooncononnnonnononancnnonononnnonncnonnnonno nn a ae aereoa aoni 6 6 Mathematical Operations tessy pieuse ai eE E R EAEEREN crac 6 8 Individual Function Descriptions 00 0 0 cece eeeeseceeeeseeseeesecsceeaecesceaecseceaeeseesaesnseeaeeeaes 6 9 ADS ai tai 6 10 ASCITES a a n r ti 6 11 AZCheckHandle DSCheckHandle ooooonconicnncnnononnncnnnnnncnnonnncnnonononnccnncnncrnncnnos 6 12 AZCheckPtr DS CheckPtt rrano a costaria EAGT das 6 13 AZCopyHandle DSCopyHandle oooconncnnnconcnononononnnconcnnnonncono cono nn non conc can crnncnnos 6 14 AZDisposeHandle DSDisposeHandle ooccnonnncnnocnnonconononcnnnoncconncnncnnccnncnnccnnos 6 15 AZDisposePtt DS DisposePt me rere oraa ai n c nn cnn no nn non conc cnn a a 6 16 AZGetHandleSize DSGetHandleSize ooococonicnnnnnocnnoncnnonnnnoncnnnconcnnconccancrnnonnos 6 17 Using External Code in LabVIEW viii ni com Contents AZHeapCheck DSHeapChe ck oooooccnnnconcnononononnnconcnnnnnnonnnoncconnnnnonncrnncnncrnnonnoss 6 18 Va VA E l ok iii ad 6 19 AZHN O PUPS G3 eset dee e AA A ea 6 20 AZA PU E ii RIS eee RNA Bate eet aaa aa 6 21 AZHUM OCK ica in tits 6 22 AZMaxMem DSMaxMem ccccsccccecssssscecceesssseecccesssaeeccecessaseeceeeesseeeesesens 6 23 AZMemStats DSMemStat ccccccccccssssccceeessseecccesssssecceeessseeceessseeeesenes 6 24 AZNewHandle D
122. estPSt CStr cfmt int32 PPrintfp PStr destPSt PStr pfmt int32 FPrintf File destFile CStr cfmt MgErr LStrPrintf LStrHandle destLsh CStr cfmt Purpose These functions format data into an ASCII format to a specified destination A format string describes the desired conversions These functions take a variable number of arguments Each argument follows the format string paired with a conversion specification embedded in the format string The second parameter cfmt or pfmt must be cast appropriately to either type CStr or PStr SPrintf and SPrintfp SPrintf prints to a C string just like the C library function sprintf sprintf returns the actual character count and appends a NULL byte to the end of the destination C string SPrint fp is the same as SPrintf except the format string is a Pascal string instead of aC string As with SPrintf SPrintfp appends a NULL byte to the end of the destination C string If you pass NULL for destCStr SPrintf and SPrint fp do not write data to memory SPrintf and SPrintfp return the number of characters required to contain the resulting data not including the terminating NULL character PPrintf and PPrintfp PPrintf prints to a Pascal string with a maximum of 255 characters PPrint sets the length byte of the Pascal string to reflect the size of the resulting string PPrint does not append a NULL byte to the end of the string PPrint fp is the same as PPrintf except
123. etCINArraySize takes into account any padding and alignment needed for the data structure However SetCINArraySize does not update the dimension fields in the array If you successfully resize the array you need to update the dimension fields to correctly reflect the number of elements in the array You can resize numeric arrays more easily with NumericArrayResize Pass to the NumericArrayResize function the array you want to resize a description of the data structure and information about the new size of the array Consider the following issues when you resize arrays of variably sized data such as arrays of strings with the SetCINArraySize or NumericArrayResize routines e If the new size of the array is smaller LabVIEW disposes of the handles used by the disposed element Neither SetCINArraySize nor NumericArrayResize sets the dimension field of the array You must set the dimension field of the array in your code after the function call e Ifthe new size of the array is larger LabVIEW does not automatically create the handles for the new elements You have to create these handles after the function returns Refer to Chapter 6 Function Descriptions for more information about the SetCINArraySize and NumericArrayResize routines Examples with Variably Sized Data The following examples describe how to create CINs that work with variably sized data types Refer to Chapter 3 CINs for more information about creating CINs Conca
124. ets the Boolean output to FALSE and returns through the 32 bit integer output the position the single cluster now occupies in the new array of clusters This example shows only the front panel block diagram and source code Complete the following steps to create the CIN 1 Follow the instructions in the Creating a CIN section of Chapter 3 CINs to create the CIN Figure 4 7 shows the front panel for this VI Figure 4 7 tblsrch vi Front Panel Figure 4 8 shows the block diagram for this VI array of clusters ew array of clusters Figure 4 8 tbisrch vi Block Diagram 2 Save the VI as tblsrch vi 3 Create the c file and save it as tblsrch c The following code is the source code for tblsrch c with the CINRun routine added CIN source file ef tinclude extcode h define ParamNumber 0 The array parameter is parameter 0 National Instruments Corporation 4 15 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs typedefs ef typedef struct int16 number LStrHandle string TD2 typedef struct int32 dimSize TD2 arg1 1 TD1 typedef TD1 TD1HdA1 CIN MgErr CINRun TD1HdA1 clusterTableh TD2 elementp LVBoolean presentp int32 positionp CIN MgErr CINRun TD1Hd1 clusterTableh TD2 elementp LVBoolean presentp int32 positionp int32 size i MgErr err noErr TD2 tmpp LStrHandle newStringh TD2 newElementp
125. ey Uptr Pointer to the data for which you want to search compareProcP ProcPtr Comparison routine you want BinSearch to use to compare array elements BinSearch passes this routine the addresses of two elements that it needs to compare Return Value The position in the array where the data is found with 0 being the first element of the array if it is found If the data is not found BinSearch returns i 1 where i is the position where key should be placed Using External Code in LabVIEW ni com BlockCmp Chapter 6 Function Descriptions int32 BlockCmp pl Purpose numBytes Compares two blocks of memory to determine whether one is less than equal to or greater than the other Parameters Name Type Description pl UPtr Pointer to a block of memory p2 UPtr Pointer to a block of memory numBytes int32 Number of bytes you want to compare Return Value A negative number zero or a positive number if p1 is less than equal to or greater than p2 respectively National Instruments Corporation 6 33 Using External Code in LabVIEW Chapter 6 Function Descriptions Cat4Chrs Macro int32 Cat4Chrs a b c d Purpose Constructs an int32 parameter from four uInt8 parameters with the first parameter as the high byte and the last parameter as the low byte Parameters Name Type Description a uInt8 High order byte of the high word of the resul
126. f clusters The memory manager routine DSCopyHand1e creates a new handle containing the same string as the one in the single cluster you passed to the CIN CINRun increases the size of the array of clusters using SetCINArraySize and fills the last position in the new array of clusters with a copy of the single cluster you passed to the CIN If the SetCINArraySize call fails the CIN returns the error code returned by the manager If the CIN is unable to resize the array LabVIEW disposes of the duplicate string handle Refer to Chapter 6 Function Descriptions for information about CINRun LStrCmp DSCopyHandle and SetCINArraySize O National Instruments Corporation 4 17 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs Manager Overview LabVIEW has a large number of external functions that you can use to perform simple and complex operations These functions organized into libraries called managers range from low level byte manipulation to routines for sorting data and managing memory All manager routines described in this chapter are platform independent If you use the manager routines you can create external code that works on all platforms that LabVIEW supports LabVIEW contains the following manager functions e Memory manager e File manager e Support manager To achieve platform independence data types should not depend on the peculiarities of various compilers For example the C language does not defi
127. f path is NULL this function allocates and returns a new path Otherwise path is set to the new path and this function returns path If an error occurs or path is not specified correctly the function returns NULL When you finish using a path dispose of it using FDestroyPath Parameters Name Type Description path Path Parameter in which FMakePath returns the new path if path is not NULL type int32 Type of path you want to create If AbsPath the new path is absolute If RelPath the new path is relative volume directory PStr PStr Optional Pascal string containing a legal volume name An empty string indicates to go up a level in the path hierarchy This parameter is used only for absolute paths in Mac OS or Windows Optional Pascal string containing a legal directory name An empty string indicates to go up a level in the path hierarchy name PStr Optional File or directory name An empty string indicates to go up a level in the path hierarchy NULL PStr Marker indicating the end of the path Return Value The resulting path If you specified path the return value is the same as path If an error occurs this function returns NULL O National Instruments Corporation Using External Code in LabVIEW Chapter 6 Function Descriptions FMClose MgErr FMClose fd Purpose Closes the file associated with the file descript
128. files are the LIBRARY statement and the EXPORT statement The LIBRARY statement must be the first statement in the file The name you specify in the LIBRARY statement identifies the library in the import library of the DLL e The names you specify in the EXPORTS statement identify the functions that the DLL exports Note Instead ofa def file many Windows programmers use the LINK option in Project Settings of the Visual C compiler to obtain equivalent command line options for most module definition statements 2 36 ni com Chapter 2 Shared Libraries DLLs Array and String Options This section reviews important concepts regarding array and string data in the Call Library Function Node Windows Refer to the examples dll data passing Call Native Code 11b for an example of using arrays and strings in shared libraries Arrays of Numeric Data Arrays of numeric data can be comprised of any type of integers or floating point numbers with single 4 byte or double 8 byte precision When you pass an array of data to a DLL function you can pass the data as an Array Data Pointer as a LabVIEW Array Handle or as a LabVIEW Array Handle Pointer Array Data Pointers have the following characteristics whether you pass the Array Data Pointers in the Windows API or in another API e You can set the number of dimensions in the array but you must not include information about the size of the array dimension s Instead y
129. fine a path with no names called an empty path An empty path is either absolute or relative The empty absolute path is the highest point you can specify in the file hierarchy The empty relative path is a path relative to an arbitrary location in the file system to itself UNIX A slash represents the empty absolute path The slash specifies the root of the file hierarchy A period represents the empty relative path Windows You represent the empty absolute path as an empty string The empty absolute path specifies the set of all volumes on the system A period represents the empty relative path Mac 0S The empty absolute path is represented as an empty string The absolute path specifies the set of all volumes on the system A colon represents the empty relative path LabVIEW In LabVIEW you specify a path using a special LabVIEW data type represented as Path The exact structure of the Path data type is private to the file manager You create and manipulate the Path data type using file manager routines A Path is a dynamic data structure Just as you use memory manager routines to allocate and deallocate handles and pointers you use file manager routines to create and deallocate a Path Just as with handles declaring a Path variable does not actually create a Path Before you can use the Path to manipulate a file you must dynamically allocate the Path using file manager routines When you are finished using the Path
130. following example code with optional parameters listed in brackets CINMake MakeOpts opts RShell dbg noDelete lt name of your CIN gt MakeOpts opts specifies extra options to pass to make Rshell The Rshe11 option to CINMake causes the make commands to execute in ToolServer rather than in the MPW Shell Having the make commands execute in ToolServer is useful if you want to be able to issue other MPW commands before the make commands have been completed for example if the CIN takes a long time to compile dbg If this argument is specified CINMake prints statements describing what it does noDelete If this argument is specified CINMake does not delete temporary files used when making the CIN You can use LVMakeMake to build an MPW makefile that you can then customize You should only have to run LVMakeMake once for each CIN You can modify the resulting makefile by adding the proper header file dependencies or by adding other object files to be linked into your CIN The format of a LVMakeMake command is shown in the following example code with optional parameters listed in brackets LVMakeMake o makeFile lt name of your CIN gt make 0 makeFile indicates the name of the output makefile If this argument is not specified LVMakeMake writes to standard output For example to build a Mac OS Classic makefile for a CIN named myCIN use the following command LVMakeMake myCIN gt myCIN ppc make
131. following values 1 Using External Code in LabVIEW Badly formed path Path is the root directory Path is in the root directory Path is in a subdirectory of the root directory one level from the root directory Path is n 2 levels from the root directory Path is n 1 levels from the root directory ni com Chapter 6 Function Descriptions FDestroyPath void FDestroyPath amp pp Purpose Release the memory of an allocated path and NULL the path pointer Parameters Name Type Description pp Path A pointer to the path you want to deallocate Return Value None Sy Note This function replaces the older FDisposePath function The older function is still available but its use is discouraged By passing a pointer to the path instead of the path directly the FDestroyPath function can properly NULL out the path thus preventing double deallocation errors The new function can also handle NULL paths eliminating the need to check for NULL prior to calling FDisposePath A typical use of the new function is illustrated by the following text Path p p FNotAPath NULL insert code here that uses the path FDestroyPath amp p p NULL at this point National Instruments Corporation 6 59 Using External Code in LabVIEW Chapter 6 Function Descriptions FDirName MgErr FDirName path dir Purpose Creates a path for the parent directory of a specified path You ca
132. ft Visual C 6 0 on 32 bit on Windows Platforms This section discusses how to set up a project that compiles myshared c and generates myshared d1l Adding the DLL Export Keyword You must explicitly export each function from your DLL to make it available to LabVIEW For this example you should use the _declspec dllexport keyword to export the avg_num function _declspec dllexport is a Microsoft specific extension to the C or C language By declaring the dllexport keyword you eliminate the need for a module definition file Refer to the Module Definition Files section of this chapter for information about module definition files Open myshared c and insert the _declspec dllexport keyword in front of the code for avg_num This function also has a declaration statement and you must place the keyword in front of the declaration too The following excerpt shows the two places in myshared c that require the _declspec dllexport keyword _declspec dllexport long avg_num float al long size float avg _declspec dllexport long avg_num float a long size float avg National Instruments Corporation 2 13 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Setting Up the Project You set up your project in the Microsoft Visual C integrated development environment Complete the following steps to set up a project for myshared c 1 Select File New and select Win32 Dynamic Link Library DLL in the listbo
133. fy any problems sooner e When calling a LabVIEW DLL that passes a 2D array you must first declare the handler variable and initialize the variable to NULL as shown in the following C code main Labview data handler variable for the array TD1Hd1 myArray NULL Call to the Labview DLL function DLLFunctionalCall amp myAray If you do not initialize the handler variable to NULL the code produces aGeneral Protection Fault when you call the DLL National Instruments Corporation 2 33 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Refer to the Troubleshooting the Call Library Function Node and the Troubleshooting Checklist sections of this chapter for more information about troubleshooting calls to DLLs Troubleshooting Checklist Complete the following checklist to eliminate many potential problems from LabVIEW VIs that call DLLs Using External Code in LabVIEW a a a The Call Library Function Node uses the proper calling convention Cor__stdcal1 The version of your DLL matches the version of LabVIEW Call Library Function Node has the correct path to the DLL DLLs providing secondary DLLs additional functions are in the same directory as the DLL needing the additional functions or are in a directory that is in the search path The Call Library Function Node has the correct spelling syntax and case sensitivity for the function name that you are calling Othe
134. g External Code in LabVIEW Chapter 4 Programming Issues for CINs scalars you should understand how LabVIEW manages memory and know which utilities manipulate data The following code shows how the memory manager defines generic handle and pointer data types typedef uChar UPtr typedef uChar UHandle Memory Allocation 3 Applications use the following types of memory allocation e Static e Dynamic Note You can allocate memory using malloc inside a CIN However assign the pointer that results from the malloc call to a variable that is local to the CIN code rather than to a variable passed from the LabVIEW block diagram Use the LabVIEW memory manager functions if you want to create or resize memory associated with a variable passed from the LabVIEW block diagram Static Memory Allocation With static memory allocation the compiler determines memory requirements when you create an application When you launch the application LabVIEW creates memory for the known global memory requirements of the application The memory LabVIEW creates remains allocated while the application runs Static memory allocation is simple to work with because the compiler handles all the details However static memory allocation cannot address the memory management requirements of most real world applications because you cannot determine most memory requirements until run time Also statically declared memory might result in larger memory requi
135. g function using a mode of 0 For example this function might return Tuesday Dec 22 1992 5 30 In SPARCstation this function accounts for international conventions for representing dates Parameters Name Type Description secs Return Value uInt32 The date and time as a C string O National Instruments Corporation 6 11 Seconds since January 1 1904 12 00 a m UT Using External Code in LabVIEW Chapter 6 Function Descriptions AZCheckHandle DSCheckHandle MgErr AZCheckHandle h MgErr DSCheckHandle h Purpose Verifies that the specified handle is a handle If it is not a handle this function returns mZonekErr Parameters Name Type Description h Return Value Uhandle Handle you want to verify MgErr which can contain the following errors noErr mZoneErr Using External Code in LabVIEW No error Handle or pointer not in specified zone ni com Chapter 6 Function Descriptions AZCheckPtr DSCheckPtr Mg Mg Err AZCheckPtr p Err DSCheckPtr p Purpose Verifies that the specified pointer is allocated with XXNewPtr or XXNewPC1r If it is not a pointer this function returns mZoneErr Parameters Name Type Description p UPtr Pointer you want to verify Return Value MgErr which can contain the following errors noErr No error mZoneErr Handle or pointer not in sp
136. gErr which can contain the following errors No error noErr mgArgE mFullE 10 Using External Code in LabVIEW Err A bad argument was passed to the function Verify the path Insufficient memory Unspecified I O error 6 104 ni com FPathToPath Chapter 6 Function Descriptions MgErr FPathToPath p Purpose Duplicates a path and returns the new path in the same variable Parameters Name Type Description p Path Address of the path you want to duplicate Return Value MgErr which can contain the following error noErr mgArgErr National Instruments Corporation No error Variable to which FPathToPath returns the resulting path Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter A bad argument was passed to the function Verify the path 6 105 Using External Code in LabVIEW Chapter 6 Function Descriptions FRefNumToFD MgErr FRefNumToFD refNum fdp Purpose Gets the file descriptor associated with the specified file refnum If no error occurs the resulting file descriptor is stored in the address referred to by fdp If an error occurs NULL is stored in the address referred to by fdp and the error is returned Parameters Name Type Description refNum LVRefNum The file refnum whose associated file descriptor you want to get fdp File Address at which FRefNumT
137. ge of this type of string storage is that NULL characters are allowed in the string Strings are virtually unlimited in length up to 23 characters This method of string storage is illustrated in Figure 2 12 If you pass a LabVIEW String Handle from the Call Library 2 38 ni com Chapter 2 Shared Libraries DLLs Function Node to the DLL then you can use the LabVIEW CIN functions such as DSSetHandleSize to resize the LabVIEW String Handle Remember you must add the correct Lab VIEW library file to your project Refer to Table 2 4 for a list of LabVIEW library files and the compilers with which they are used The Pascal string format is nearly identical to the LabVIEW string format but instead of storing the length of the string as a 32 bit signed integer the string length is stored as an 8 bit unsigned integer Storing the string length as an 8 bit unsigned integer limits the length of a Pascal style string to 255 characters A Pascal string that is n characters long will require n 1 bytes of memory to store Figure 2 13 illustrates a Pascal string 04 t e x t String String Data Length Figure 2 13 Pascal String Format C strings are probably the type of strings you will deal with most commonly The similarities between the C style string and normal numeric arrays in C becomes much more clear when you see that C strings are declared as char where char is typically an 8 bit unsigned integer
138. ght laws this publication may not be reproduced or transmitted in any form electronic or mechanical including photocopying recording storing in an information retrieval system or translating in whole or in part without the prior written consent of National Instruments Corporation Trademarks CVI LabVIEW National Instruments NI and ni com are trademarks of National Instruments Corporation Product and company names mentioned herein are trademarks or trade names of their respective companies Patents For patents covering National Instruments products refer to the appropriate location Help Patents in your software the patents txt file on your CD or ni com patents WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS 1 NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT INJURY TO A HUMAN 2 IN ANY APPLICATION INCLUDING THE ABOVE RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE IMPAIRED BY ADVERSE FACTORS INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY COMPUTER HARDWARE MALFUNCTIONS COMPUTER OPERATING SYSTEM SOFTWARE FITNESS FITNESS OF COMPILERS AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION INSTALLATION ERRORS SOFTWARE AND HARD
139. han the other This comparison ignores differences in case This function is similar to PStrCaseCmp except you pass the function handles to the string data instead of pointers Parameters Name Type Description slp PStr Pointer to a Pascal string s2p PStr Pointer to a Pascal string Return Value lt 0 0 or gt 0 if slp is less than equal to or greater than s2p respectively Returns lt 0 if s1p is an initial substring of s2p National Instruments Corporation 6 147 Using External Code in LabVIEW Chapter 6 Function Descriptions PPStrCmp int32 PPStrCmp sip Purpose Lexically compares two Pascal strings and determines whether one is less than equal to or greater than the other This comparison is case sensitive This function is similar to PSt rCmp except you pass the function handles to the string data instead of pointers Parameters Name Type Description slp PStr Pointer to a Pascal string s2p PStr Pointer to a Pascal string Return Value lt 0 0 or gt 0 if slp is less than equal to or greater than s2p respectively Returns lt 0 if s1p is an initial substring of s2p Using External Code in LabVIEW 6 148 ni com Printf Chapter 6 Function Descriptions SPrintf SPrintfp PPrintf PPrintfp FPrintf LStrPrintf int32 SPrintf CStr destCSt CStr cfmt int32 SPrintfp CStr destCst PStr pfmt int32 PPrintf PStr d
140. hat is Thread Safe oooconcnnnnocnncnconcnoncononancnnonnncnnornncnnonnncnncnnnons 3 3 Creating a CIN si e ra N aA atada iii 3 4 Step 1 Set Up Input and Output Terminals for the CIN eee 3 4 Input Output Terminals 00 00 ea aa 3 5 Output Only TerminalS oononcninnnonincnnonnnancnnnonnnanonnnonncrnncnn can ccanonnnono 3 6 Step 2 Wire the Inputs and Outputs to the CIN oooonconccnoconacconanncnncnnncnncnnnono 3 6 Step 3 Created so Bile iii asa 3 7 Step 4 Compile the CIN Source Code oocoooconoccoconocconnconcnnccnncnnnonanonccnnonanonnonnno 3 9 MacOS Xt a eiii 3 9 Mac OS Clas IC usuaris 3 10 Microsoft WiNdOWS oooooccocononconononconncononnccnonnnonnonnnonnonn non conan cnc rn ncnnons 3 15 Using External Code in LabVIEW vi ni com Contents SA 55 ssa vesSeccasvavess eens sends oaeavashoeongcetevautes stapuacs dues eeaes yrewbiteceianvs 3 17 LUX da ad Ba 3 18 per Compiler temita ici 3 18 Step 5 Load the CIN Object Code oooconccnocncoccononoconnconnconcnononaconcconcrnncnnonnncnnonos 3 19 LabVIEW Manag r ROUUNES curia dato os 3 19 Point rs as Parameters iiccsccciicssccslaces ea dada sonido daa bad 3 20 Debugging External Codec tard ria 3 22 DOPANTE oaie tradi inicia 3 22 MI a e US 3 22 UN umi ideada topado date nicdandat n 3 24 Chapter 4 Programming Issues for CINs Passing Parmalat iia lidera 4 1 Parameters in the CIN c File io a n a a e a 4 1 Passing Fixed Size Data to CINS ooooonccconnonnconconncononnnonncn
141. he handle This example shows only the simplest aspects of how to work with pointers and handles in C Other examples throughout this manual show different aspects of using pointers and handles Refer to a C manual for a list of other operators you can use with pointers and for more information about how to work with pointers File Manager The file manager supports routines for opening and creating files reading data from and writing data to files and closing files In addition you can manipulate the end of file mark of a file and position the current read or write mark to an arbitrary position in the file You also can move copy and rename files determine and set file characteristics and delete files The file manager contains a number of routines for directories with which you can create and delete directories You also can determine and set directory characteristics and obtain a list of a directory s contents LabVIEW supports concurrent access to the same file so you can have a file open for both reading and writing simultaneously When you open a file you can indicate whether you want the file to be read from and written to concurrently You also can lock a range of the file if you need to make sure a range is nonvolatile at a given time The file manager also provides many routines for manipulating paths or path names in a platform independent manner The file manager supports the creation of path descriptions which are eithe
142. hen the user closes the VI containing the CIN For these situations you can write routines that LabVIEW calls at predefined times or when the node executes Specifically LabVIEW calls certain routines when the VI containing the CIN is loaded saved closed aborted or compiled You generally use these routines in CINs that perform an ongoing task such as accumulating results from call to call so you can allocate initialize and deallocate resources at the correct time Most CINs perform a specific action at run time only To create a CIN you must be an experienced C developer Also because CINs are tightly coupled with LabVIEW restrictions exist about which compilers you can use After you write your first CIN as described in this manual writing new CINs is relatively easy The work involved in writing new CINs is mostly in coding the algorithm because the interface to LabVIEW remains the same regardless of the development system Using the Flatten To String Function Using External Code in LabVIEW The Flatten To String function takes LabView data and converts it into a string This string when used in conjunction with the various communication functions or I O functions can be stored in a file or database or be sent to other computers 1 4 ni com Chapter 1 Introduction The string created by the Flatten To String function is a LabVIEW string LabVIEW strings have a 4 byte number which is a 32 bit signed integer data t
143. i com Chapter 3 CINs FMTell SecsToDate FMWrite NumericArrayResize You must allocate space for this return value The following examples illustrate incorrect and correct ways to call one of these functions from within a generic function foo Incorrect example foo Path path PStr p an uninitialized pointer File fd an uninitialized pointer MgErr err err FNamePtr path p FMOpen fd path openReadOnly denyWriteOnly err In the incorrect example p is a pointer to a Pascal string but the pointer is not initialized to point to any allocated buffer FNamePtr expects its caller to pass a pointer to an allocated space and writes the name of the file referred to by path into that space Even if the pointer does not point to a valid place FNamePtr writes its results there with unpredictable consequences Similarly FMOpen writes its results to the space to which fa points which is not a valid place because fd is uninitialized Correct example foo Path path Str255 buf allocated buffer of 256 chars File fd MgErr err err FNamePtr path buf err FMOpen amp fd path openReadOnly denyWriteOnly In the correct example buf contains space for the maximum sized Pascal string whose address is passed to FNamePtr fd is a local variable allocated space for a file descriptor National Instruments Corporation 3 21 Using External Code in LabVIEW Chapter 3 CINs Debugging Ext
144. ial substring of s2 Using External Code in LabVIEW 6 170 ni com StrNCmp Chapter 6 Function Descriptions int32 StrNCmp sl Purpose n Lexically compares two strings to determine whether one is less than equal to or greater than the other limiting the comparison to n characters Parameters Name Type Description sl cstr Pointer to a C string s2 CStr Pointer to a C string n uInt32 Maximum number of characters you want to compare Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an initial substring of s2 O National Instruments Corporation 6 171 Using External Code in LabVIEW Chapter 6 Function Descriptions StrNCpy CStr StrNCpy dst Purpose n Copies the C string sre to the C string dst If the source string is less than n characters the function pads the destination with NULL characters If the source string is greater than n only n characters are copied This function assumes dst is large enough to contain sre Parameters Name Type Description dst cstr Pointer to a C string src CStr Pointer to a C string n int32 Maximum number of characters you want to copy Return Value A copy of the destination C string pointer Using External Code in LabVIEW 6 172 ni com SwapBlock Chapter 6 Function Descriptions void SwapBlock ps Pur
145. ied I O error National Instruments Corporation 6 97 Using External Code in LabVIEW Chapter 6 Function Descriptions FNewRefNum MgErr FNewRefNum path fd refNumPtr Purpose Creates a new file refnum for an open file with the name and location specified by path and the file descriptor fd If the file refnum is created the resulting file refnum is stored in the address referred to by refNumPtr If an error occurs NULL is stored in the address referred to by refNumPtr and the error is returned Parameters Name Type Description path Path Path of the open file for which you want to create a file refnum fd File File descriptor of the open file for which you want to create a file refnum refNumPtr LVRefNum Address at which FNewRefNunm stores the new file refnum Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path mFullErr Insufficient memory Using External Code in LabVIEW 6 98 ni com FNotAPath Chapter 6 Function Descriptions Path FNotAPath p Purpose Creates a path that is the canonical invalid path Parameters Name Type Description p Path Path allocated by FNotAPath If NULL Return Value FNotAPath allocates a new canonical invalid p
146. iii 6 104 FPa thToPath uni ases 6 105 FREENUMTORD 5 moro die 6 106 FERetNumToP aiii dada 6 107 FRelPath cistitis 6 108 ERE MOV Vii caida 6 109 FBSetAccessRights visa apa 6 110 A NO 6 111 ESCtIDLO casitas it ds 6 112 ESetPathT peinada 6 114 O uence caetsspedbeseesgacenatesptanedansa shitesca eg oehaes eaeteteceeces ats 6 115 Using External Code in LabVIEW X ni com Contents EStimgToPath ius iii data 6 116 PY EXtlOP ath ui do iaa 6 117 FUnFlattenBatO iii tt tia 6 118 FVOINaMme iii ias 6 119 GEALON eiii iii 6 120 Hex Chad A aa 6 121 Oi tit ii IA rt 6 122 HUB yleza ln ei ia 6 123 HINDI ae ee ee 6 124 ISA Plica a 6 125 A ON 6 126 II OO 6 127 WSU Pp iii 6 128 Dolina 6 129 LOB te civic iii ia iia 6 130 DO cocoa ricas Un ano ARO cacon nassib 6 131 EoNtbble Srei nnn a a aa aa Aa AE E EA R E AA AA 6 132 ES BUT e orai ankoraa aaa a S ASE o r EE AER a 6 133 ESTE siii e e A E a a a a 6 134 O EERE E E E EE 6 135 LToPS usais a SA end a ad 6 136 Marcada tds la 6 137 Mill airis iia 6 138 Mii a a da 6 139 MoveBlockK cicle dado vid Ender 6 140 Numeric Array Resize sa iineoae sat seca cova a tdci 6 141 OC CUTS iiss ainan a Ras avte dane a tea tuade ct os baccucdacduan an A a Seats 6 143 Osuna pa 6 144 Pri ds 6 145 Post VUscrEvent ui diia 6 146 PPStrCaseCmp iii ici 6 147 A nagtanades cap adeaees sas E sraeeaeees aaah 6 148 PO aid 6 149 PStDltinaciaic ia 6 152 PStrCaseCMP iii iaa as 6 153 PSCA luciana oi apa sates 6 154 PStrEMp inn 6 15
147. ile 6 Select Project Settings and click the C tab of the Project Settings dialog box and make the following settings Select Code Generation from the Category pull down menu b Set the Struct member alignment control to 1 Byte for this example and for all configurations c Select Debug Multithreaded DLL from the Use run time library pull down menu to apply the Win32 Debug configuration as shown in Figure 2 4 General Debug C C Category Code Generation y Ees Link Resources MID if TO w Processor Use run time library Blend A Debug Multithreaded Single Threaded Calling convention Multithreaded x y Multithreaded DLL cdecl Debug Single Threaded Debug Multithreaded Debug Multithreaded DLL Figure 2 4 Setting the Use run time library Control Microsoft Visual C You have the option to choose the Win32 Release configuration instead In that case you select Multithreaded DLL in the Use run time library control 7 Select Build Build myshared dll to cause Visual C C to build a DLL and place it in either the Debug or Release output directory depending on which configuration option you selected in step 6c In the Example 1 Call a Shared Library that You Built section you call this DLL from LabVIEW National Instruments Corporation 2 15 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Gnu C or C Compilers on Solaris or Linux Use the fo
148. in UNIX Windows Permissions are ignored for directories For files only bit 7 the UNIX user write permission bit is used If this bit is clear the file is read only Otherwise you can write to the file Mac OS All nine bits are used for directories folders The bits which control read write and execute permissions respectively in UNIX are used to control See Files Make Changes and See Folders access rights respectively in Mac OS File Manager Functions and Operations You can perform the following operations by using the functions listed National Instruments Corporation Current position mark positioning FMSeek FMTell Default access rights information getting FGetDefGroup Directory contents creating and determining FbListDir FNewDir End of file mark positioning FGetEOF FSetEOF File data to disk flushing FFlush 6 3 Using External Code in LabVIEW Chapter 6 Function Descriptions Using External Code in LabVIEW File operations performing basic FCreate FCreateAlways FMClose FMOpen FMRead FMWrite File range locking FLockOrUnlockRange File refnums manipulating FDisposeRefNum FlsARefNum FNewRefNum FRefNumToFD FRefNumToPath File directory and volume information determination FExists FGetAccessRights FGetInfo FGetVolInfo FSetAccessRights FSet
149. ing that CIN is not reentrant choose either method 5 10 ni com Chapter 5 Advanced Applications Using Code Globals The following code averages using code globals CIN source file 7 include extcode h float64 gTotal int32 gNumElements CIN MgErr CINRun float64 new_num float64 avg CIN MgErr CINRun float64 new_num float64 avg gTotal new_num gNumElements avg gTotal gNumElements return noErr CIN MgErr CINLoad RsrcFile rf gTotal 0 gNumElements 0 return noErr The variables are initialized in CINLoad If the variables are dynamically created that is if they are pointers or handles you can allocate the memory for the pointer or handle in CINLoad and deallocate it in CINUnload You can allocate and deallocate the memory using CINLoad and CINUnload because CINLoad and CINUnload are called only once regardless of the number of references to the code resources and the number of data spaces This example does not use the UseDefaultCINLoad macro because this c file has a CINLoad function National Instruments Corporation 5 11 Using External Code in LabVIEW Chapter 5 Advanced Applications Using CIN Data Space Globals The following code uses CIN data space globals to perform the averaging FA CIN source file include extcode h typedef struct float64 total int32 numElements dsGlobalStruct CIN MgErr CINInit
150. ing the following values e Start tThe first byte to lock or unlock is located offset bytes from the start of the file offset must be greater than or equal to 0 e fCurrent The first byte to lock or unlock is located offset bytes from the current position mark offset can be positive 0 or negative e f End The first byte to lock or unlock is located offset bytes from the end of the file offset must be less that or equal to 0 offset int32 The position of the first byte to lock or unlock The position is the number of bytes from the beginning of the file the current position mark or the end of the file as determined by mode count int32 Number of bytes to lock or unlock starting at the location specified by mode and offset lock Boo132 Indicates whether FLockOrUnlockRange locks or unlocks a range of bytes If TRUE the function locks a range If FALSE the function unlocks a range O National Instruments Corporation 6 83 Using External Code in LabVIEW Chapter 6 Function Descriptions Return Value MgErr which can contain the following error noErr No error fIOErr Unspecified I O error Using External Code in LabVIEW 6 84 ni com FMakePath Chapter 6 Function Descriptions Path FMakePath path type volume directory directory name NULL The brackets indicate that the volume directory and name parameters are optional Purpose Creates a new path I
151. int32 free ViInfoRec Return Value size in bytes of a volume number of bytes used on volume number of bytes available for use on volume A bad argument was passed to the function Verify the path or MgErr which can contain the following errors noErr No error mgArgErr fIOErr Unspecified I O err Using External Code in LabVIEW 6 72 ni com FileNameCmp Macro Chapter 6 Function Descriptions int32 FileNameCmp s1 Purpose S2 Lexically compares two file names to determine whether one is less than equal to or greater than the other This comparison uses the same case sensitivity as the file system that is case insensitive for Mac OS and Windows case sensitive for SPARCstation Parameters Name Type Description sl PStr Pointer to a Pascal string s2 PStr Pointer to a Pascal string Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an initial substring of s2 National Instruments Corporation 6 73 Using External Code in LabVIEW Chapter 6 Function Descriptions FileNamelndCmp Macro int32 FileNameIndCmp sip Purpose s2p Lexically compares two file names and determines whether one is less than equal to or greater than the other This comparison uses the same case sensitivity as the file system that is case insensitive for Mac OS and Win
152. iption fd File File descriptor associated with the file ofstp int32 Address at which FMTe11 stores the position of the current position mark in terms of bytes relative to the beginning of the file If an error occurs ofstp is undefined Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr mgArgErr 10 National Instruments Corporation Err No error The file descriptor is not valid Unspecified I O error 6 93 Using External Code in LabVIEW Chapter 6 Function Descriptions FMWrite MgErr FMWrite fd inCount Purpose outCountp buffer Writes inCount bytes from memory starting at the address specified by buffer to the file specified by the file descriptor fd starting from the current position mark Refer to the FMSeek and FMTell functions in this chapter for more information about the current position mark The function stores the actual number of bytes written in outCountp The number of bytes stored can be less than inCount if an DiskFul1 error occurs before the function writes inCount bytes The number of bytes stored is zero if any other error occurs Parameters Name Type Description fd File File descriptor associated with the file from which you want to write inCount int32 Number of bytes you want t
153. is TRUE if the number of columns in the first matrix is not equal to the number of rows in the second matrix This example shows only the front panel block diagram and source code National Instruments Corporation 4 11 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs Complete the following steps to create the CIN 1 Follow the instructions in the Creating a CIN section of Chapter 3 CINs to create the CIN Figure 4 4 shows the front panel for this VI Figure 4 4 cross vi Front Panel Figure 4 5 shows the block diagram for this VI Figure 4 5 cross vi Block Diagram 2 Save the VI as cross vi 3 Create the c file for the CIN and save it as cross c The following code is the source code for cross c with the CINRun routine added CIN source file tinclude extcode h define ParamNumber 2 The return parameter is parameter 2 define NumDimensions 2 2D Array Using External Code in LabVIEW 4 12 ni com typedefs 2y typedef struct int32 dimSizes 2 float64 arg1 1 TD1 typedef TD1 TD1Hdl Chapter 4 Programming Issues for CINs CIN MgErr CINRun TD1Hd1 A TD1Hd1l B TD1Hd1AxB LVBoolean error CIN MgErr CINRun TD1Hd1 A TD1Hdl B TD1Hdl AxB LVBoolean error int32 by di ky Le int32 rows cols float64 aElmtp bElmtp resultElmtp MgErr err noErr int32 newNumElmts if k A gt dimSizes 1 1 B
154. is parameter in the argument list to the CIN newNumElmts int32 New number of elements to which the handle refers Uhandle dataH int32 paramNum int32 newNumElmts Return Value MgErr which can contain the following errors No error Not enough memory to perform the operation Handle or pointer not in specified zone O National Instruments Corporation noErr MFullErr mZoneErr 6 165 Using External Code in LabVIEW Chapter 6 Function Descriptions StrCat int32 StrCat sl Purpose s2 Concatenates a C string s2 to the end of another C string s1 returning the result in s1 This function assumes sl is large enough to contain the resulting string Parameters Name Type Description s1 Cstr Pointer to a C string s2 CStr Pointer to aC string Return Value The length of the resulting string Using External Code in LabVIEW 6 166 ni com Strcmp Chapter 6 Function Descriptions int32 StrCmp sl s2 Purpose Lexically compares two strings to determine whether one is less than equal to or greater than the other Parameters Name Type Description sl CStr Pointer to a C string s2 CStr Pointer to a C string Return Value lt 0 0 or gt 0 if sl is less than equal to or greater than s2 respectively Returns lt 0 if sl is an initial substring of s2 National Instruments Corporation 6 16
155. kRecognizedType bit is set if the item described is a file for which you can determine a 4 character file type Otherwise kRecognizedType is clear The kIsLink bit is set if the item described is a UNIX link or Mac OS alias Otherwise kIsLink is clear The kFIsInvisible bit is set if the item described does not appear in a file dialog box Otherwise kFIsInvisible is clear The value of type is defined only if the kRecognizedType bit is set in flags In this case type is the 4 character file type of the file described by the file type record This 4 character file type is provided by the file system in Mac OS and is computed by examining the file name extension on other systems Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path fNotFound The directory was not found fNoPerm Access was denied the file directory or disk is locked or protected mFullErr Insufficient memory fIOErr Unspecified I O error Using External Code in LabVIEW 6 82 ni com Chapter 6 Function Descriptions FLockOrUnlockRange MgErr FLockOrUnlockRange fd mode offset count lock Purpose Locks or unlocks a section of a file Parameters Name Type Description fd File File descriptor associated with the file mode int32 Position in the file relative to which FLockOrUnlockRange determines the first byte to lock or unlock us
156. l Instruments be liable for any damages arising out of or related to this document or the information contained in it EXCEPT AS SPECIFIED HEREIN NATIONAL INSTRUMENTS MAKES NO WARRANTIES EXPRESS OR IMPLIED AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE CUSTOMER S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING FROM LOSS OF DATA PROFITS USE OF PRODUCTS OR INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF ADVISED OF THE POSSIBILITY THEREOF This limitation of the liability of National Instruments will apply regardless of the form of action whether in contract or tort including negligence Any action against National Instruments must be brought within one year after the cause of action accrues National Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control The warranty provided herein does not cover damages defects malfunctions or service failures caused by owner s failure to follow the National Instruments installation operation or maintenance instructions owner s modification of the product owner s abuse misuse or negligent acts and power failure or surges fire flood accident actions of third parties or other events outside reasonable control Copyright Under the copyri
157. l down menu for return type e Adda parameter and name it offset National Instruments Corporation 2 23 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs f Select Numeric from the Type pull down menu g Select Unsigned 32 bit Integer from the Data Type pull down menu h Add a parameter and name it data i Select Numeric from the Type pull down menu j Select Signed 16 bit Integer from the Data Type pull down menu k Select Point to Value from the Pass pull down menu 5 Inspect the function prototype that appears in the Function Prototype field If the prototype you see does not match the definition of the function in the API you are calling you must change your settings in the Call Library Function dialog box Place a Numeric Control Numeric Indicator and Round LED indicator on the front panel Label the control and indicators and complete the block diagram as shown in Figure 2 7 data returned l 0 Succeeded Figure 2 7 Read Data VI Front Panel and Block Diagram Example 3 Call the Win32 API Ez Using External Code in LabVIEW You might want to access the 32 bit Windows platform API Win32 API In Win32 environments various DLLs permit your application to interact with the operating system and with the graphical user interface Because the API offers thousands of functions programmers must rely on the documentation for the Microsoft Software Development Kit SDK Micros
158. lect Load Code Resource Select mult 1sb the object code file you created You should be able to run the VI If you save the VI LabVIEW saves the CIN object code along with the VI National Instruments Corporation 4 5 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs Comparing Two Numbers Producing a Boolean Scalar This example shows only the block diagram and the code Complete the following steps to create a CIN that compares two single precision numbers 1 Follow the instructions in the Creating a CIN section of Chapter 3 CINs to create the CIN Figure 4 2 shows the block diagram for this CIN y TF Figure 4 2 aequalb vi Block Diagram 2 Save the VI as aequalb vi Create a c file for the CIN and name it aequalb c LabVIEW creates the following c file CIN source file tinclude extcode h CIN MgErr CINRun float32 A float32 B LVBoolean compare CIN MgErr CINRun float32 A float32 B LVBoolean compare if A B compare LVTRUE else compare LVFALSI El return noErr If the first number is greater than the second one the return value is TRUE Otherwise the return value is FALSE Using External Code in LabVIEW 4 6 ni com Chapter 4 Programming Issues for CINs Passing Variably Sized Data to CINs LabVIEW dynamically allocates memory for arrays and strings If a string or array needs more space to hold new
159. lication you want to launch National Instruments Corporation 1 1 Using External Code in LabVIEW Chapter 1 Introduction If you can access the application through TCP IP you might be able to pass data or commands to the application Refer to the documentation for the application for a description of its communication capability If you are a LabVIEW user refer to the Using LabVIEW with TCP IP and UDP Application Note for more information about techniques for using networking VIs to transfer information to other applications You also can use many ActiveX LabVIEW tools to communicate with other applications Mac OS Use the AppleEvent VIs to send commands between applications or to launch other applications Apple events are a Mac specific protocol through which applications communicate with each other If you are a LabVIEW user refer to the Using Apple Events and the PPC Toolbox to Communicate with LabVIEW Applications on the Macintosh Application Note for information about different methods for using AppleEvent VIs to launch and control other applications Characteristics of the Two Calling Approaches B Note In most cases a Call Library Function Node is easier to use than a CIN Assuming the underlying code is the same the calling speed is the same whether you use a Call Library Function Node or a CIN Using External Code in LabVIEW The LabVIEW Call Library Function Node and the CIN are block diagram objects that link source
160. llowing command to compile the myshared c source file that you completed in the Task 2 Complete the c File section gcc fPIC shared o lt output name gt lt source file gt The fPIC option instructs GCC to produce position independent code which is suitable for shared libraries The shared option specifies that the output should be a shared library file B Note Some versions of the Gnu linker do not produce suitable output for shared libraries The fno gnu linker instructs GCC to use the system linker rather than the Gnu linker The output name is normally a file with a so extension on Solaris and Linux Using External Code in LabVIEW Reducing Symbol Scope By default all symbols functions and global variables defined in your code are available It is sometimes desirable for your library to distinguish between those symbols that should be accessed by external objects and those that are for internal use only Use a mapfile to make these distinctions The mapfile is a text document that the linker takes as input and uses to determine among other things which symbols should be exported Use the following basic syntax for a mapfile where lt library file gt is the name of the output file lt library file gt global Symbol for global scope 1 Symbol for global scope 2 local Symbols for local scope 1 or 3 Under the global and local sections list all of the symbols that you want to be availa
161. llowing values are defined in the file extcode h denyReadWrite Prevents others from reading from and writing to the file while it is open e denyWrite0nly Prevents others from writing to the file only while it is open denyNeither Allows others to read from and write to the file while it is open group PStr UNIX group you want to assign to the new file O National Instruments Corporation 6 53 Using External Code in LabVIEW Chapter 6 Function Descriptions Return Value MgErr which can contain the following errors noErr mgArgErr fIsOpen fNoPerm fDupPath fTMFOpen fIOErr Using External Code in LabVIEW No error A bad argument was passed to the function Verify the path File is already open for writing This error is returned only in Mac OS and Solaris Windows returns 10Err when the file is already open for writing Access was denied because the file is locked or protected A file of that name already exists Too many files are open Unspecified I O error 6 54 ni com Chapter 6 Function Descriptions FCreateAlways MgErr FCreateAlways fdp path permissions openMode denyMode group Purpose Creates a file with the name and location specified by path and with the specified permissions and opens the file for writing and reading as specified by openMode If the file already exists this function opens and truncates the file You can u
162. locks The four reserved fields are reserved for use by National Instruments Using External Code in LabVIEW 6 24 ni com AZNewHandle DSNewHandle Chapter 6 Function Descriptions UHandle AZNewHandle size UHandle DSNewHandle size Purpose Creates a new handle to a relocatable block of memory of the specified size The routine aligns all handles and pointers in DS to accommodate the largest possible data representations for the platform in use Parameters Name Type Description size int32 Size in bytes of the handle you want to create Return Value A handle of the specified size If an error occurs this function returns NULL O National Instruments Corporation 6 25 Using External Code in LabVIEW Chapter 6 Function Descriptions AZNewHClr DSNewHClr UHandle AZNewHClr size UHandle DSNewHClr size Purpose Creates a new handle to a relocatable block of memory of the specified size and initializes the memory to zero Parameters Name Type Description size int32 Size in bytes of the handle you want to create Return Value A handle of the specified size where the block of memory is set to all zeros If an error occurs this function returns NULL Using External Code in LabVIEW 6 26 ni com AZNewPClr DSNewPClr Chapter 6 Function Descriptions UPtr AZNewPClr size UPtr DSNewPClr size Purpose
163. low order int16 of an int32 Parameters Name Type Description x int32 int32 for which you want to determine the low int16 National Instruments Corporation 6 129 Using External Code in LabVIEW Chapter 6 Function Descriptions LoByte Macro int8 LoByte x Purpose Returns the low order int8 of an int16 Parameters Name Type Description x int16 int16 for which you want to determine the low int8 Using External Code in LabVIEW 6 130 ni com Long Macro Chapter 6 Function Descriptions int32 Long hi lo Purpose Creates an int32 from two int16 parameters Parameters Name Type Description hi int16 High int16 for the resulting int32 lo int16 Low int16 for the resulting int32 Return Value The resulting int32 National Instruments Corporation 6 131 Using External Code in LabVIEW Chapter 6 Function Descriptions LoNibble Macro uInt8 LoNibble x Purpose Returns the value stored in the low four bits of an uInt8 Parameters Name Type Description x uInt8 uInt8 whose low four bits you want to extract Using External Code in LabVIEW 6 132 ni com LStrBuf Macro Chapter 6 Function Descriptions uChar LStrBuf s Purpose Returns the address of the string data of a long Pascal string that is the address of s gt str Parameters Name Type Description s LStrPt
164. ltiplies the values to which A and B refer and stores the results in the location to which A_B refers It is important that CIN routines return an error code so LabVIEW knows whether the CIN encountered any fatal problems and handles the error correctly If you return a value other than noErr LabVIEW stops running the VI 8 Compile the source code and convert it into a form LabVIEW can use The following sections summarize the steps for each of the supported compilers Refer to the Step 4 Compile the CIN Source Code section of Chapter 3 CINs for more information about completing this step on your platform Macintosh Programmer s Workshop Create a file named mult 1vm Make sure the name variable is set to mult Build mult 1vm Metrowerks CodeWarrior Create a new project and place mult c in it Build mult 1sb Microsoft Visual C Compiler Command Line and Symantec C for Windows Create a file named mult 1vm Make sure the name variable is set to mult Build mult 1vm Microsoft Visual C Compiler IDE for Windows Create a project UNIX Compilers Create a makefile using the shell script 1vmkmf in the cintools directory For this example enter the following command lymkmf mult The preceding command creates a file called Makefile After running 1vmkmf enter the standard make command which uses Makefile to create a file called mult 1sb You can load mult 1sb into the CIN in LabVIEW 9 Right click the node and se
165. me memory space as the main application Mac OS X You can create CINs with the Project Builder development environment available free from Apple Computer Inc Although it is possible to create a CIN using Metrowerks Codewarrior National Instruments currently does not provide any support for this compiler Refer to the Mac OS X subsection of the Step 4 Compile the CIN Source Code section of this chapter for information about creating a CIN with Project Builder National Instruments Corporation 3 1 Using External Code in LabVIEW Chapter 3 CINs Mac OS Classic You can create CINs with compilers from the two major C compiler vendors e Metrowerks CodeWarrior from Metrowerks Corporation of Austin TX e Macintosh Programmer s Workshop MPW from Apple Computer Inc of Cupertino CA Refer to the Mac OS Classic subsection of the Step 4 Compile the CIN Source Code section of this chapter for information about creating a CIN using these compilers Microsoft Windows Solaris and Linux LabVIEW for Windows supports CINs created with the following compilers e Microsoft Visual C e Symantec C Refer to the Microsoft Windows subsection of the Step 4 Compile the CIN Source Code section of this chapter for information about creating a CIN using these compilers The default compiler for Solaris is gcc If gcc is not installed cc becomes the default compiler for Solaris The only supported compiler for Linux is gcc
166. ments The SDK implements two versions of functions that use string arguments a Unicode version and an ANSI version One of the items in the Requirements section of the MessageBox documentation says Unicode Implemented as Unicode and ANSI version on Windows and Windows NT You can distinguish the two versions in the DLL because each has a w Unicode or an A ANSI appended to the end of the function name winuser h contains the following code ifdef UNICODE define MessageBox MessageBoxW else define MessageBox MessageBoxA tendif UNICODE The preceding code defines MessageBox to be either MessageBoxA or MessageBoxw depending on whether the application is a Unicode 2 28 ni com Chapter 2 Shared Libraries DLLs application In effect a MessageBox function does not exist in user32 d11 Instead user32 d11 contains a function MessageBoxA and a function MessageBoxw In most cases in LabVIEW you use the ANSI version of the function because the LabVIEW strings are based on ANSI not Unicode For this example you use the MessageBoxa function Configuring a Call to the Win32 API Now that you are familiar with many aspects of the Win32 API you can configure a LabVIEW Call Library Function Node to call the MessageBox function Remember that you must use the Standard __stdca11 calling convention in calls to any function in the Windows SDK Figure 2 9 shows a correctly configured instance of the Call Library Functi
167. mgArgErr A bad argument was passed to the function Verify the path fIsOpen File is already open for writing This error is returned only in Mac OS and Solaris Windows returns IOErr when the file is already open for writing fNotFound File not found TMFOpen Too many files are open fIOErr Unspecified I O error National Instruments Corporation 6 89 Using External Code in LabVIEW Chapter 6 Function Descriptions FMove MgErr FMove oldPath newPath Purpose Moves a file or renames it if the new path indicates the file is to remain in the same directory Parameters Name Type Description oldPath Path Path of the file or directory you want to move newPath Path Path including the name of the file or directory where you want to move the file or directory Return Value MgErr which can contain the following errors noErr mgArgErr fNotFound fNoPerm fDiskFull fDupPath fIsOpen fTMFOpen mFullErr fIOErr Using External Code in LabVIEW No error A bad argument was passed to the function Verify the path File not found Access was denied the file directory or disk is locked or protected Disk is full The new file already exists The original file is open for writing Too many files are open Insufficient memory Unspecified I O error 6 90 ni com FMRead Chapter 6 Function Descriptions MgErr FMRead fd inCount Purpose outCoun
168. mmand where mul t is the makefile name nmake f mult lvm If you want to use standard C or Windows libraries define the symbol cinLibraries For example to use standard C functions in the previous example you could use the following 1vm file name mult type CIN cinLibraries libc lib linclude CINTOOLSDIR ntlvsb mak To include multiple libraries separate the list of library names with spaces Symantec C Building CINs using Symantec C is similar to building CINs for Visual C Command Line However you should use smake instead of nmake on your lvm file Solaris 2 x LabVIEW for Solaris 2 x uses external code compiled in a shared library format To prepare this library for Lab VIEW use the LabVIEW utility lvsbutil lvsbutil is in the cintools folder The default compiler for Solaris is gcc If gcc is not installed cc becomes the default compiler for Solaris National Instruments Corporation 3 17 Using External Code in LabVIEW Chapter 3 3 Using External Code in LabVIEW CINs Linux The only supported compiler for Linux is gcc gcc Compiler Create a makefile using the shell script Lvmkmf LabVIEW Make Makefile which creates a makefile for a given CIN Use the standard make command to make the CIN code In addition to compiling the CIN the makefile puts the code in a form LabVIEW can use The format for the 1vmkmf command is shown in the following example code with optional paramete
169. mmand line arguments to the MakePEF tool that indicate the mapping between the name of each link time import library and the run time name of that import library These usually look similar to the following example code librename 1ibA xcoff 1ibA librename libB xcoff 1ibB Only the file names are needed not entire paths You must adjust the Dir names to reflect your own file system hierarchy Modify your MPW command search path by appending the cintools MPW folder to the default search path This search path is defined by the MPW Shell variable commands as shown in the following example code set commands commands lt pathname to directory of cinToolsDir gt Go to the MPW Worksheet and enter the following commands setting your current folder to the CIN folder Directory lt pathname to directory of your CIN gt Run the LabVIEW CINMake script shown in the following example code CINMake lt name of your CIN gt If CINMake does not find a 1vm file in the current folder it builds a file named cinName 1vm and prompts you for necessary information If CINMake finds cinName 1vm but it does not have the line LVMVers 2 MPW saves the 1vm file in cinName 1vm old and updates the cinName 1vm file to be compatible with the new version of CINMake O National Instruments Corporation 3 13 Using External Code in LabVIEW Chapter 3 CINs Using External Code in LabVIEW The format of the CINMake command is shown in the
170. n 6 117 Using External Code in LabVIEW Chapter 6 Function Descriptions FUnFlattenPath int32 FUnFlattenPath fp pPtr Purpose Converts a flattened path created using FFlattenPath into a path Parameters Name Type Description fp UPtr Pointer to the flattened path you want to convert to a path pPtr Path Address at which FUnFlattenPath stores the resulting path Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value Number of bytes the function interpreted as a path Using External Code in LabVIEW 6 118 ni com FVolName Chapter 6 Function Descriptions MgErr FVolName path vol Purpose Creates a path for the volume of an absolute path by removing all but the first component name from path You can pass the same path variable for the volume path that you use for path Therefore you can call this function in the following two ways err FVolName path vol the parent path is returned err FVolName path path the parent path writes over Parameters in a second path variable the existing path Name Type Description path vol Path Path Path whose volume path you want to determine Parameter in which FVolName stores the volume path Return Value MgErr which can contain the following error noErr mgArgErr O National
171. n Node and select Create Constant from the shortcut menu Set the constant value to Zero Wire the avg output of the Call Library Function Node to Avg Value Wire the error output of the Call Library Function Node to Error Figure 2 6 shows the completed Array Average block diagram Figure 2 6 Array Average VI Block Diagram Run the VI On the front panel enter values in Array and run the VI to calculate the average of those values Save your work and close the VI If your DLL returns incorrect results or crashes verify the data types and wiring to see if you wired the wrong type of information If you require further help several sections in this chapter present troubleshooting tips and pitfalls to avoid Example 2 Call a Hardware Driver API You might want to access an API associated with hardware you have purchased In this example you call a hypothetical interface card for a databus called X bus May Note You do not need to use the Call Library Function Node to gain access to the APIs of National Instruments hardware All National Instruments products come with LabVIEW interfaces Using External Code in LabVIEW 2 22 ni com Chapter 2 Shared Libraries DLLs Configure the Call Library Function Node The X bus interface card comes with a software driver for your operating system The X bus documentation provides the following standard information e A listing of all functions you can use to access
172. n contain the following values Character is a numerical digit TRUE FALSI y Using External Code in LabVIEW Otherwise 6 126 ni com IsLower Chapter 6 Function Descriptions Bool32 IsLower c Purpose Returns TRUE if the character c is a lowercase letter that is in the set a to z In SPARCstation this function also returns TRUI Parameters E for lowercase international characters such as 5 and so on Name Type Description uChar Character you want to analyze Return Value Boo132 which can contain the following values Character is a lowercase letter TRUE FALSE O National Instruments Corporation Otherwise 6 127 Using External Code in LabVIEW Chapter 6 Function Descriptions IsUpper Bool32 IsUpper c Purpose Returns TRUE if the character c is between an uppercase letter that is in the set A to z In SPARCstation this function also returns TRUI 6 A and so on Parameters E for uppercase international characters such as Name Type Description uChar Character you want to analyze Return Value Boo132 which can contain the following values Character is an uppercase letter TRUE FALSI GJ Using External Code in LabVIEW Otherwise 6 128 ni com Lo16 Macro Chapter 6 Function Descriptions int16 Lol6 x Purpose Returns the
173. n pass the same path variable for the parent path that you use for path Therefore you can call this function in the following two ways err FDirName path dir the parent path is returned err FDirName path path the parent path writes over Parameters in a second path variable the existing path Name Type Description path dir Path Path Path whose parent path you want to determine Parameter in which FDirName stores the parent path Return Value MgErr which can contain the following errors No error noErr mgArg Using External Code in LabVIEW BEE A bad argument was passed to the function Verify the path 6 60 ni com FDisposeRefNum Chapter 6 Function Descriptions MgErr FDisposeRefNum refNum Purpose Disposes of the specified file refNum Parameters Name Type Description refNum LVRefNum File refnum of which you want to dispose Return Value MgErr which can contain the following error noErr mgArgErr National Instruments Corporation No error File refnum is not valid 6 61 Using External Code in LabVIEW Chapter 6 Function Descriptions FEmptyPath Path FEmptyPath p Purpose Makes an empty absolute path which is not the same as disposing the path Parameters Name Type Description p Path Path allocated by FEmptyPath If NULL Return V
174. ncurrent access to the file is allowed The following values are defined in the file extcode h denyReadwrite Prevents others from reading from and writing to the file while it is open e denyWriteOnly Prevents others from writing to the file only while it 1s open denyNeither Allows others to read from and write to the file while it is open group PStr UNIX group you want to assign to the new file Using External Code in LabVIEW 6 56 ni com Return Value Chapter 6 Function Descriptions MgErr which can contain the following errors noErr mgArgErr fIsOpen fNoPerm fDupPath fTMFOpen FIOErr National Instruments Corporation No error A bad argument was passed to the function Verify the path File is already open for writing This error is returned only in Mac OS and Solaris Windows returns 10Err when the file is already open for writing Access was denied because the file is locked or protected A file of that name already exists Too many files are open Unspecified I O error 6 57 Using External Code in LabVIEW Chapter 6 Function Descriptions FDepth int32 FDepth path Purpose Computes the depth or number of component names of a path Parameters Name Type Description path Path Path whose depth you want to determine Return Value int32 indicating the depth of the path which can contain the
175. ndex int32 Number of the string you want to remove with 0 as the first string National Instruments Corporation 6 41 Using External Code in LabVIEW Chapter 6 Function Descriptions CPStrReplace MgErr CPStrReplace slh s2 index Purpose Replaces a Pascal string in a concatenated list of Pascal strings with a new Pascal string Parameters Name Type Description slh CPStrHandle Handle to a concatenated list of Pascal strings s2 PStr Pointer to a Pascal string index int32 Number of the string you want to replace with 0 as the first string Return Value MgErr which can contain the following errors No error noErr mFullErr Using External Code in LabVIEW Insufficient memory 6 42 ni com CPStrSize Chapter 6 Function Descriptions int32 CPStrSize sp Purpose Returns the number of characters in a concatenated list of Pascal strings Use the CPStrLen function to get the number of Pascal strings in the concatenated list Parameters Name Type Description sp CPStrPtr Pointer to a concatenated list of Pascal strings Return Value The number of characters in the concatenated list of Pascal strings National Instruments Corporation 6 43 Using External Code in LabVIEW Chapter 6 Function Descriptions CToPStr int32 CToPStr cstr Purpose pstr Converts a C string to a P
176. ndle across different calls of the same CIN an asynchronous CIN the AZ handle might be relocated between calls AZHLock and AZHUn1ock might be useful if you do not want the handle to relocate A DS handle moves only when you resize it Additional routines make it easy to copy and concatenate handles and pointers to other handles check the validity of handles and pointers and copy or move blocks of memory from one place to another Simple Example of Using Pointers and Handles in Memory Zones This simple example demonstrates how to work with pointers and handles in C The following code shows how to work with a pointer to an int32 int32 myInt32P myInt32P int32 DSNewPtr sizeof int32 myInt32P 5 x myInt32P 7 DSDisposePtr myInt32P The first line declares the variable myInt32P as a pointer to or the address of a 32 bit signed integer The first line does not actually allocate memory for the int32 The first line creates memory for an address and associates the name myInt32P with that address The P at the end of the variable name is a convention used in this example to indicate the variable is a pointer The second line creates a block of memory in the data space large enough to hold a single 32 bit signed integer and sets myInt32P to refer to this memory block The third line places the value 5 in the memory location to which myInt32P refers The operator refers to the value in the address location The f
177. ne the size of an integer Without an explicit definition of the size of each data type you have difficulty creating code that works identically across multiple compilers LabVIEW managers use data types that explicitly indicate the size of the data type For example if a routine requires a 4 byte integer as a parameter you define the parameter as an int 32 The managers define data types in terms of the fundamental data types for each compiler Thus on one compiler the managers might define an int32 as an int while on another compiler the managers might define an int32 as along int When you write external code use the manager data types instead of the host computer data types so your code is more portable and has fewer errors The remainder of this chapter discusses data types and the individual manager functions Data Types Manager data types include the following data types e Scalar e Char e Dynamic e Memory related e Constants Using External Code in LabVIEW 4 18 ni com Chapter 4 Programming Issues for CINs Scalar Scalar data types include Boolean and numeric Boolean External code modules work with two kinds of Boolean scalars those existing in LabVIEW block diagrams and those passing to and from manager routines The manager routines use a conventional Boolean form where O is FALSE and 1 is TRUE This conventional Boolean form is called a Boo132 and is stored as a 32 bit value LabVIEW block diagrams store Bo
178. nncnnccnnos 2 24 Constants ica it 2 26 Determining the Proper Library and Function Name 2 28 Unicode Versions and ANSI Versions of Functions ee 2 28 Configuring a Call to the Win32 API eee cere eseeeeeeeees 2 29 Additional Windows Examples of LabVIEW Calls to DLLs ooooncnncnicnnncinnnnancnnncnnos 2 30 Debugging DLLs and Calls to DLES ooconncninonicnonnnonconnnoncnnnnoncnn non cnnnonccnn crono nn nro ncnncnnno 2 31 Troubleshooting the Call Library Function Node oooocononnocncnncoononncnncnanannninnos 2 31 Troubleshooting your DLL acooocicinondinoiostorisinactccaiecria reino ntartaacs 2 32 Troubleshooting Checklist oooooncnnconncnonnnoncnnnnononnnconcnnocononnnonnncncnn cono nnncnnonnos 2 34 Module Definition Files ciicocooiocoor egei eisino p iaasa aasia aaa ia doers 2 36 Array and String OptionsS sssisinninssiiinin enraiar E 2 37 Arrays of Numeric Data siinsesse ai aa a a Sa 2 37 String Data ici n aE E A E E EN E A ai 2 38 Array and String Tip saiscscisesddsiecesisdesesecesesssdasa rencia iii 2 40 Chapter 3 CINs Supported Languages iiini li init ibas 3 1 MacOS Xi in nia 3 1 Mac OS Classin e ii 3 2 Microsoft Wind WS iria a a indias 3 2 Solaris anid LIMUSA eee T RERS 3 2 Resolving Multithreading Issues ooooncnicnnonionnnonconaconcnncnnncnn cnn nonnonnncnn conc cnn crono nn c rana nccnnos 3 2 Making LabVIEW Recognize a CIN as Thread Safe oooonncnnnnicnnocinnnccnnnnncnnos 3 3 Using C Code t
179. nnonncnnconncnn ono ncnno a ron non rancio 4 2 Scalar NuMetal 4 2 Scalar Boolean S alii 4 2 REIS A a 4 2 Clust rs OF Scala iia a e De eee 4 2 Return Value for CIN Routines oooncococonocconconnnonconncnnonnnonnnnnnonnonn nono cnn ncnncrnnonnnos 4 3 Examples With Calar vit 4 3 Passing Variably Sized Data to CINS ooooonnccocccocconncononancnnonancnnonnncon cnn nnononn non nc nn circa rnncnno 4 7 Alignment Considerations os ocra ie EE non nc nn non conc cnn aran canicas 4 7 ATTAYS and StNOOS a E a 4 8 Pat a A little 4 8 Clusters Containing Variably Sized Data oooconcnnnnncnicnnononnnonnnnncnnnonncnnarnnonanos 4 8 Resizing Arrays and Strings ienei ie e E non nono nonn conc cnn cnn ncnncrnno 4 9 Examples with Variably Sized Data ooonconnninnnnnnonnonnccnnonncnncnnnrnncnncrnncnnoraninnon 4 9 Manager Overview tia A dt 4 18 Data Types ada aia 4 18 Cl A ests 4 19 Ci da ii ii 4 21 DINAMICA ta ii Dd ce 4 21 Memory Relat d cutis ca 4 23 Constants ni A ia 4 23 Memory Manara iS 4 23 Memory Alloc MON tt dde eben ees 4 24 Memory Zone uti a dos 4 25 Fil Mana Ser toplist id tesi 4 28 Identifying Files and Directories 2 0 0 0 eee ec eeeeseesecseeeseeseeeeeeseeaeeseeeasenseeaes 4 29 Path Speci Cations e a ii dla 4 29 O National Instruments Corporation vii Using External Code in LabVIEW Contents File Descriptor comicos idad ii Wea cz nt Reve teen ceasehe 4 32 File Refis ne ain eit eal Aa Sires ahs ees e 4 32 Support Managers edit tr i
180. noErr mgArgE EX fNotFound fNoPerm fIsOpen fIOErr O National Instruments Corporation Access was denied the file directory or disk is locked or protected File is open or directory is not empty Unspecified I O error 6 109 Using External Code in LabVIEW Chapter 6 Function Descriptions FSetAccessRights MgErr FSetAccessRights path owner group permPtr Purpose Sets access rights information for the specified file or directory If an error occurs no information changes Parameters Name Type Description path Path Path of the file or directory for which you want to set access rights information owner PStr New owner that FSetAccessRights sets for the file or directory if owner is not NULL group PStr New group that FSetAccessRights sets for the file or directory if group is not NULL permPtr int32 Address of new permissions that FSetAccessRights Sets for the file or directory if permPtr is not NULL Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path fNotFound File not found fIOErr Unspecified I O error Using External Code in LabVIEW 6 110 ni com FSetEOF Chapter 6 Function Descriptions MgErr FSetEOF fd size Purpose Sets the size of the specified file If an error occurs the file size does
181. nstance of the VI If you have a CIN data space in a reentrant VI and you call the VI in seven places LabVIEW allocates memory to store seven CIN data spaces for the VI Each of the CIN data spaces contains a unique storage location for the CIN data space for that calling instance As with multiple instances of the same CIN LabVIEW calls the CINInit CINDispose and CINAbort routines for each individual CIN data space If you have a reentrant VI containing multiple copies of the same code resource LabVIEW calls the CINInit CINDispose and CINAbort routines once for each use of the reentrant VI multiplied by the number of references to the code resource within that VI National Instruments Corporation 5 7 Using External Code in LabVIEW Chapter 5 Advanced Applications Figure 5 3 shows an example of three VIs referencing a reentrant VI containing one CIN Caller 1 Caller 2 Caller 3 Gan My VI My VI My VI Data Space 1 Data Space 3 E Bana T 7 4 byte CIN Data Space Data Space Globals Data Space Globals My VI E O EN E Data E 2 Code Resource Global Storage gt Data Space Globals Code Globals Figure 5 3 Three Vis Referencing a Reentrant VI Containing One CIN Multithreaded Operating Systems By default CINs written in LabVIEW 5 0 or earlier run in a single thread the user interface thread When you change a CIN to be reentrant that is to run in multi
182. nterface tasks In single threaded applications LabVIEW switches between user interface tasks and running VIs When CIN or shared library object code executes it takes control of its execution thread If an application has only a single thread of control the application waits until the object code returns In single threaded operating systems such as Mac OS CINs and shared libraries even prevent other applications from running LabVIEW cannot interrupt object code that is running so you cannot reset a VI that is running a CIN or shared library until execution completes If you want to write a CIN or shared library that performs a long task be aware that LabVIEW cannot perform other tasks in the same thread while these objects execute Details of the Call Library Function Node You can call most standard shared libraries with the Call Library Function Node In Windows these shared libraries are DLLs on Mac OS they are Code Fragments and on UNIX they are Shared Libraries The Call Library Function Node includes a large number of data types and calling conventions You can use the Call Library Function Node to call functions from most standard and custom made libraries DLLs have the following advantages e You can change the DLL without changing any of the VIs that link to the DLL provided you do not modify the function prototypes e Practically all modern development environments provide support for creating DLLs while LabVIEW s
183. ntroduction This manual discusses the following methods used in LabVIEW to call code written in other languages e Using platform specific protocols e Using the Call Library Function Node to call the following types of shared libraries Dynamic Link Libraries DLL in Windows Code Fragments on Mac OS Shared Libraries on UNIX e Creating a Code Interface Node CIN to call code written specifically to link to VIs 3 Notes To convert an instrument driver written in LabWindows CVI select Tools Instrumentation Import CVI Instrument Driver to open the Select a CVI Function Panel file dialog box In the Select a CVI Function Panel file dialog box you select the function panel file to convert After you select a front panel file the CVI Function Panel Converter dialog box opens You use the CVI Function Panel Converter dialog box to complete the conversion of the front panel file Refer to the LabVIEW Help for more information about the CVI Function Panel Converter dialog box Refer to cvilvsb h in the cintools folder for information about creating a LabVIEW CIN in LabWindows CVI Calling Code in Various Platforms This section describes the differences between running Windows and UNIX applications from within your VIs and running Mac OS applications from within your VIs Windows and UNIX Use the System Exec VI to run a command line from your VI The command line can include any parameters supported by the app
184. nused bits in the last 16 bit integer LabVIEW 4 x ordered the bits from left to right That is the most significant bit MSB is index 0 As with other arrays a 4 byte dimension size preceded Boolean arrays The dimension size for LabVIEW 4 x Boolean arrays indicates the number of valid bits contained in the array The exact structure for Path data types is subject to change in future versions of LabVIEW A Path is a dynamic data structure LabVIEW passes the same way it passes arrays LabVIEW stores the data for Paths in an application zone handle Refer to Chapter 6 Function Descriptions for information about the functions that manipulate Paths Clusters Containing Variably Sized Data For cluster arguments LabVIEW passes a pointer to a structure containing the elements of the cluster LabVIEW stores scalar values directly as components inside the structure If a component is another cluster LabVIEW stores the component cluster value as a component of the main cluster If a component is an array or string LabVIEW stores a handle to the array or string component in the structure Using External Code in LabVIEW 4 8 ni com Chapter 4 Programming Issues for CINs Resizing Arrays and Strings To resize return arrays and strings you pass to a CIN use the LabVIEW SetCINArraySize routine Pass to the SetCINArraySize function the handle you want to resize information describing the data structure and the desired size of the array or handle S
185. o the specified point relative to the beginning of the file the current position in the file or the end of the file If an error occurs the current position mark does not move Parameters Name Type Description fd File File descriptor associated with the file ofst int32 New position of the current position mark The position is the number of bytes from the beginning of the file the current position mark or the end of the file as determined by mode mode int32 Position in the file relative to which FMSeek sets the current position mark for a file using the following values e Start Current position mark moves to ofst bytes relative to the start of the file ofst must be greater than or equal to 0 e fCurrent Current position mark moves ofst bytes from the current position mark ofst can be positive 0 or negative e f End Current position mark moves to ofst bytes from the end of the file ofst must be less than or equal to 0 Return Value MgErr Which can contain the following errors noErr No error mgArgErr The file descriptor is not valid fEOF Attempt to seek before the start or after the end of the file fIOErr Unspecified I O error Using External Code in LabVIEW 6 92 ni com FMTell Chapter 6 Function Descriptions MgErr FMTell fd ofstp Purpose Returns the position of the current position mark in the file Parameters Name Type Descr
186. o use the String Handle format UN Caution Do not attempt to resize a string with system functions such as realloc because your system might crash Using External Code in LabVIEW Waveform When you call a shared library that includes a waveform data type you do not have to specify a numeric value from the Data Type pull down menu the default is 8 byte double However you must specify a Dimension If the Parameter is a single waveform specify a Dimension of 0 If the Parameter is an array of waveforms specify a Dimension of 1 LabVIEW does not support an array of waveforms greater than 1D 2 6 ni com Chapter 2 Shared Libraries DLLs Digital Waveform Specify a Dimension of 0 if the Parameter is a single digital waveform Specify a Dimension of 1 if the Parameter is an array of digital waveforms LabVIEW does not support an array of digital waveforms greater than 1D Digital Table Specify a Dimension of 0 if the Parameter is a single digital table Specify a Dimension of 1 if the Parameter is an array of digital tables LabVIEW does not support an array of digital tables greater than 1D 3 Note Waveforms digital waveforms and digital tables can be passed through shared libraries but accessing the data inside the shared libraries is not supported at this time ActiveX Select one of the following items from the Data Type pull down menu e ActiveX Variant Pointer passes a pointer to ActiveX data e Dispatch Pointer p
187. o write outCountp int32 Address at which FMWrite stores the number of bytes written FMWrite does not store any value if NULL is passed Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter buffer Uptr Address of the data you want to write Return Value MgErr which can contain the following errors noErr mgArgErr fDiskFull fNoPerm fIOErr Using External Code in LabVIEW No error Not a valid file descriptor or inCount lt 0 Out of space Access was denied Unspecified I O error ni com FName Chapter 6 Function Descriptions MgErr FName path name Purpose Copies the last component name of a specified path into a string handle and resizes the handle as necessary Parameters Name Type Description path Path Path whose last component name you want to determine name StringHandle Handle in which FName returns the last component name as a Pascal string Return Value MgErr which can contain the following errors No error Badly formed path or path is root directory noErr mgArgErr mFullErr O National Instruments Corporation Insufficient memory 6 95 Using External Code in LabVIEW Chapter 6 Function Descriptions FNamePtr MgErr FNamePtr path name Purpose Copies the last component name of a path to the address specified by name This routine does not
188. oFD stores the file descriptor associated with the specified file refnum Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following error noErr mgArg Using External Code in LabVIEW Err No error File refnum is not valid 6 106 ni com FRefNumToPath Chapter 6 Function Descriptions MgErr FRefNumToPath refNum path Purpose Gets the path associated with the specified file refnum and stores the resulting path in the existing path If no error occurs path is set to the path associated with the specified file refnum If an error occurs path is set to the canonical invalid path Parameters Name Type Description refNum LVRefNum The file refnum whose associated path you want to get path Path Path where FRefNumToPath stores the path associated with the specified file refnum This path must already have been created Return Value MgErr which can contain the following errors No error A bad argument was passed to the function Verify the path Insufficient memory noErr mgArgErr mFullErr National Instruments Corporation 6 107 Using External Code in LabVIEW Chapter 6 Function Descriptions FRelPath MgErr FRelPath startPath endPath relPath Purpose Computes a relative path between two absolute paths Y
189. of data spaces and the number of references to that code resource Because LabVIEW calls CINLoad once for a given code resource you should initialize code globals in CINLoad LabVIEW calls CINInit for a given code resource a total of one time for each CIN data space multiplied by the number of references to the code resource in the VI corresponding to that data space If you want to use CIN data space globals initialize them in CINInit Refer to the Loading a New Resource into the CIN Compiling a VI and the Code Globals and CIN Data Space Globals sections of this chapter for more information about CINInit and data space globals National Instruments Corporation 5 3 Using External Code in LabVIEW Chapter 5 Advanced Applications Unloading a VI When you close a VI front panel LabVIEW checks whether any references to the VI are in memory If any references to the VI are in memory the VI code and data space remain in memory When all references to a VI are removed from memory and its front panel is not open the VI is unloaded from memory When a VI is unloaded from memory LabVIEW calls the CINDispose routine giving you a chance to dispose of anything you allocated earlier CINDispose is called for each CINInit call For instance if you used XXNewHandle in your CINInit routine you should use XXDisposeHandle in your CINDispose routine LabVIEW calls CINDispose for a code resource once for each individual CIN data space As the las
190. oft Visual Studio products give you access to the SDK documentation You also can access this information at the Microsoft Developer Network MSDN Web site on the Internet Note Instead of using the Windows DLL as described in this example you could easily create this message box in LabVIEW 2 24 ni com Chapter 2 Shared Libraries DLLs In this example you call the Windows MessageBox function a function which illustrates several of the typical complexities of the Win32 API MessageBox is a simple SDK function that presents a small dialog box with a message and has the following prototype int MessageBox HWND hWnd handle to owner window LPCTSTR lpText text in message box LPCTSTR lpCaption message box title UINT uType message box style Notice the non standard data types such as HWND and LPCTSTR The Win32 API uses hundreds of data types in the SDK and very few of them are standard C data types However many of the non standard data types are merely aliases for standard C data types The API uses the aliases to identify the context of a particular data type Table 2 1 lists the data types in the preceding prototype and the corresponding standard C data types Table 2 1 Mapping Win32 Data Types to Standard C Data Types WIN32 SDK Data Type Basic C Data Type HWND int LPCTSTR const char UINT unsigned int To properly call the MessageBox function in LabVIEW you need to identify th
191. olean scalars as 8 bit values The value is O if FALSE and 1 if TRUE This Boolean form is called an LVBoolean The Table 4 1 describes the two forms of Boolean scalars Table 4 1 Boolean Scalars Name Description Boo132 32 bit integer O if FALSE 1 if TRUE LVBoolean 8 bit integer 0 if FALSE 1 if TRUE Numeric The managers support 8 16 and 32 bit signed and unsigned integers For floating point numbers LabVIEW supports the single double and extended floating point data types Table 4 2 Floating Point Data Types Supported by LabVIEW Type Description Single 32 bit Double 64 bit Extended At least 80 bit LabVIEW supports complex numbers containing two floating point numbers with different complex numeric types for each of the floating point data types O National Instruments Corporation 4 19 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs LabVIEW supports the following basic data types for numbers e Signed integers ints 8 bit integer int16 16 bit integer int32 32 bit integer e Unsigned integers uInt8 8 bit integer ulInt16 16 bit integer ulInt32 32 bit integer e Floating point numbers float32 32 bit floating point number float64 64 bit floating point number floatExt extended precision floating point number Table 4 3 explains how various platforms store extended precision numbers Table 4 3 Stor
192. ols Mach o folder in the LabVIEW directory 3 On the Files tab press Command I and select the liblabviewcin a file in the External Frameworks and Libraries section 4 Click the Set Path button and locate the 1iblabviewcin a file in the cintools Mach o folder in the LabVIEW directory 5 On the Files tab press Command I and select the 1iblvexports a file in the External Frameworks and Libraries section 6 Click the Set Path button and locate the 1iblvexports a file in the cintools Mach o folder in the LabVIEW directory The ReadMe Project Builder rtf file located in the cintools Project Builder Files directory also includes information about how to install the CIN template into Project Builder and how to create a new CIN project Mac OS Classic LabVIEW for Mac OS Classic uses shared libraries as a resource for customized code To prepare the code for LabVIEW use the separate utilities lvsbutil app for Metrowerks CodeWarrior and lvsbutil tool for the Macintosh Programmer s Workshop These utilities are included with LabVIEW in the cintools folder 3 10 ni com Chapter 3 CINs LabVIEW header files are compatible with Metrowerks CodeWarrior and Macintosh Programmer s Workshop Header files might need modification for other environments Always use the latest Universal headers containing definitions for Mac OS Classic compilers Metrowerks CodeWarrior for Mac OS Classic To set up your CIN project use the project stati
193. on Node Make your Call Library Function dialog box match the settings in the graphic Refer to the Task 1 Build the Function Prototype in LabVIEW section of this chapter for a separate example that teaches you how to configure controls for the Call Library Function Node Call Library Function Xx MessageBioxs stdcall WINAPI Unsigned 32 bit Integer int32 MessageBoxA ulnt32 hWnd CStr IpT ext CStr IpCaption ulnt32 uT ype Figure 2 9 Configuring the Call Library Function Node to Call the Win32 API National Instruments Corporation 2 29 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Figure 2 10 shows the block for a VI designed to call the Win32 API Configure your block diagram to match Figure 2 10 No morespace This is a Test MB ICONEXCLAMATION Figure 2 10 Block Diagram for a Call to the Win32 API The VI generates the message box shown in Figure 2 11 This is a Test ieee Jew tome Figure 2 11 Running a LabVIEW Call to the Win32 API Additional Windows Examples of LabVIEW Calls to DLLs Windows The following examples can help you learn more about calling DLLs from LabVIEW The Call DLL VI located in examples d11 data passing Call Native Code 11b allows you to browse examples of C and C external code data types and how they interface with LabVIEW e The Play Sound VI located in the examples d11 sound playsnd 1
194. on Prototype in LabVIEW eee eee eeeeeeeeeeeees 2 9 Task 2 Complete these Fll iioui Aditi weed cin it 2 11 Required Libraries iii iii 2 12 Task 3 Build a Library Project in an External IDE eens 2 13 Microsoft Visual C 6 0 on 32 bit on Windows Platforms 2 13 Gnu C or C Compilers on Solaris or Linux eee 2 16 Metrowerks CodeWarrior on Mac OS conoconcccicnonnconcnoncnnnoncconarnnonnninnos 2 17 Project Builder on Mac OS X ocooconoccncononcononnnconocnnconnonncnnonnncnncrnnonnnos 2 17 Calling External APIS eire n e ia ta dave te teas 2 17 Common Pitfalls with the Call Library Function Node 0 eee eee 2 17 Incorrect Function Name oooooccccccoconaconncnononnnonnconocn nono nnnncnn conc conc rnncnnnos 2 18 Data TYPES catala ita At A 2 19 Constant ici a 2 19 Calling ConventiOns 20 idea 2 19 O National Instruments Corporation v Using External Code in LabVIEW Contents Example 1 Call a Shared Library that You Built eeeeeeeeeees 2 20 Complete Configuration of the Call Library Function Node 2 20 Build the Front Panel usted 2 21 Complete the Block Diagram ooooncnncnnnnncnnnnnnnnnononancnnononcnncanocancnnnono 2 21 Run the Villasana in att 2 22 Example 2 Call a Hardware Driver API ooononiccnncnocnnoncnnnonncononononncnnnonnnnnccnnos 2 22 Configure the Call Library Function Node oooonconnnnnnnonnnnnnononnninnon 2 23 Example 3 Call the Win32 API oonconcncinccconnnonconcnoncnnononcnnnonncon conc cnncr
195. onery in the cintools Metrowerks Files Project Stationery LabVIEW CIN MwPPc folder The folder contains a template for new CINs with most of the settings you need Refer to the Read Me file in the Project Stationery folder for more information To create a CIN for Mac OS Classic you need your source files and CINLib ppc mwerks in your Code Warrior project Lab VIEW installs CINLib ppc mwerks in the cintools Metrowerks Files PPC Libraries folder If you call any routines within LabVIEW such as D8SSetHandleSize or SetCINArraySize you also need the labview export stub file LabVIEW installs labview export stub in the cintools PowerPC Libraries folder If you call any routines from a system shared library you must add the appropriate shared library interface file to your project When building a CIN using Code Warrior for PPC you can set many of the preferences to whatever you want However other preferences must be set to specific values to correctly create a CIN If you do not use the project stationery make sure you set the following preferences in the CodeWarrior Preferences dialog box e Clear the Prefix File using MacHeaders does not work e Set Struct Alignment to 68K e Clear all the Entry Point fields e Set Export Symbols to Use exp file and place a copy of the file projectName exp from your cintools Metrowerks Files PPC Libraries folder in the same folder as your CodeWarrior project Rename projectNam
196. ons size rfSize cdate mdate 6 69 system specific file type 0 for directories system specific file creator 0 for folders on Mac only system specific file access rights file size in bytes data fork on Mac or entries in directory resource fork size on Mac only creation date seconds since system reference time El last modification date seconds since system ref time Using External Code in LabVIEW Chapter 6 Function Descriptions Bool32 folder indicates whether path refers to a folder Bool32 isInvisible indicates whether file is visible in File Dialog on Mac only Point location system specific desktop geographical location on Mac only Str255 owner owner in pascal string form of file or folder Str255 group group in pascal string form of file or folder FinfoRec FInfoPtr Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path fNotFound File not found fIOErr Unspecified I O error Using External Code in LabVIEW 6 70 ni com Chapter 6 Function Descriptions FGetPathType MgErr FGetPathType path typePtr Purpose Returns the type relative absolute or not a path of a path Parameters Name Type Description path Path Path whose type you want to determine typePtr int
197. or fd Parameters Name Type Description fd File File descriptor associated with the file you want to close Return Value MgErr which can contain the following errors No error noErr mgArgErr fIOErr Using External Code in LabVIEW Not a valid file descriptor Unspecified I O error 6 86 ni com FMOpen Chapter 6 Function Descriptions MgErr FMOpen fdp Purpose openMode denyMode Opens a file with the name and location specified by path for writing and reading as specified by openMode You can use denyMode to control concurrent access to the file from within LabVIEW If the function opens the file the resulting file descriptor is stored in the address referred to by fdp If an error occurs the function stores 0 in the address referred to by fdp and returns an error 3 Note Before you call this function make sure that you understand how to use the fdp parameter Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using the fdp parameter Parameters Name Type Description fdp File Address at which FMOpen stores the file descriptor for the new file If FMOpen fails it stores 0 in the address fdp Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter path Path Path of the file you want to create
198. orm simple and complex operations ranging from low level byte manipulation to routines for sorting data and managing memory When you want to use the LabVIEW manager functions inside your shared library you must include the following LabVIEW library files in your compiled project e labview 1ib for Visual C e labview sym 1ib for Symantec labview export stub for Metrowerks CodeWarrior The preceding LabVIEW library files appear in the cintools directory of your LabVIEW installation Specifically you need the LabVIEW manager functions if you intend to do any of the following tasks e Allocate free or resize arrays strings or other data structures that are passed into or out of your library from LabVIEW e Work with LabVIEW Path data types e Work with file refnums inside your library e Use any of the Support Manager functions Refer to Chapter 6 Function Descriptions for more information about the manager functions 2 12 ni com Chapter 2 Shared Libraries DLLs Task 3 Build a Library Project in an External IDE The process of building a library project is specific to each integrated development environment IDE and each operating system This section describes the following compiler platform combinations that you can use to build shared libraries to use in LabVIEW e Microsoft Visual C on Windows e Gnu C C on UNIX e Metrowerks CodeWarrior on Mac Classic e Apple s Project Builder for Mac OS X Microso
199. ory Return Value A handle to the block of memory to which p refers If an error occurs this function returns NULL National Instruments Corporation 6 29 Using External Code in LabVIEW Chapter 6 Function Descriptions AZSetHandleSize DSSetHandleSize Mg Mg Err AZSetHandleSize h Err DSSetHandleSize h Purpose Changes the size of the block of memory referenced by the specified handle Parameters Name Type Description h UHandle Handle you want to resize size int32 New size in bytes of the handle size size While LabVIEW arrays are stored in DS handles do not use this function to resize array handles Many platforms have memory alignment requirements that make it difficult to determine the correct size for the resulting array Instead use either NumericArrayResize or SetCINArraySize Refer to the Resizing Arrays and Strings section of Chapter 4 Programming Issues for CINs for information about using NumericArrayResize and SetCINArraySize Do not use these functions on a locked handle Return Value MgErr which can contain the following errors No error Not enough memory to perform the operation Handle or pointer not in specified zone Using External Code in LabVIEW noErr mFullE mZoneE 6 30 ni com AZSetHSzClr DSSetHSzClr Chapter 6 Function Descriptions MgErr AZSetHSzClr h MgErr DSSetHSzClr h Purpose size size
200. ou can edit this list with the System control panel accessory For example if you installed LabVIEW for Windows inc Program Files National Instruments LabVIEW x x the CIN tools directory should be c Program Files National Instruments LabVIEW x x cintools where x xis the LabVIEW version number In this instance you would add the following line to the user environment variables using the System control panel CINTOOLSDIR c Program Files National Instruments LabVIEW x x cintools Windows Me 98 Modify your AUTOEXEC BAT to set CINTOOLSDIR to the correct value Build a 1vm file LabVIEW Makefile for your CIN You must specify the following items e name is the name of your CIN for example mult e typeis CIN include CINTOOLSDIR ntlvsb mak 3 16 ni com Chapter 3 CINs To define additional include paths for a CIN you must add a CINCLUDES line to the 1vm file as shown in the following example code CINCLUDE Ipathnames You must include the I argument on the line pathnames is the directory where you look for other includes If your CIN uses extra object files you can specify the objFiles option You do not need to specify the codeDir parameter because the code for the CIN must be in the same directory as the makefile You do not need to specify the wcDir parameter because the CIN tools can determine the location of the compiler You can compile the CIN code using the following co
201. ou can pass the same path variable for the new path that you use for startPath or relPath Therefore you can call this function in the following three ways FRelPath star the relati FRelPath star the new pa FRelPath star the new pa tPath endPath relPath ve path is returned in a third path variable tPath endPath startPath th writes over the old startPath tPath endPath endPath th writes over the old endPath Parameters Name Type Description startPath Path Absolute path from which you want the relative path to be computed endPath Path Absolute path to which you want the relative path to be computed relPath Path Path returned by AddPath Return Value Mg no Err which can contain the following errors Err E mgArgErr mFull ESI LE Using External Code in LabVIEW No error A bad argument was passed to the function Verify the path Insufficient memory 6 108 ni com FRemove Chapter 6 Function Descriptions MgErr FRemove path Purpose Deletes a file or a directory If an error occurs this function does not remove the file or directory Parameters Name Type Description path Path Path of the file or directory you want to delete Return Value MgErr which can contain the following errors No error A bad argument was passed to the function Verify the path File not found
202. ou must pass the size of the array dimension s information to your DLL in a separate variable e Never resize an array or perform operations that might change the length of the array data passed from LabVIEW Resizing might cause a crash because the pointer sent is not an allocated block but points into the middle of an allocated block e To return an array of data you should allocate an array of sufficient size in LabVIEW pass the array to your function and have this array act as the buffer If the data takes less space you can return the correct size as a Separate parameter and then on the calling diagram use array subset to extract the valid data Remember that the Windows API does not use LabVIEW array handles so with functions that are part of the Windows API you can use only Array Data Pointers If you pass the array data as a LabVIEW Array Handle you can use LabVIEW CIN functions to resize the array In order to call LabVIEW CIN functions your compile must include the correct LabVIEW library file which is located within the LabVIEW cintools directory Table 2 4 lists different compilers and the correct LabVIEW library file to use with the compiler National Instruments Corporation 2 37 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs String Data Using External Code in LabVIEW Table 2 4 Compilers and the LabVIEW Library File Used with Each Compiler Compiler LabVIEW Library File Code
203. oubl doubl doubl doubl doubl doubl doubl doubl doubl doubl 70707 0 0 007 0 0 0 00 0 0 0 O sqrt doubl tan double acos doubl asin doubl atan2 doub ceil double cosh double floor double fmod double frexp double ldexp double log10 double modf double pow double sinh double tanh double ee r e e le e Chapter 6 Function Descriptions double double int int double double Individual Function Descriptions The remainder of this chapter describes individual CIN functions you can use with LabVIEW National Instruments Corporation 6 9 Using External Code in LabVIEW Chapter 6 Function Descriptions Abs int32 Abs n Purpose Returns the absolute value of n unless n is 23 in which case the function returns the number unmodified Parameters Name Type Description n int32 int32 whose absolute value you want to determine Using External Code in LabVIEW 6 10 ni com ASCIITime Chapter 6 Function Descriptions CStr ASCIITime secs Purpose Returns a pointer to a string representing the date and time of day corresponding to seconds after January 1 1904 12 00 a m UT This function uses the same date format as that returned by the DateCString function using a mode of 2 The date is followed by a space The time is in the same format as that returned by the TimeCStrin
204. ourth line sets x equal to the value at address myInt32P plus 7 The last line frees the pointer The following code is the same example using handles instead of pointers int32 myInt32H myInt32H int32 DSNewHandle sizeof int32 myInt32H 5 x myInt32H 7 DSDisposeHandle myInt32H National Instruments Corporation 4 27 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs The first line declares the variable myInt32H as a handle to a 32 bit signed integer Strictly speaking the first line declares myInt32H as a pointer to a pointer to an int32 As with the previous example the first line does not allocate memory for the int 32 The first line creates memory for an address and associates the name myInt32H with that address The H at the end of the variable name is a convention used in this example to indicate the variable is a handle The second line creates a block of memory in the data space large enough to hold a single int32 DSNewHandle places the address of the memory block as an entry in the master pointer list and returns the address of the master pointer entry Finally the second line sets myInt32H to refer to the master pointer The third line places the value 5 in the memory location to which myInt 32H refers Because myInt32H is a handle you use the operator twice to get to the data The fourth line sets x equal to the value referenced by myInt32H plus 7 The last line frees t
205. p CPStrBuf CPStrCmp CPStrIndex CPStrInsert CPStrLen CPStrRemove 6 6 ni com National Instruments Corporation Chapter 6 CPStrReplace CPStrSize CToPStr FileNameCmp FileNameIndCmp FileNameNCmp FPrintf HexChar IsAlpha IsDigit IsLower IsUpper LStrBuf LStrCmp LStrLen LStrPrintf LToPStr PPrintf PPrintfp PPStrCaseCmp PPStrCmp PStrBuf PStrCasecmp PStrCat PStrCmp PStrCpy PStrLen PStrNCpy PToOCStr PToLStr SPrintF SPrintfp StrCat Function Descriptions 6 7 Using External Code in LabVIEW Chapter 6 Function Descriptions trCmp trCpy trLen trNCaseCmp S S S S StrNCmp S trNCpy ToLower ToUpper e Synchronization functions Occur PostLVUserEvent e Utility functions BinSearch QSort Unused Time functions ASCIITime DateCString DateToSecs MilliSecs E SecsToDate TimeCString TimeInSecs Mathematical Operations In addition to the mathematical operations in the preceding list LabVIEW Using External Code in LabVIEW supports a number of other mathematical functions The following functions are implemented as defined in The C Programming Language by Brian W Kernighan and Dennis M Ritchie double atan double double cos double double exp double double fabs double double log double double sin double 6 8 ni com doubl doubl doubl doubl doubl doubl d
206. ple threads more than one execution thread can call the CIN at the same time Add the following code to your c file if you want a CIN to run in the current execution thread of the block diagram CIN MgErr CINProperties int32 mode void data switch mode case kCINIsReentrant Bool32 data TRUE return noErr break return mgNotSupported Using External Code in LabVIEW 5 8 ni com Chapter 5 Advanced Applications If you read and write a global or static variable or call a non reentrant function within your CINs keep the execution of those CINs in a single thread Even if a CIN is marked reentrant the CIN functions other than CINRun are called from the user interface thread For example CINInit and CINDispose are never called from two different threads at the same time CINRun might be running when the user interface thread is calling CINInit CINAbort or any of the other functions To be reentrant the CIN must be safe to call CINRun from multiple threads and safe to call any of the other CIN procedures and CINRun at the same time Other than CINRun you do not need to protect any of the CIN procedures from each other because calls to them are always in one thread Code Globals and CIN Data Space Globals When you declare global or static local data within a CIN code resource LabVIEW allocates storage for that data LabVIEW maintains your globals across calls to various routines When you allocate
207. pletes the following steps when compiling a VI and before disposing of the current data space 1 Calls the CINDispose routine for each reference to the code resource within the VI s being compiled Calling the CINDispose routine gives the code resource a chance to dispose of any old results it is managing 2 Compiles the VI and creates a new data space for the VI s being compiled LabVIEW creates multiple data spaces for reentrant VIs 3 Calls CINInit for each reference to the code resource within the compiled VI s Calling CINInit gives the code resource a chance to create or initialize any data it wants to manage Click the Run button in a VI to run the VI When LabVIEW encounters a Code Interface Node it calls the CINRun routine for that node When you save a VI LabVIEW calls the CINSave routine for that VI Calling the CINSave routine gives you the chance to save any resources such as something you loaded in CINLoad When you save a VI LabVIEW creates a new version of the file even if you are saving the VI with the same name If the save is successful LabVIEW deletes the old file and renames the new file with the original name Therefore you need to save in CINSave anything you expect to be able to load in CINLoad When you abort a VI LabVIEW calls the CINAbort routine for every reference to a code resource contained in the VI being aborted LabVIEW also calls the CINAbort routine of all actively running subVIs If a CIN is
208. pose size Swaps size bytes between the section of memory referred to by ps and pd The source and destination memory blocks should not overlap Parameters Name Type Description ps UPtr Pointer to source pd UPtr Pointer to destination size int32 Number of bytes you want to move O National Instruments Corporation 6 173 Using External Code in LabVIEW Chapter 6 Function Descriptions TimeCString CStr TimeCString secs Purpose fmt Returns a pointer to a string representing the time of day corresponding to t seconds after January 1 1904 12 00 a m UT In SPARCstation this function accounts for international conventions for representing dates 3 Note This function was formerly called TimeString Parameters Name Type Description secs uInt32 Seconds since January 1 1904 12 00 a m fmt int32 UT Indicates the format of the returned time string using the following values e 0 hh mm format where hh is the hour 0 through 23 with 0 as midnight and the mm is the minute 0 through 59 e 1 hh mm ss format where hh is the hour mmis the minute o through 59 and ssis the second o through 59 Return Value The time as a C string Using External Code in LabVIEW 6 174 ni com Chapter 6 Function Descriptions TimelnSecs uint32 TimeInSecs Return Value The current date and time in seconds relative to January 1 19
209. put and returns a 32 bit signed integer as an output as shown in Figure 3 5 Figure 3 5 CIN with 32 bit Signed Integer Input and 32 Bit Signed Integer Output The following code excerpt is the initial c file for the CIN in Figure 3 5 CIN source file include extcode h MgErr CINRun int32 numIn int32 numOut MgErr CINRun int32 numIn int32 numOut Insert code here return noErr You can write eight routines for the CIN in Figure 3 5 The CINRun routine is required and the others are optional If an optional routine is not present LabVIEW uses a default routine when building the CIN The preceding c file is a template in which you must write C code The extcode h file which is in the cintools directory in LabVIEW is automatically included because it defines basic data types and a number of routines that can be used by CINs ext code h also defines some constants and types whose definitions might conflict with the definitions of system header files The cintools directory also contains hosttype h which resolves the differences between definitions in extcode h and definitions National Instruments Corporation 3 7 Using External Code in LabVIEW Chapter 3 CINs Using External Code in LabVIEW in system header files hosttype h also includes many of the common header files for a given platform Always use include extcode h at the beginning of your source code If your code needs
210. r Pointer to a long Pascal string Return Value The address of the string data of the long Pascal string National Instruments Corporation 6 133 Using External Code in LabVIEW Chapter 6 Function Descriptions LStr mp LStrPtr LStrCmp lip Purpose 12p Lexically compares two long Pascal strings to determine whether one is less than equal to or greater than the other This comparison is case sensitive Parameters Name Type Description lip LStrPtr Pointer to a long Pascal string 12p LStrPtr Pointer to a long Pascal string Return Value lt 0 0 or gt 0 if I1p is less than equal to or greater than 12p respectively Returns lt 0 if Mp is an initial substring of I2p Using External Code in LabVIEW 6 134 ni com LStrLen Macro Chapter 6 Function Descriptions int32 LStrLen s Purpose Returns the length of a long Pascal string that is s gt cnt Parameters Name Type Description s LStrPtr Pointer to a long Pascal string Return Value The number of characters in the long Pascal string National Instruments Corporation 6 135 Using External Code in LabVIEW Chapter 6 Function Descriptions LToPStr int32 LToPStr lstrp Purpose pstr Converts a long Pascal string to a Pascal string If the long Pascal string is more than 255 characters this function converts only the first 255 characters The
211. r by two CIN MgErr CINRun int32 num_in int32 num_out num_out num_in 2 return noErr Refer to the Passing Parameters section of Chapter 4 Programming Issues for CINs for information and examples about how LabVIEW passes data to a CIN 3 8 ni com Chapter 3 CINs Step 4 Compile the CIN Source Code You must compile the source code for the CIN as a LabVIEW subroutine 1sb file After you compile your C C code in one of the compilers that LabVIEW supports you use a LabVIEW utility that puts the object code into the 1sb format Because the compiling process is often complex LabVIEW includes utilities that simplify the process These utilities take a simple specification for a CIN and create object code you can load into LabVIEW The specific utility you use depends on the platform and compiler you use Refer to the following sections for more information about compiling on your platform ay Note The LabVIEW Base Development system can use existing 1sb files but cannot create new 1sb files You can create 1sb files in the LabVIEW Full and Professional Development Systems Mac OS X CINs compiled for LabVIEW on Mac OS Classic are not compatible with LabVIEW on Mac OS X You must compile CINs into the Mach O binary format and use the natural alignment of data in your compiler settings to rebuild the CINs you created in Mac OS Classic LabVIEW includes a template to help you build CINs using the Project
212. r relative to a specific location or absolute that is the full path With file manager routines you can create and compare paths determine characteristics of paths and convert a path between platform specific descriptions and the platform independent form Using External Code in LabVIEW 4 28 ni com Chapter 4 Programming Issues for CINs Applications that manipulate files can use the functions in the file manager The file manager routines support basic file operations such as creating opening and closing files writing data to files and reading data from files In addition you can use file manager routines to create directories determine characteristics of files and directories and copy files File manager routines use a LabVIEW data type for file path names called Paths that indicates a file or directory path independent of the platform You can translate a Path to and from the conventional format a host platform uses for describing a file pathname Refer to the File Manager section of this chapter for more information about the file manager Identifying Files and Directories When you perform operations on files and directories you need to identify the target of the operation The platforms LabVIEW supports use a hierarchical file system meaning files are stored in directories possibly nested several levels deep These hierarchical file systems support the connection of multiple discrete storage media called volumes For example DO
213. r the Call Library Function Node returns to the right terminal of the top pair of terminals If the return type is Void the top pair of terminals is unused Each additional pair of terminals corresponds to a parameter in the Parameter list of the Call Library Function Node To pass a value to the Call Library Function Node wire to the left terminal of a terminal pair To read the value of a parameter after the Call Library Function Node call wire from the right terminal of a terminal pair Figure 2 2 shows a Call Library Function Node that has a return type of Void a string parameter and a numeric parameter Figure 2 2 Call Library Function Node with Return Value of Void and Two Parameters National Instruments Corporation 2 3 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Configuring Return Type For return type you can set Type to Void Numeric or String Void is only available for return type and is not available for parameters Use Void for the return type if your function does not return any values Even if the function you call returns a value you can use Void for the return type When the function returns a value and you select Void as the return type the value returned by the function is ignored Refer to the Numeric section of this chapter for information about the numeric parameter type and to the String section of this chapter for information about the string parameter type 3 Note If
214. rameters Name Type Description p Path Path you want to convert to a string txt LstrHandle Address at which FPathToAZString stores the resulting string If nonzero the function assumes it is a valid handle resizes the handle fills in its value and stores the handle at the address referred to by txt Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value MgErr which can contain the following errors noErr No error mgArgErr A bad argument was passed to the function Verify the path mFullErr Insufficient memory fIOErr Unspecified I O error National Instruments Corporation 6 103 Using External Code in LabVIEW Chapter 6 Function Descriptions FPathToDSString MgErr FPathToDSString p Purpose txt Converts a path to an LStr and stores the string as a data space zone handle The LStr contains the platform specific syntax for the path Parameters Name Type Description Path Path you want to convert to a string txt LstrHandle Address at which FPathToDSString stores the resulting string If nonzero the function assumes it is a valid handle resizes the handle fills in its value and stores the handle at the address referred to by txt Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter Return Value M
215. ray of 8 bit integers than C strings because of the possibility of having NULL values in the string When you are passing a LabVIEW Array Handle or LabVIEW String Handle from the Call Library Function Node to your DLL you can use the LabVIEW CIN functions to resize or create an array or string Refer to the Required Libraries section of this chapter for more information about CIN functions 2 40 ni com CINs This chapter discusses the LabVIEW Code Interface Node CIN which is a block diagram node that links C C source code to LabVIEW 3 Notes Itis technically possible to write CINs in a language other than C or C if the CIN entry points such as CINRun CINLoad and so on are declared as extern Cc However National Instruments recommends using a shared library DLL rather than a CIN if you want to use a language other than C or C Refer to Chapter 2 Shared Libraries DLLs for information about DLLs LabVIEW does not support the creation of external subroutines If you want to share code among multiple CINs use DLLs Refer to Chapter 2 Shared Libraries DLLs for information about shared libraries Supported Languages The interface for CINs supports a variety of compilers although not all compilers can create code in the correct executable format External code must be compiled as a form of executable appropriate for a specific platform The code must be relocatable because LabVIEW loads external code into the sa
216. reference the code resource and regardless of whether the surrounding VI is reentrant only one copy of the global variables is ever in memory and the value of the global variables are consistent When you create a CIN LabVIEW allocates a CIN data space strictly for the use of the CIN A CIN data space is a 4 byte storage location in the VI data space s Each CIN can have one or more CIN data spaces reserved for the CIN depending on how many times the CIN appears in a VI or collection of VIs You can use this CIN data space to store global data on a per data space basis as described in the Code Globals and CIN Data Space Globals section Figure 5 1 shows a simple example of data storage spaces for one CIN Global Storage VI Data Space Code Resource 4 byte CIN Code Globals Data Space Data Space Globals Figure 5 1 Data Storage Spaces for One CIN A CIN references the code resource by name using the name you specified when you created the code resource When you load a VI containing a CIN LabVIEW looks in memory to see if a code resource with the desired name is already loaded If a code resource with the desired name is already 5 2 ni com Chapter 5 Advanced Applications loaded into memory LabVIEW links the CIN to that code resource for execution purposes Linking the CIN to the code resource behaves the same way as links between VIs and subVIs When you try to ref
217. rements because the memory is allocated for the duration of the application Dynamic Memory Allocation With dynamic memory allocation you reserve memory when you need it and free memory when you are no longer using it Dynamic allocation requires more work than static memory allocation because you have to determine memory requirements and allocate and deallocate memory as necessary Using External Code in LabVIEW 4 24 ni com Chapter 4 Programming Issues for CINs The LabVIEW memory manager supports the following methods of dynamic memory allocation e Using pointers to allocate memory e Using handles to allocate memory Using Pointers for Dynamic Memory Allocation The more conventional method uses pointers to allocate memory With pointers you request a block of memory of a certain size The routine returns the address of the block of memory to your CIN When you no longer need the block of memory you call a routine to free the block of memory You can use the block of memory to store data You reference the data stored in the block of memory by using the address the manager routine returned when you created the pointer You can make copies of the pointer and use them in multiple places in your application to refer to the same data Pointers in the LabVIEW memory manager are nonrelocatable which means the manager never moves the memory block to which a pointer refers while that memory is allocated for a pointer Because other refe
218. rences to the memory block do not become out of date not moving the memory block allocated to a pointer avoids problems that occur when you need to change the amount of memory allocated to a pointer If you need more memory sufficient memory might not exist to expand the memory space of the pointer without moving the memory block to a new location If an application had multiple references to the pointer moving the memory block to a new location causes problems because each pointer refers to the old memory address of the data Using invalid pointers can cause severe problems Using Handles for Dynamic Memory Allocation A second form of memory allocation uses handles As with pointers when you allocate memory using handles you request a block of memory of a certain size The memory manager allocates the memory and adds the address of the memory block to a list of master pointers The memory manager returns a handle that is a pointer to the master pointer If you reallocate a handle and it moves to another address the memory manager updates the master pointer to refer to the new address If you look up the correct address using the handle you access the correct data Use handles to perform most memory allocation in LabVIEW Pointers are available because in some cases they are more convenient and simpler to use Memory Zones LabVIEW s memory manager interface can distinguish between the following distinct sections called zones e Data spac
219. rs Name Type Description path Path Path you want to verify Return Value Boo132 which can contain the following values TRUE FALSI y Using External Code in LabVIEW Path is well formed and type is absolute or relative Path is not valid 6 76 ni com FisAPathOfType Chapter 6 Function Descriptions Bool32 FIsAPathOfType path ofType Purpose Determines whether a path is a valid path of the specified type relative or absolute Parameters Name Type Description path Path Path you want to compare to the specified type ofType int32 Type you want to compare to the path s type of Type can have the following values e fAbsPath Compare the path s type to absolute e f RelPath Compare the path s type to relative Return Value Boo132 which can contain the following values Path is well formed and type is identical to of Type TRUE FALSI National Instruments Corporation E Otherwise 6 77 Using External Code in LabVIEW Chapter 6 Function Descriptions FisAPathOrNotAPath Bool32 FIsAPathOrNotAPath path Purpose Determines whether path is a valid path or the canonical invalid path Parameters Name Type Description path Path Path you want to verify Return Value Boo132 which can contain the following values Path is well formed and type is absolu
220. rs listed in brackets lvmkmf o Makefile LVSBName LVSBName is the name of the CIN you want to build If LVSBName is foo the compiler assumes the source is foo c and names the output file foo 1sb o is the name of the makefile 1vmkm creates If you do not specify this argument the makefile name default is Makefile The created makefile will be similar to the following example code Note In the following example code entries in parentheses correspond to the Solaris cc compiler Also replace xx in 1vxx with the LabVIEW version number for example 1v70 This Makefile was generated automatically by lvmkmf CC gcc CC cc LD gcc LD 1d LDFLAGS shared LDFLAGS G XFLAGS fPIC XFLAGS K PIC CINDIR usr local lvxx cintools CFLAGS I CINDIR S XFLAGS CINLIB CINDIR libcin a MAKEGLUE CINDIR makeglueSVR4 awk AS as 3 18 ni com Chapter 3 CINs The makefile produced assumes the cin o libcin a and lvsbutil files are in certain locations If these assumptions are incorrect you can edit the makefile to correct the pathnames Step 5 Load the CIN Object Code To load the code resource right click the node and select Load Code Resource from the shortcut menu Select the 1sb file you created in the Step 4 Compile the CIN Source Code section LabVIEW loads your object code into memory and links the code to the current front panel or block diagram After you save the
221. rwise the error message Function not found in library appears Data is wired to the input terminals of all the parameters of the Call Library Function Node that you are passing to a DLL function Also check that the Library Function Node is properly configured for all input parameters Return types and data types of arguments for functions in the Call Library Function Node exactly match the data types your function uses Erroneous data type assignments can cause crashes The Call Library Function Node passes arguments to the function in the correct order Resizing of arrays and concatenation of strings can take place only under the following conditions Only when the Call Library Function Node passes a LabVIEW Array Handle or LabVIEW String Handle Only when you add labview 1ib to a Visual C project labview export stub to a Code Warrior project and labview sym lib to a Symantec project 2 34 ni com Chapter 2 Shared Libraries DLLs A Caution Never resize arrays or concatenate strings using the arguments passed directly to a function Remember the parameters you pass are LabVIEW data Changing array or string sizes might result in a crash by overwriting other data stored in LabVIEW memory a O National Instruments Corporation The Call Library Function Node passes strings of the correct type to a function C string pointers Pascal string pointers or the LabVIEW string handles The Windows API requires the
222. s the file or directory the path identifies National Instruments Corporation 4 29 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs A path can be one of the following types e Relative path e Absolute path A relative path describes the location of a file or directory relative to an arbitrary location in the file system An absolute path describes the location of a file or directory starting from the top level of the file system A path does not necessarily go from the top of the hierarchy down to the target You can often use a platform specific tag in place of a name that indicates the path should go up a level from the current location UNIX You specify the path of a file or directory as a series of names separated by the slash character If the path is an absolute path you begin the specification with a slash Indicate the path should move up a level using two periods in a row Thus the following path specifies a file README relative to the top level of the file system usr home gregg myapps README The following paths are two relative paths to the same file gregg myapps README relative to usr home myapps README relative to a directory inside of the gregg directory Windows You separate names in a path with a backslash character If the path is an absolute path you begin the specification with a drive designation followed by a colon followe
223. scussion forum or email e Training Visitni com custed for self paced tutorials videos and interactive CDs You also can register for instructor led hands on courses at locations around the world e System Integration If you have time constraints limited in house technical resources or other project challenges NI Alliance Program members can help To learn more call your local NI office or visit ni com alliance If you searched ni com and could not find the answers you need contact your local office or NI corporate headquarters Phone numbers for our worldwide offices are listed at the front of this manual You also can visit the Worldwide Offices section of ni com niglobal to access the branch office Web sites which provide up to date contact information support phone numbers email addresses and current events National Instruments Corporation A 1 Using External Code in LabVIEW Glossary A ANSI application zone asynchronous execution AZ application zone Bundle node C C string CStr CIN source code Code Interface Node code resource concatenated Pascal string CPStr CPStr National Instruments Corporation American National Standards Institute See AZ application zone Mode in which multiple processes share processor time one executing while the others for example wait for interrupts as while performing device I O or waiting for a clock tick Memory allocation se
224. se CINAbort or CINRun int32 SetDSStorage int32 newVal This routine sets the value of the 4 byte quantity in the CIN data space LabVIEW allocates for each CIN use of that code resource or the uses of the surrounding VI if the VI is reentrant It returns the old value of the 4 byte quantity in that CIN data space Call this routine only from CINInit CINDispose CINAbort or CINRun Code Globals and CIN Data Space Globals Examples Using External Code in LabVIEW The following examples illustrate the differences between code globals and CIN data space globals In both examples the CIN takes a number and returns the average of that number and the previous numbers passed to it as shown in Figure 5 4 Figure 5 4 Averaging CIN When you write your application decide whether it is appropriate to use code globals or data space globals If you use code globals calling the same code resource from multiple CINs or different reentrant VIs affects the same set of globals In the code globals averaging example the result indicates the average of all values passed to the CIN If you use CIN data space globals each CIN calling the same code resource and each VI can have its own set of globals if the VI is reentrant In the CIN data space globals averaging example the results indicate the average of values passed to a specific node for a specific data space If you have only one CIN referencing the code resource and the VI contain
225. se denyMode to control concurrent access to the file from within LabVIEW You can use the group parameter to assign the file to a UNIX group In Windows or Mac OS group is ignored If the function creates the file the resulting file descriptor is stored in the address referred to by fdp If an error occurs the function stores 0 in the address referred to by fdp and returns an error 3 Note Before you call this function make sure that you understand how to use the fdp parameter Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using the fdp parameter National Instruments Corporation 6 55 Using External Code in LabVIEW Chapter 6 Function Descriptions Parameters Name Type Description fdp File Address at which FCreateAlways stores the file descriptor for the new file If FCreateAlways fails it stores 0 in the address fdp Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter path Path Path of the file you want to create permissions int32 Permissions to assign to the new file openMode int32 Access mode to use in opening the file The following values are defined in the file extcode h openReadOnly Open for reading e openWriteOnly Open for writing openReadWrite Open for both reading and writing denyMode int32 Mode that determines what level of co
226. st have one makefile for each CIN Name the makefile by appending 1vm to the CIN name to indicate that it is a LabVIEW makefile The makefile should resemble the following pseudocode Make sure that each Dir command ends with the colon character e name name is the Name for the code and indicates the base name for your CIN The source code for your CIN should be in name c The code created by the makefile is placed in a new LabVIEW subroutine 1sb file name 1sb e type type is the type of external code you want to create For CINs use a type of CIN e codeDir codeDir is the complete pathname to the folder containing the c file used for the CIN e cinToolsDir cinToolsDir is the complete pathname to the LabVIEW cintools MPwW folder 3 12 ni com Chapter 3 CINs e LVMVers 2 is the version of CINMake script reading this 1vm file e inclDir i inclDir is optional and is the complete or partial pathname to a folder containing any additional h files e otherPPCObjFiles otherPPCObjFiles is optional and is the list of additional object files files with a o extension your code needs to compile Separate the names of files with spaces ShLibs sharedLibraryNames is optional and is a list of the link time copies of import libraries with which the CIN must be linked Each should be a complete path to the file Separate the names with spaces ShLibMaps sharedLibMappings is optional and is the co
227. steps to create the front panel of the Array Average VI 1 Place an Array control on the front panel and label it Array 2 Place a Numeric Control in the array shell and resize the array to contain four elements 3 Right click the Array control and select Reprensentation Single Precision from the shortcut menu 4 Place a Numeric Indicator on the front panel and label it Avg Value to display the result of your averaging calculation 5 Right click the Avg Value indicator and select Reprensentation Single Precision from the shortcut menu 6 Place a Numeric Indicator on the front panel and label it Error to display any errors that your VI generates 7 Right click the Error indicator and select Reprensentation Long from the shortcut menu Figure 2 5 shows the Array Average VI front panel Array Avg Value S J 0 z Error Figure 2 5 Array Average VI Front Panel Complete the Block Diagram Complete the following steps to complete the block diagram of the Array Average VI Pe SAN O National Instruments Corporation Wire Array to the a input of the Call Library Function Node Place an Array Size function on the block diagram Wire Array to the input of the Array Size function Wire the Array Size function output to the size input of the Call Library Function Node 2 21 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs 5 Right click the avg input of the Call Library Functio
228. t 4 32 Chapter 5 Advanced Applications CIN Route Sisi perilla neah 5 1 Data Spaces and Code Resources ponini i N nano nonn ocn cnn non AN E 5 1 One Reference to the CIN in a Single Vl ononnnoncnninociccnnoncnnnonnnononnnonncrnnonnc ron cano rnncnnnno 5 3 MACH GA Vii tl iia 5 3 Unloading a Vivi glia wastes iad es eae 5 4 Loading a New Resource into the CIN ooooconconoconocconanoncnncnnncononnncnnonaconncnn conos 5 4 Compiliing a Vico tidad A Mae ni 5 4 O A NO 5 5 Saving a Mii ita bs 5 5 Aborting a VEe rrearen odiada 5 5 Multiple References to the Same CIN in a Single VI ooonnnnncnicnonicanininonacininccnnraninannnons 5 6 Multiple References to the Same CIN in Different VIs oooooncnononnnconnnonconconnnnnnoncnnnonnos 5 7 Single Threaded Operating SysteMS oooconncnocnnonconnnoncnnnonncononnncnnnonnonnc rca naninnons 5 7 Multithreaded Operating Systems eee eeceseceeeeseeseecseeeeeeasenseeaeenaes 5 8 Code Globals and CIN Data Space Globals oooonocnicnnoniccononccanonnnononnonnconccnnonnccnnonancnnons 5 9 Code Globals and CIN Data Space Globals Examples ee eee 5 10 Using Eode GlobalS isaac 5 11 Using CIN Data Space Globals o oonconcnoconocnonnnoncononanonanonncancrnnonnno 5 12 Chapter 6 Function Descriptions Memory Manager Functions 0 0 eee iep e a e D a aeei 6 1 Fil Manager Punictr ms perei eies a E A EERE EE E a a e 6 2 Permissions for Files and Directories ssessseessereresreseeresreresreresresrsr
229. t reference to the code resource is removed from memory LabVIEW calls the CINUn1oad routine for that code resource once giving you the chance to dispose of anything allocated in CINLoad As with CINDispose and CINInit CINUnload is called for each CINLoad For example if you loaded some resources from a file in CINLoad you can free the memory those resources are using in CINUnload After LabVIEW calls CINUnload the code resource itself is unloaded from memory Loading a New Resource into the CIN Compiling a VI Using External Code in LabVIEW If you load a new code resource into a CIN the old code resource is first given a chance to dispose of anything it needs to dispose LabVIEW calls CINDispose for each CIN data space and each reference to the code resource followed by the CINUn1oad for the old resource After the calls to CINDispose and CINUn1oad the new code resource is given a chance to perform any initialization it needs to perform LabVIEW calls CINLoad for the new code resource After LabVIEW calls CINLoad it calls the CINInit routine once for each data space and each reference to the code resource When you compile a VI LabVIEW recreates the VI data space including resetting all uninitialized shift registers to their default values Also your CIN is given a chance to dispose or initialize any storage it manages 5 4 ni com Running a VI Saving a VI Aborting a VI Chapter 5 Advanced Applications LabVIEW com
230. te relative or not a path Path is not valid TRUE FALSE Using External Code in LabVIEW ni com FisARefNum Chapter 6 Function Descriptions Boo132 FIsARefNum refNum Purpose Determines whether refNum is a valid file refnum Parameters Name Type Description refNum LVRefNum File refnum you want to verify Return Value Boo132 which can contain the following values File refnum has been created and not yet disposed File refnum is not valid TRUE FALSE National Instruments Corporation 6 79 Using External Code in LabVIEW Chapter 6 Function Descriptions FlsEmptyPath Bool32 FIsEmptyPath path Purpose Determines whether path is a valid empty path Parameters Name Type Description path Path Path you want to verify Return Value Boo132 which can contain the following values Path is well formed and empty and type is absolute or relative Path is not a valid empty path TRUE FALSE Using External Code in LabVIEW ni com Chapter 6 Function Descriptions FListDir Mg Err FListDir path list typeH Purpose Determines the contents of a directory The function fills the AZ handle passed in list with a CPStr where the ent field specifies the number of concatenated Pascal strings that follow in the str 1 field Refer to the Data Types section of Chapter 4 Programming Issues for CINs
231. tenating Two Strings In this example the CIN concatenates two strings and uses an input output terminal The top left terminal of the CIN takes in the first string as an input parameter to the CIN The top right terminal of the CIN returns the result of the concatenation This example shows only the diagram and the code National Instruments Corporation 4 9 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs Complete the following steps to create the CIN 1 To create the CIN follow the instructions in the Creating a CIN section of Chapter 3 CINs Figure 4 3 shows the block diagram for this CIN Figure 4 3 Istrcat vi Block Diagram 2 Save the VI as lstrcat vi Create a c file for the CIN and name it 1strcat c LabVIEW creates the following c file CIN source file El tinclude extcode h CIN MgErr CINRun LStrHandle varl LStrHandle var2 CIN MgErr CINRun LStrHandle varl LStrHandle var2 ENTER YOUR CODE HERE return noErr 4 Fill in the CINRun function with the following example code CIN MgErr CINRun LStrHandle strhl LStrHandle strh2 int32 sizel size2 newSize MgErr err sizel LStrLen strh1 size2 LStrLen strh2 Using External Code in LabVIEW 4 10 ni com Chapter 4 Programming Issues for CINs newSize sizel size2 if err NumericArrayResize uB 1L UHandle amp strh1 newSize goto out
232. tern cC clause as shown in the following prototype extern C long MyDLLFunction long nInput unsigned long nOutput void argl long MyDLLFunction long nInput unsigned long nOutput void argl Insert Code Here ay Note If you disable C decoration of a function the compiler cannot create polymorphic versions of the function Task 2 Complete the c File The Call Library Function Node generates the following source code skeleton in myshared c Call Library Source File include extcode h long avg_num float a long size float avg long avg_num float a long size float avg Insert Code Here Replace the Insert Code Here spacer with the following function code making sure to place the code within the pair of curly braces int i float sum 0 National Instruments Corporation 2 11 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Using External Code in LabVIEW if a NULL for i 0 i lt size i sum sum a i else return 1 avg sum size return 0 Required Libraries This simple example requires no header files When you build more complex shared libraries you must include header files for all related libraries For example a Windows shared library project might need to include windows h In another instance a project might need to include extcode h the header file for the set of LabVIEW manager functions that perf
233. the function you are calling returns a data type not listed choose a return data type the same data size as the one returned by the function For example if the function returns a char data type use an 8 bit unsigned integer A call to a function in a DLL cannot return a pointer because there are no pointer types in LabVIEW However you can specify the return type as an integer that is the same size as the pointer LabVIEW then treats the address as a simple integer and you can pass it to future DLL calls Using External Code in LabVIEW Adding and Deleting Parameters To add parameters to the Call Library Function Node click the Add a Parameter Before button or the Add a Parameter After button To remove a parameter click the Delete this Parameter button Editing Parameters Use the Parameter pull down menu to select the return value or a parameter for editing When selected you can edit the Parameter name to something more descriptive which makes it easier to switch between parameters The Parameter name does not affect the call but it is propagated to output wires Also you can edit all fields in the Parameter section for the selected parameter Selecting the Parameter Type Use the Type pull down menu to indicate the type of each parameter You can select from the following parameter types Numeric e Array String Waveform 2 4 ni com Chapter 2 Shared Libraries DLLs e Digital Waveform e Digital Table e A
234. the time specified uses daylight savings time Parameters Name Type Description secs uInt32 Seconds since January 1 1904 12 00 a m UT dateRecordP DateRec Pointer to a DateRec structure SecsToDate stores the converted date in the fields of the date structure referred to by dateRecordP Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter National Instruments Corporation 6 163 Using External Code in LabVIEW Chapter 6 Function Descriptions SetALong Macro void SetALong p x Purpose Stores an int32 at the address specified by a void pointer In SPARCstation this function can retrieve an int32 at any address even if it is not long word aligned Parameters Name Type Description p void Address at which you want to store an int32 Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter x int32 Value you want to store at the specified address Using External Code in LabVIEW 6 164 ni com SetCINArraySize Chapter 6 Function Descriptions Mg Err SetCINArraySize Purpose Resizes a data handle based on the data structure of an argument that you pass to the CIN This function does not set the array dimension field Parameters Name Type Description dataH UHandle Handle you want to resize paramNum int32 Number for th
235. ther The source and destination memory blocks can overlap Parameters Name Type Description ps UPtr Pointer to source pd UPtr Pointer to destination size int32 Number of bytes you want to move Using External Code in LabVIEW 6 140 ni com NumericArrayResize Chapter 6 Function Descriptions MgErr NumericArrayResize int32 typeCode int32 numDims Uhandle dataHP int32 totalNewSize Purpose Resizes a data handle that refers to a numeric array This routine also accounts for alignment issues It does not set the array dimension field If dataHP is NULL LabVIEW allocates a new array handle in dataHP Parameters Name Type Description typeCode int32 Data type for the array you want to resize numDims int32 Number of dimensions in the data structure to which the handle refers dataHP UHandle Pointer to the handle you want to resize totalNewSize int32 New number of elements to which the handle should refer Return Value MgErr which can contain the following errors noErr No error MFullErr Not enough memory to perform the operation mZoneErr Handle or pointer not in specified zone Possible Values for this Type Code Input Data Type Type Code numbers in hexadecimal 8 bit integer 01 oriB 16 bit integer 02 oriW 32 bit integer 03 or iL 8 bit unsigned integer 05 or uB 16 bit unsigned integer 06 or uW 32 bit unsigned integer 07
236. ting int32 b uInt8 Low order byte of the high word of the resulting int32 c uInt8 High order byte of the low word of the resulting int32 d uInt8 Low order byte of the low word of the resulting int32 Return Value The resulting int32 Using External Code in LabVIEW 6 34 ni com ClearMem Chapter 6 Function Descriptions void ClearMem p size Purpose Sets size bytes starting at the address referenced by p to 0 Parameters Name Type Description p UPtr Pointer to block of memory you want to clear size int32 Number of bytes you want to clear National Instruments Corporation 6 35 Using External Code in LabVIEW Chapter 6 Function Descriptions CPStrBuf Macro uChar CPStrBuf sp Purpose Returns the address of the first string in a concatenated list of Pascal strings that is the address Of sp gt str Parameters Name Type Description sp CPStrPtr Pointer to a concatenated list of Pascal strings Return Value The address of the first string of the concatenated list of Pascal strings Using External Code in LabVIEW 6 36 ni com CPStrCmp Chapter 6 Function Descriptions int32 CPStrCmp slp Purpose s2p Lexically compares two concatenated lists of Pascal strings to determine whether one is less than equal to or greater than the other This comparison is case sensitive The function compares the lists as
237. tion in a way that allows the DLL to correctly interpret the data Create a skeleton c file from the current configuration of the Call Library Function Node By viewing the c file you can determine whether LabVIEW will pass the data in a manner compatible with the DLL function You then can make any necessary adjustments Refer to the Task 2 Complete the c File section of this chapter for information about creating a skeleton c file Calling Functions That Expect Other Data Types You might encounter a function that expects a data type LabVIEW does not use For example you cannot use the Call Library Function Node to pass an arbitrary cluster or array of nonnumeric data If you need to call a function that expects other data types use one of the following methods Depending on the data type you might be able to pass the data by creating a string or array of bytes that contains a binary image of the data you want to send You can create binary data by typecasting data elements to strings and concatenating them e Write a library function that accepts data types that LabVIEW does use Use parameters the library function expects to build the data structures Call the library function e Write a CIN that can accept arbitrary data structures Refer to Chapter 3 CINs for more information about writing CINs Building a Shared Library DLL Building external code libraries to call from LabVIEW consists of the following basic tasks
238. tive check the handle before using it to determine whether it has become an empty handle Parameters Name Type Description National Instruments Corporation UHandle 6 21 Application zone handle you want to mark as purgative Using External Code in LabVIEW Chapter 6 Function Descriptions AZHUnlock MgErr AZHUnlock h Purpose Unlocks the memory referenced by the application zone handle h so it can be moved This means that the memory manager can move the block of memory to which the handle refers if other memory operations need space Parameters Name Type Description h UHandle Application zone handle you want to unlock Return Value MgErr which can contain the following errors noErr mZonel Using External Code in LabVIEW No error Handle or pointer not in specified zone 6 22 ni com Chapter 6 Function Descriptions AZMaxMem DSMaxMem int32 AZMaxMem int32 DSMaxMem Purpose Returns the size of the largest block of contiguous memory available for allocation Return Value int32 the size of the largest block of contiguous memory available for allocation National Instruments Corporation 6 23 Using External Code in LabVIEW Chapter 6 Function Descriptions AZMemStats DSMemStats void AZMemStats MemStatRec msrp void DSMemStats MemStatRec msrp Purpose Returns various
239. to make system calls also use tinclude hosttype h immediately after include extcode h and then include your system header files hosttype h includes only a subset of the h files for a given operating system If the h file you need is not included in hosttype h you can include it in the c file for your CIN after you include hosttype h LabVIEW calls the CINRun routine when it is time for the node to execute CINRun receives the input and output values as parameters The other routines CINLoad CINSave CINUnload CINAbort CINInit CINDispose and CINProperties are housekeeping routines The housekeeping routines are called at specific times so you can take care of specialized tasks with your CIN For example LabVIEW calls CINLoad when it first loads a VI If you need to accomplish a special task when your VI loads put the code for that task in the CINLoad routine The following example code shows how to put the code for a task in the CINLoad routine CIN MgErr CINLoad RsrcFile reserved Unused reserved Insert code here return noErr In general you only need to write the CINRun routine Use the other routines when you have special initialization needs such as when your CIN must maintain some information across calls and you want to preallocate or initialize global state information The following example code shows how to fill out the CINRun routine in the c file for the CIN in Figure 3 5 to multiply a numbe
240. tp buffer Reads inCount bytes from the file specified by the file descriptor fd The function starts from the current position mark and reads the data into memory starting at the address specified by buffer Refer to the FMSeek and FMTell functions in this chapter for more information about the current position mark The function stores the actual number of bytes read in outCountp The number of bytes can be less than inCount if the function encounters end of file before reading inCount bytes The number of bytes is zero if any other error occurs Parameters Name Type Description fd File File descriptor associated with the file from which you want to read inCount int32 Number of bytes you want to read outCountp int32 Address at which FMRead stores the number of bytes read FMRead does not store any value if NULL is passed Refer to the Pointers as Parameters section of Chapter 3 CINs for more information about using this parameter buffer Uptr Address where FMRead stores the data Return Value MgErr which can contain the following errors noErr mgArgErr FEOF fIOErr National Instruments Corporation No error Not a valid file descriptor or inCount lt 0 EOF encountered Unspecified I O error Using External Code in LabVIEW Chapter 6 Function Descriptions FMSeek MgErr FMSeek fd ofst mode Purpose Sets the current position mark for a file t
241. tring pointer UINT uInt32 Windows Refer to the examples d11l data passing Call Native Code 11b for a list of more Win32 API data types Constants This section presents methods for finding the numerical values of constants in the Win32 API using MessageBox constants as examples Table 2 3 lists selected constants for MessageBox Table 2 3 Selected Constants for MessageBox MB_CANCELTRYCONTIN Constant Description MB_ABORTRETRYIGNORE An Abort Retry Ignore message box UE A Cancel Try Again Continue message box in Windows 2000 An alternative to MB_ABORTRETRYIGNORE MB_HELP A Help button to add to a message box for Windows 2000 XP Me 2000 Windows NT 4 0 and later The system sends a WM_HELP message to the owner whenever the user clicks the Help button or presses lt F1 gt MB_OK A message box with an OK button This is the default message box Using External Code in LabVIEW In Visual Studio programmers do not use the actual values of constants In LabVIEW however you need to pass the actual numeric value of the constant to the function You find these values in the header files that come with the SDK The SDK online documentation normally lists the relevant 2 26 ni com Chapter 2 Shared Libraries DLLs header file at the bottom of the help topic for a given function For MessageBox the SDK online documentation has the following statement Header
242. ttings and change Settings For to All Configurations Click the C C tab and set the category to Code Generation Select the Struct member alignment tab and select 1 byte 8 Choose a run time library Select Project Settings and change Settings for to All Configurations Select the C C tab and set the category to Code Generation Select Multithreaded DLL in the Use run time library control National Instruments Corporation 3 15 Using External Code in LabVIEW Chapter 3 CINs Using External Code in LabVIEW 10 11 12 13 Make a custom build command to run 1vsbutil Select Project Settings and change Settings for to All Configurations Select the Custom Build tab and change the Commands field as follows with the code all on a single line lt your path to cintools gt lvsbutil TargetName d S WkspDir OutDir Change the Output fields to OutDir TargetName 1sb For Visual C NET compiler only Add lt CINTOOLSDIR gt lvsbmain def to the Linker Input Module Definition File field Click the File View tab in the Work Space window Open your c file and replace Insert code here with your code Select Build Build projectName dll where projectName is the name of your project Visual C Command Line This section describes using command line tools in Windows to build CINs 1 Add a CINTOOLSDIR definition to your list of user environment variables Windows 2000 NT XP Y
243. u forget this point and your compiler does not warn you 2 35 Using External Code in LabVIEW Chapter 2 Shared Libraries DLLs Q Test the DLL with another program to ensure that the function and the DLL behave correctly Testing it with the debugger of your compiler or a simple C program in which you can call a function in a DLL can help you identify whether possible difficulties are inherent to the DLL or are related to LabVIEW Module Definition Files 3 Using External Code in LabVIEW In the Building a Shared Library DLL section you configured LabVIEW to use the C calling convention in the c source file you built with the Call Library Function Node In contrast you use the __stdcal11 calling convention when you call the Win32 API When you build a shared library DLL with __stdcal11 you normally use a module definition def file to export the functions in your DLL In the absence of a def file ___stdcal1 might truncate function names in an unpredictable pattern so the actual function name would be unavailable to applications that call the DLL You can associate a def file with a DLL The def file contains the statements for defining a DLL such as the name of the DLL and the functions that it exports as shown in the following example code LIBRARY myshared EXPORTS avg_num The preceding code example demonstrates the following key requirements for def files e The only mandatory entries in the def
244. uch as global variables files on disk and so on e The code is thread safe when it does not access any hardware In other words the code does not contain register level programming e The code is thread safe when it does not make any calls to any functions shared libraries or drivers that are not thread safe Using External Code in LabVIEW 2 2 ni com Chapter 2 Shared Libraries DLLs e The code is thread safe when it uses semaphores or mutexes to protect access to global resources e The code is thread safe when it is called by only one non reentrant VI Refer to the Execution Properties Page topic of the LabVIEW Help for more information about reentrancy Refer to the Using LabVIEW to Create Multithreaded VIs for Maximum Performance and Reliability Application Note for more information about multithreading in LabVIEW Setting the Calling Convention Use the Calling Conventions pull down menu in the Call Library Function dialog box to select the calling convention for the function The default calling convention is C Windows You also can use the standard Windows calling convention stdcall Refer to the documentation for the DLL you want to call for the appropriate calling conventions Configuring Parameters This section discusses the return value and how to add parameters to the Call Library Function Node Initially the Call Library Function Node has no parameters and has a return type of Void The return type fo
245. uments Corporation xiii Using External Code in LabVIEW About This Manual monospace italic Italic text in this font denotes text that is a placeholder for a word or value that you must supply Platform Text in this font denotes a specific platform and indicates that the text following it applies only to that platform Related Documentation The following documents contain information that you might find helpful as you read this manual e LabVIEW User Manual e LabVIEW Help e Using LabVIEW with TCP IP and UDP Application Note e Using Apple Events and the PPC Toolbox to Communicate with LabVIEW Applications on the Macintosh Application Note e Using LabVIEW to Create Multithreaded VIs for Maximum Performance and Reliability Application Note Sun users also might find the following document helpful e Sun Workshop CD ROM Sun Microsystems Inc U S A Linux users also might find the following document helpful e The GNU C Compiler Reference Manual Free Software Foundation 1989 2000 Windows users also might find the following documents helpful e Microsoft Windows documentation set Microsoft Corporation Redmond WA 1992 1995 e Microsoft Windows Programmer s Reference Microsoft Corporation Redmond WA 1992 1995 e Win32 Programmer s Reference Microsoft Corporation Redmond WA 1992 1995 e Microsoft Visual C CD ROM Microsoft Corporation Redmond WA 1997 Using External Code in LabVIEW xiv ni com I
246. unction has not been properly exported you must recompile the DLL Before recompiling you must close all applications and VIs that might make use of the DLL Otherwise the recompile will fail because the DLL is still in memory Most compilers warn you when the DLL is in use by an application After you confirm the name of the function and after you confirm proper export of the function find out whether you have used the C or C compiler on the code If you have used the C compiler the names of the functions in the DLL are altered by a process called name mangling The easiest way to correct name mangling is to enclose the 2 32 ni com Chapter 2 Shared Libraries DLLs declarations of the functions you want to export in your header file with the extern C statement as shown in the following example code extern C your function prototypes here e Try to debug your DLL by using the source level debugger provided with your compiler Using the debugger of your compiler you can set breakpoints step through your code watch the values of the variables and so on Debugging using conventional tools can be extremely beneficial Refer to the appropriate manual for your compiler for more information about debugging e Calling the DLL from another C program is also another way to debug your DLL By calling the DLL from another C program you have a means of testing your DLL independent of LabVIEW thus helping you to identi
247. upports only a subset of development environments for creating CINs The Call Library Function Node is most appropriate when you have existing code you want to call or if you are familiar with the process of creating standard shared libraries Because a library uses a format standard among several development environments you can use almost any development environment to create a library that LabVIEW can call Refer to the documentation for your compiler to determine whether you can National Instruments Corporation 1 3 Using External Code in LabVIEW Chapter 1 Introduction Details of a CIN create standard shared libraries Refer to Chapter 2 Shared Libraries DLLs for more information about the Call Library Function Node The CIN is a general method for calling C code from LabVIEW You can pass arbitrarily complex data structures to and from a CIN In some cases you might have higher performance using CINs because data structures pass to the CIN in the same format that they are stored in LabVIEW CINs have the following advantages e The CIN code is integrated into the code of the VI so there is no extra file to maintain when the VI is distributed e CINSs provide certain special entry points such as CINLoad CINSave and so on In some cases you might want a CIN to perform additional tasks at certain execution times For example you might want to initialize data structures at load time or free private data structures w
248. ut only Input Output Terminals By default a terminal pair is input output The left terminal is the input terminal The right terminal is the output terminal For example the CIN in Figure 3 2 has a single terminal pair with a 32 bit signed integer control wired to the input terminal and a 32 bit signed integer indicator wired to the output terminal 1321 EN EH JEFA Figure 3 2 CIN with a Control and Indicator Wired to the Terminal Pair When the VI calls the CIN the only argument LabVIEW passes to the CIN object code is a pointer to the value of the 32 bit signed integer input When the CIN completes LabVIEW then passes the value referenced by the pointer to the 32 bit signed integer indicator When you wire controls and indicators to the input terminal and the output terminal of a terminal pair LabVIEW assumes the CIN can modify the data passed If another node on the block diagram needs the input value LabVIEW might have to copy the input data before passing it to the CIN The CIN in Figure 3 3 has a 32 bit signed integer control wired to the input terminal but no indicator wired to the output terminal 132 112 Figure 3 3 CIN with Only a Control Wired to the Terminal Pair O National Instruments Corporation 3 5 Using External Code in LabVIEW Chapter 3 CINs If you do not wire an indicator to the output terminal of a terminal pair LabVIEW assumes the CIN does not modify the value you pass to
249. variable you should release the Path using file manager routines In addition to providing routines for the creation and elimination of a Path the file manager provides routines for comparing duplicating determining Path characteristics and converting Path to and from other formats such as the platform specific format for the system on which LabVIEW is running National Instruments Corporation 4 31 Using External Code in LabVIEW Chapter 4 Programming Issues for CINs File Descriptors When you open a file LabVIEW returns a file descriptor associated with the file A file descriptor is a data type Lab VIEW uses to identify open files All operations performed on an open file use the file descriptor to identify the file A file descriptor is valid only while the file is open If you close the file the file descriptor is no longer associated with the file If you open the file again the new file descriptor is most likely different from the previous file descriptor File Refnums In the file manager LabVIEW accesses open files using file descriptors However on the front panel and block diagram LabVIEW accesses open files using file refnums A file refnum contains a file descriptor for use by the file manager and additional information used by LabVIEW LabVIEW specifies file refnums using the LVRefNum data type the exact structure of which is private to the file manager To pass references to open files into or out of a CIN con
250. vert file refnums to file descriptors and convert file descriptors to file refnums using the functions described in Chapter 6 Function Descriptions Support Manager The support manager contains a collection of constants macros basic data types and functions such for bit or byte manipulation of data string manipulation mathematical operations sorting searching and determining the current time and date The string functions contain much of the functionality of the string libraries supplied with standard C compilers such as string concatenation and formatting You can use variations of many of these functions with LabVIEW strings Pascal strings and C strings Table 4 5 describes the different string types Table 4 5 String Types and Their Descriptions String Type Description LabVIEW 4 byte length field followed by data generally stored in a handle Pascal 1 byte length field followed by data C data terminated by a null character With the utility functions you can sort and search on arbitrary data types using quicksort and binary search algorithms Using External Code in LabVIEW 4 32 ni com Chapter 4 Programming Issues for CINs The support manager also contains transcendental functions for many complex and extended floating point operations Certain routines specify time as a data structure The following example code illustrates specifying time as a data structure typedef struct
251. x on the Projects tab as shown in Figure 2 3 2 Click the OK button 3 Note You do not use Microsoft Foundation Classes MFC in this example However if you want to use these object classes in a project you can select MFC AppWizard dll at this point instead of selecting Win32 Dynamic Link Library Then copy the code from the myshared c source file and place it into the skeleton source code file that the MFC AppWizard generates je ATL COM Appwizard ug Cluster Resource Type Wizard La Custom AppWizard Database Project Hed DevStudio Add in Wizard SA ISAPI Extension Wizard l i LabVIEW Code Interface Node Appw izard Makefile fs MFC ActiveX ControlWizard MFC Appwizard dll BA MFC Appwizard exe Ti Utility Project aw in32 Application _ Win32 Console Application 32 Dynamic Link Library 55 Win32 Static Library Figure 2 3 Creating a Project in Visual C 3 Select An empty DLL project when prompted to choose the type of DLL that you want to create 4 Click the Finish button to finish creating your project and return to the Visual C workspace Using External Code in LabVIEW 2 14 ni com Chapter 2 Shared Libraries DLLs 5 Select Add to Project Files from the Project menu and add the myshared c source file ay Note When you want to use the LabVIEW manager functions in a Windows DLL you also must add labview lib to your project The cintools directory of your LabVIEW installation contains this 1ib f
252. xample 1 Call a Shared Library that You Built This section describes the tasks necessary to complete the Array Average VI you started building in the Building a Shared Library DLL section so the VI can call the avg_num function in myshared d11 UNIX The shared library file has a so or s1 extension The following tasks must be completed before the Array Average VI can call the avg_num function in myshared d11 e Complete configuration of the Call Library Function Node e Build the front panel e Complete the block diagram Complete Configuration of the Call Library Function Node Complete the following steps to complete the configuration of the Call Library Function Node 1 Open the Array Average VI block diagram 2 Right click the Call Library Function Node and select Configure from the shortcut menu to open the Call Library Function dialog box 3 Click the Browse button to open the Select a library dialog box 4 Navigate to the location of your myshared d11 file 5 Select myshared d11 and click the Open button The file path to myshared d11 appears in the Library Name or Path field The Library Name or Path field is the shared library that the Call Library Function Node calls nye Note To make the reference to your shared library platform independent use for the file extension Using External Code in LabVIEW 2 20 ni com Chapter 2 Shared Libraries DLLs Build the Front Panel Complete the following
253. xternal Code in LabVIEW D rr Insufficient memory 6 50 ni com FCopy Chapter 6 Function Descriptions MgErr FCopy oldPath newPath Purpose Copies a file preserving the type creator and access rights The file to be copied must not be open If an error occurs the new file is not created Parameters Name Type Description oldPath Path Path of the file or directory you want to copy newPath Path Path including filename where you want to store the new file Return Value MgErr which can contain the following errors noErr mgArgErr fNotFound fNoPerm fDiskFull fDupPath fIsOpen fTMFOpen mFullErr fFIOErr National Instruments Corporation No error A bad argument was passed to the function Verify the path File not found Access was denied the file directory or disk is locked or protected Disk is full The new file already exists The original file is open for writing Too many files are open Insufficient memory Unspecified I O error 6 51 Using External Code in LabVIEW Chapter 6 Function Descriptions FCreate MgErr FCreate fdp path permissions openMode denyMode group Purpose Creates a file with the name and location specified by path and with the specified permissions and opens it for writing and reading as specified by openMode If the file already exists the function returns an error You can use deny
254. y string format to an alphanumeric string format doubles the size of the string However converting to an alphanumeric format preserves the information in the string when you use the string in an environment where you have to replace LabVIEW strings with C strings Using External Code in LabVIEW 1 6 ni com Shared Libraries DLLs This chapter describes how to call shared libraries from LabVIEW Windows A shared library is called a DLL This manual uses DLL as a generic abbreviation for shared library Mac OS A shared library is called a Code Fragment UNIX A shared library is called a Shared Library function You can use any language to write DLLs as long as the DLLs can be called using one of the calling conventions LabVIEW supports either stdcall or C Examples and troubleshooting information appear later in the chapter to help you build and use DLLs and to successfully configure the Call Library Function Node in LabVIEW The general methods described here for DLLs also apply to other types of shared libraries Refer to the examples d11 directory for examples of using shared libraries Configuring the Call Library Function Node Use the Call Library Function Node to directly call a 32 bit Windows DLL a Mac OS Code Fragment or a UNIX Shared Library function Right click the Call Library Function Node and select Configure from the shortcut menu to open the Call Library Function dialog box shown in Figure 2 1 Use the
255. your CIN with debugging symbols If you built your CIN from the command line add the following lines to the 1vm file of your CIN to add debug information to the CIN DEBUG 1 cinLibraries Kernel32 lib 3 23 Using External Code in LabVIEW Chapter 3 CINs UNIX Using External Code in LabVIEW If you built your CIN using the IDE build a debug version of the DLL Select Projects Settings the Debug tab and the General category Enter your LabVIEW executable in Executable for debug session 3 Run LabVIEW If you built your CIN from the command line start LabVIEW normally When the debugger trap is run a the following message appears A Breakpoint has been reached Click OK to terminate application Click CANCEL to debug the application Click the Cancel button to launch the debugger which attaches to LabVIEW searches for the DLLs then asks for the source file of your CIN Point it to your source file and the debugger loads the CIN source code You then can debug your code If you built your CIN using the IDE open your CIN project and click the GO button Visual C launches LabVIEW On UNIX you can use standard C printf calls or the DbgPrintf function described in the previous section You also can use gdb the Gnu debugger to debug the CIN You must load the VI that contains the CIN before you add breakpoints The CIN is not loaded until the VI is loaded 3 24 ni com Programming Issues for CINs
256. ype at the beginning of the string that specifies the length of the string Specifying the length of the string enables a LabVIEW string to include NULL characters such as the ASCII character zero 0 If a LabVIEW string is passed to external code and used as a C string NULL characters embedded in the string might cause problems because C strings are interpreted as terminating at the first NULL character To pass the flattened form of LabVIEW data to C code convert the flattened LabVIEW data from a binary string format to an alphanumeric string format For example suppose your string consists of the following five characters character 35 character 65 A character 0 NULL character 50 2 Complete the following steps to convert the preceding five characters from a binary string format to an alphanumeric string format 1 Convert the decimal values of the five characters into hexadecimal values 35d 0x23 65d 0x41 Od 0x00 50d 0x32 107d 0x6B 2 Write down the actual alphanumeric characters for the hexadecimal values and include only a single NULL value at the end N DNNWOOEHF RAU haracter 50 haracter 51 haracter 52 haracter 49 haracter 48 haracter 51 haracter 50 haracter 54 haracter 66 B haracter 0 NULL E c c c character 48 c Cc c Cc c National Instruments Corporation 1 5 Using External Code in LabVIEW Chapter 1 Introduction Converting from a binar

Using External Code in LabVIEW

Contents

Download Pdf Manuals

Related Search

Related Contents