Home

LabVIEW Code Interface Reference Manual

1. 1 37 Debugging CINs Under Windows 95 NT 1 37 Debugging CINs Under Sun or Solaris 1 39 Debugging CINs Under HP UX 1 39 Chapter 2 CIN Parameter Passing Introduction 2 1 CIN c File 2 1 How LabVIEW Passes Fixed Sized Data to CINs 2 2 Scalar Numerics 2 2 Scalar Booleans 2 2 Refnums 2 3 Clusters of Scalars 2 3 Return Value for CIN Routines 2 3 Examples with Scalars
2. xii Related Documentation xiii Customer Communication xiv Chapter 1 CIN Overview Introduction 1 1 Classes of External Code 1 2 Supported Languages 1 3 Macintosh 1 3 Microsoft Windows 3 1 1 4 Microsoft Windows 95 and Windows NT 1 4 Solaris 1 4 HP UX and Concurrent 1 5 Steps for Creating a CIN 1 5 Place the CIN on a Block Diagram 1 6 Add Input and Output Terminals to the CIN
3. 5 2 Numerics 5 3 Complex Numbers 5 4 char Data Type 5 4 Dynamic Data Types 5 4 Arrays 5 4 Strings 5 5 C Style Strings CStr 5 5 Pascal Style Strings PStr 5 5 LabVIEW Strings LStr 5 5 Concatenated Pascal String CPStr 5 6 Paths Path 5 6 Memory Related Types 5 6 Constants 5 7 Contents National Instruments Corporation ix LabVIEW Code Interface Reference Manual Memory
4. 3 17 Compiling the CIN 3 20 Optimization 3 20 Chapter 4 External Subroutines Introduction 4 1 Creating Shared External Subroutines 4 2 External Subroutines 4 3 Macintosh 4 3 Microsoft Windows 3 1 Windows 95 and Windows NT 4 3 Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX 4 4 Contents LabVIEW Code Interface Reference Manual viii National Instruments Corporation Calling Code 4 4 Macintosh 4 5 Microsoft Windows 3 1 Windows 95 and Windows NT 4 6 Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX 4 6 External Subroutine Example
5. 1 6 Input Output Terminals 1 7 Output Only Terminals 1 8 Wire the Inputs and Outputs to the CIN 1 8 Create c File 1 9 Special Macintosh Considerations 1 11 Compile the CIN Source Code 1 12 Macintosh 1 13 THINK C for 68K Version 7 1 13 Symantec C 8 0 for Power Macintosh 1 16 Metrowerks CodeWarrior for 68K 1 18 Metrowerks CodeWarrior for Power Macintosh 1 20 Macintosh Programmer s Workshop for 68K and Power Macintosh 1 22 Microsoft Windows 3 x 1 26 Watcom C Compiler 1 26 Microsoft Windows 95 and Windows NT 1 28 Visual C Command Line
6. 2 4 Creating a CIN That Multiplies Two Numbers 2 4 Comparing Two Numbers Producing a Boolean Scalar 2 7 How LabVIEW Passes Variably Sized Data to CINs 2 8 Alignment Considerations 2 9 Arrays and Strings 2 10 Paths Path 2 10 Clusters Containing Variably Sized Data 2 10 Resizing Arrays and Strings 2 11 SetCINArraySize 2 12 NumericArrayResize 2 13 Examples with Variably Sized Data 2 15 Concatenating Two Strings 2 15 Computing the Cross Product of Two Two Dimensional Arrays 2 17 Work
7. 4 7 Compiling the External Subroutine 4 7 Macintosh 4 7 Microsoft Windows 3 1 4 8 Microsoft Windows 95 and Windows NT 4 9 Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX 4 9 Calling Code Example 4 10 Compiling the Calling Code 4 11 Macintosh 4 11 Microsoft Windows 3 1 4 12 Microsoft Windows 95 and Windows NT 4 13 Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX 4 13 Chapter 5 Manager Overview Introduction 5 1 Basic Data Types 5 2 Scalar Data Types 5 2 Booleans
8. 1 28 Visual C IDE 1 30 Symantec C 1 30 Contents LabVIEW Code Interface Reference Manual vi National Instruments Corporation Watcom C Compiler for Windows 3 1 under Windows 95 or Windows NT 1 31 Solaris 1 x 1 31 Solaris 2 x 1 31 HP UX and Concurrent PowerMAX 1 32 Unbundled Sun ANSI C Compiler HP UX C ANSI C Compiler and Concurrent C Compiler 1 32 Load the CIN Object Code 1 33 LabVIEW Manager Routines 1 34 Online Reference 1 34 Pointers as Parameters 1 34 Debugging External Code 1 36 DbgPrintf
9. In the correct example buf contains space for the maximum sized Pascal string whose address is passed to FNamePtr and fd is a local variable allocated space for a file descriptor 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 will write its results there with unpredictable consequences Similarly FMOpen will write its results to the space to which fd points which is not a valid place because fd is uninitialized Debugging External Code LabVIEW has a debugging window you can use with external code to display information at execution time You can open the window display arbitrary print statements and close the window from any CIN or external subroutine Use the DbgPrintf function to create this debugging window The format for DbgPrintf is similar to the format of the SPrintf function which is described in the CIN Function Overview section of the LabVIEW Online Reference DbgPrintf takes a variable number of arguments where the first argument is a C format string Chapter 1 CIN Overview National Instruments Corporation 1 37 LabVIEW Code Interface Reference Manual DbgPrintf syntax int32 DbgPrintf CStr cfmt The first time yo
10. R RAM Random Access Memory reentrant execution Mode in which calls to multiple instances of a subVI can execute in parallel with distinct and separate data storage reference See pointer relocatable Able to be moved by the memory manager to a new memory location representation Subtype of the numeric data type of which there are signed and unsigned byte word and long integers as well as single double and extended precision floating point numbers both real and complex S scalar Number capable of being represented by a point on a scale A single value as opposed to an array Scalar Booleans strings and clusters are explicitly singular instances of their respective data types shared external routine Subroutine that can be shared by several CIN code resources Glossary National Instruments Corporation G 7 LabVIEW Code Interface Reference Manual sink terminal Terminal that absorbs data Also called a destination terminal source code Original uncompiled text code source terminal Terminal that emits data subVI VI used in the block diagram of another VI comparable to a subroutine T terminal Object or region on a node through which data passes top level VI VI at the top of the VI hierarchy This term is used to distinguish the VI from its subVIs type descriptor See data type descriptor V vector One dimensional array virtual instrument VI LabVIEW program so called bec
11. Digital display value for a floating point representation of not a number typically the result of an undefined operation such as log 1 nodes Execution elements of a block diagram consisting of functions structures and subVIs O object Generic term for any item on the front panel or block diagram including controls nodes wires and imported pictures object code Compiled version of source code Object code is not stand alone because you must load it into LabVIEW to run it P Pascal string PStr A series of unsigned characters with the value of the first character indicating the length of the string Used in the Pascal programming language Glossary LabVIEW Code Interface Reference Manual G 6 National Instruments Corporation pointer Variable containing an address Commonly this address refers to a dynamically allocated block of memory polymorphism Ability of a node to automatically adjust to data of different representation type or structure pop up To call up a special menu by clicking on an object with the right mouse button Windows Sun and HP UX or holding down the lt command gt key while clicking Macintosh pop up menus Menus accessed by popping up on an object Menu options pertain to that object specifically portable Able to compile on any platform that supports LabVIEW private data structures Data structures whose exact format is not described and is usually subject to change
12. Existing Solaris 1 x and Solaris 2 x for LabVIEW 3 0 CINs will not operate correctly if they reference functions not in the System V Interface Definition SVID for libc libsys and libnsl Recompiling your existing CINs using the shared library format should ensure your CINs function as expected Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 32 National Instruments Corporation HP UX and Concurrent PowerMAX As previously stated the HP UX C ANSI C compiler and Concurrent C Compiler are the only compilers tested with LabVIEW Unbundled Sun ANSI C Compiler HP UX C ANSI C Compiler and Concurrent C Compiler With these compilers you create a makefile using the shell script lvmkmf LabVIEW Make Makefile which creates a makefile for a given CIN You then 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 lvmkmf command follows with optional parameters listed in brackets lvmkmf o Makefile t CIN ext Gluefile LVSBName LVSBName the name of the CIN or external subroutine you want to build is required If LVSBName is foo the compiler assumes the source is foo c and the compiler names the output file foo lsb o is optional and supplies the name of the makefile lvmkmf creates If you do not use this option the makefile name defaults to Makefile t is optional and indicates the type of e
13. LVBoolean 8 bit integer 1 if TRUE 0 if FALSE Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 4 National Instruments Corporation 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 The following segments of code give the type definitions for each of these complex data types typedef struct float32 re im cmplx64 typedef struct float64 re im cmplx128 typedef struct floatExt re im cmplxExt char Data Type The char data type is defined by C to be a signed byte value LabVIEW defines an unsigned char data type with the following type definition typedef uInt8 uChar Dynamic Data Types 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 the Scalar Data Types section of this chapter You can construct 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 Chapter 2 CIN Parameter Passing gives examples of how to manipula
14. Paths that provides a platform independent way of specifying a file or directory path You can translate a Path to and from a host platform s conventional format for describing a file pathname See the File Manager section of the LabVIEW Online Reference for more information The support manager contains a collection of generally useful functions such as functions for bit or byte manipulation of data string manipulation mathematical operations sorting searching and determining the current time and date See the Support Manager section of the LabVIEW Online Reference for more information Basic Data Types There are five basic data types scalar the char data type dynamic memory related and constants Scalar Data Types The two kinds of scalar data types are Booleans and numerics described below Booleans External code modules work with two kinds of Booleans those existing in LabVIEW block diagrams and those passing to and from manager routines The manager routines use a conventional form of Boolean where 0 is FALSE and 1 is TRUE This form of Boolean is called a Bool32 and it is stored as a 32 bit value LabVIEW block diagrams store Boolean scalars as 8 bit values The value is 1 if the Boolean is TRUE and 0 if the Boolean is FALSE This form of Boolean is called an LVBoolean Chapter 5 Manager Overview National Instruments Corporation 5 3 LabVIEW Code Interface Reference Manual The two forms of Boolea
15. SPrintf winTitleCStr CStr P winTitle Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 22 National Instruments Corporation cb WORD InvokeIndirectFunction hMessageBox messageCStr winTitleCStr 0x1 out if messageCStr DSDisposePtr messageCStr if winTitleCStr DSDisposePtr winTitleCStr return cinErr CIN MgErr CINUnload void if hDLL FreeLibrary hDLL return noErr National Instruments Corporation 4 1 LabVIEW Code Interface Reference Manual 4 External Subroutines This chapter describes how to create and call shared external subroutines from other external code modules Introduction An external subroutine or shared external subroutine is a function you can call from multiple external code modules By placing common code in an external subroutine you can avoid duplicating the code in each external code module You can also use external subroutines to store information that must be accessible to multiple external code modules External subroutines are different from CINs in that LabVIEW diagrams do not call them directly Instead an external subroutine is a function CINs and other external subroutines call You store external subroutines in separate files not in VIs When you load a VI containing a CIN LabVIEW determines whether the CIN references external subroutines If it does LabVIEW loads the external subroutines into memory and modif
16. This example shows only the front panel block diagram and source code Follow the instructions in the Steps for Creating a CIN section of Chapter 1 CIN Overview to create the CIN The front panel for this VI is shown in the following illustration Save the VI as tblsrch vi The block diagram for this VI is shown in the following illustration Chapter 2 CIN Parameter Passing National Instruments Corporation 2 21 LabVIEW Code Interface Reference Manual Save the c file for the CIN as tblsrch c Following is the source code for tblsrch c with the CINRun routine added CIN source file include extcode h define ParamNumber 0 The array parameter is parameter 0 typedefs typedef struct int16 number LStrHandle string TD2 typedef struct int32 dimSize TD2 arg1 1 TD1 typedef TD1 TD1Hdl CIN MgErr CINRun TD1Hdl clusterTableh TD2 elementp LVBoolean presentp int32 positionp CIN MgErr CINRun TD1Hdl clusterTableh TD2 elementp LVBoolean presentp int32 positionp int32 size i MgErr err noErr TD2 tmpp LStrHandle newStringh TD2 newElementp int32 newNumElements size clusterTableh gt dimSize tmpp clusterTableh gt arg1 positionp 1 presentp LVFALSE Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 22 National Instruments Corporation for i 0 i lt size i if
17. mult is the makefile name nmake f mult lvm If you want to use standard C or Windows 95 or Windows NT libraries define the symbol cinLibraries For example to use standard C functions in the preceding example you could use the following lvm file name mult type CIN cinLibraries libc lib include CINTOOLSDIR ntlvsb mak To include multiple libraries separate the list of library names using spaces Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 30 National Instruments Corporation Visual C IDE To build CINs using the Visual C Integrated Development Environment complete the following steps Create a new DLL project Select File New and select Win32 Dynamic Link Library as the project type You can name your project whatever you like Add CIN objects and libraries to the project Select Project Add To Project Files and select cin obj labview lib lvsb lib and lvsbmain def from the Cintools Win32 subdirectory These files are needed to build a CIN Add Cintools to the include path Select Project Settings and change Settings for to All Configurations Select the C C tab and set the category to Preprocessor Add the path to your cintools directory in the Additional include directories field Set alignment to 1 byte Select Project Settings and change Settings For to All Configurations Select the C C tab and set the category to Code Gen
18. LabVIEW knows if the CIN encountered any fatal problems and handles the error correctly If you return a value other than noErr LabVIEW stops the execution of the VI Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 6 National Instruments Corporation 5 After creating the source code you need to compile it and convert it into a form LabVIEW can use The following sections summarize the steps for each of the supported compilers Note Step 5 is different for each platform Look under the heading for your platform and compiler in the following sections to find the instructions for your system For details refer to the relevant subsection within the Compile the CIN Source Code section in Chapter 1 CIN Overview THINK C for 68K and Symantec C Create a new project and place mult c in it Build mult lsb according to the instructions in the THINK C for 68K Version 7 or the Symantec C 8 0 for Power Macintosh of the Compile the CIN Source Code section of Chapter 1 Macintosh Programmer s Workshop for 68K and Power Macintosh Create a file named mult lvm Make sure the name variable is set to mult Build mult lvm according to the instructions in the Macintosh Programmer s Workshop for 68K and Power Macintosh subsection of the Compile the CIN Source Code section of Chapter 1 Metrowerks CodeWarrior for Power Macintosh and 68K Create a new project and place mult c in it Build mult lsb according to
19. Makefile with the other If you want to place the code in the same directory you need either to combine the two makefiles manually or to create two separate makefiles using the o option to the lvmkmf script and use make f lt makefile gt to create the CIN or external subroutine Load the CIN Object Code Load the code resource by choosing Load Code Resource from the CIN pop up menu Select the lsb file you created in Compile the CIN Source Code This command loads your object code into memory and links the code to the current front panel block diagram After you save the VI the file containing the object code does not need to be resident on the computer running LabVIEW for the VI to execute If you make modifications to the source code you can load the new version of the object code using the Load Code Resource option The file containing the object code for the CIN must have an extension of lsb There is no limit to the number of CINs per block diagram Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 34 National Instruments Corporation LabVIEW Manager Routines LabVIEW has a suite of routines that can be called from CINs and external subroutines 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 three categories memory manager file manager and su
20. Manager 5 7 Memory Allocation 5 7 Static Memory Allocation 5 7 Dynamic Memory Allocation Pointers and Handles 5 8 Memory Zones 5 9 Using Pointers and Handles 5 9 Simple Example 5 10 Reference to the Memory Manager 5 12 Memory Manager Data Structures 5 12 File Manager 5 12 Identifying Files and Directories 5 13 Path Specifications 5 13 Conventional Path Specifications 5 13 Empty Path Specifications 5 15 LabVIEW Path S
21. Manual Examples of these globals include decimalPt CrgRtnChar LnFeedChar EOLChar TabChar EmptyStrChar SInfinity SNegInfinity DInfinity DNegInfinity EMaxW EMaxL EInfinity ENegInfinity DPi DHalfPi DThreeHalvesPi DTwoPi DRad2Deg DTwo DNan EPi EHalfPi ETwoPi EE Eln10 Eln2 Elog10e ELog2e EHalf EOne ETwo ETen EZero ERecipPi ERecipE EPlanck EElemChg ESpeedLt EGravity EAvgdro ERydbrg EMlrGas ELnOfPi ELogOfE ELnOfTwo and ENan Although mentioned in the documentation these globals are not exported for use in CINs To get these values into your CIN code pass them in as parameters to the CIN Can LabVIEW be used to call a DLL in Windows Yes The Call Library Function calls a DLL function directly The function is located in the Advanced palette of the Functions palette Refer to Chapter 13 of the LabVIEW Function and VI Reference Manual for more details on this feature I get an error linking to a function when I build my CIN using the Windows platform The Watcom linker usually does not allow you to link with the Watcom library function modules when making a stand alone module If it does allow you to link the code should work properly Unfortunately there is no clearly defined way to determine which functions will link and which will not it is trial and error If this error occurs the only way to work through the problem is to write a DLL that calls the library functions Why do I get garb
22. Windows 95 NT See the Microsoft Windows 3 x subsection of the Compile the CIN Source Code section of this chapter for more information on using the Watcom C compiler for Windows 3 1 Note Under Windows 95 and Windows NT do not call CINs created using the Watcom C compiler that call DLLs and system functions or that access hardware directly The technique Watcom uses to call such code under Windows 3 1 does not work under Windows 95 or Windows NT Solaris LabVIEW for Sun supports external code compiled in a out format under Solaris 1 x and a shared library format under Solaris 2 x These formats are prepared for LabVIEW using a LabVIEW utility The unbundled Sun ANSI C compiler is the only compiler tested thoroughly with LabVIEW The header files are compatible with the unbundled Sun ANSI C Compiler and may need modification for other compilers Chapter 1 CIN Overview National Instruments Corporation 1 5 LabVIEW Code Interface Reference Manual HP UX and Concurrent LabVIEW for HP UX and Concurrent support external code compiled as a shared library This library is prepared for LabVIEW using a LabVIEW utility The HP UX C ANSI C compiler and Concurrent C Compiler are the only compilers tested thoroughly with LabVIEW Steps for Creating a CIN You create a CIN by first describing in LabVIEW the data you want to pass to the CIN You then write the code for the CIN using one of the supported programming languages After you
23. and Strings section of this chapter Scalar Booleans LabVIEW stores Booleans in memory as 8 bit integers If any bit of the integer is 1 the Boolean is TRUE otherwise the Boolean is FALSE LabVIEW passes Booleans to CINs with the same conventions as for numerics Note In LabVIEW 4 x and earlier Booleans were stored as 16 bit integers If the high bit of the integer was 1 the Boolean was TRUE otherwise the Boolean was FALSE Chapter 2 CIN Parameter Passing National Instruments Corporation 2 3 LabVIEW Code Interface Reference Manual Refnums LabVIEW treats a refnum the same way as it treats 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 component is another cluster LabVIEW stores this cluster value as a component of the main cluster 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 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 rout
24. execute external routine See shared external routine F flattened data Data of any type that has been converted to a string usually for writing it to a file Formula Node Node that executes formulas you enter as text Especially useful for lengthy formulas too cumbersome to build in block diagram form function Built in execution element comparable to an operator function or statement in a conventional language G G LabVIEW graphical programming language H handle Pointer to a pointer to a block of memory handles reference arrays and strings An array of strings is a handle to a block of memory containing handles to strings I icon Graphical representation of a node on a block diagram icon pane Region in the upper right hand corner of the front panel and block diagram windows that displays the VI icon IEEE Institute of Electrical and Electronic Engineers indicator Front panel object that displays output Inf Digital display value for a floating point representation of infinity Glossary National Instruments Corporation G 5 LabVIEW Code Interface Reference Manual inplace Characteristic of an operation whose input and output data can use the same memory space L LabVIEW string LStr The string data type used by LabVIEW block diagrams M matrix Two dimensional array MB Megabytes of memory MPW Macintosh Programmer s Workshop MSB Most significant bit N NaN
25. file to your project s file list An easy way to set up your CIN project is to make use of the CIN project stationery in the cintools Metrowerks Files Project Stationery folder For CodeWarrior PowerPC projects the project stationery is a file called LabVIEW CIN MWPPC This file provides a template for CINs containing almost all of the settings you need See the Read Me file in the Project Stationery folder for details Chapter 1 CIN Overview National Instruments Corporation 1 21 LabVIEW Code Interface Reference Manual When building a CIN using CodeWarrior for PPC you can set many of the preferences to whatever you wish Others however must be set to specific values to correctly create a CIN If you do not use the CIN project stationery you need to make the following settings in the CodeWarrior Preferences dialog box Language Set the Source Model pop up menu to Apple C Empty out the Prefix File text field using MacHeaders will not work Processor Set the Struct Alignment pop up menu to 68K Linker Empty all of the Entry Point fields PEF Set the Export Symbols pop up menu to Use exp file and place a copy of the file projectName exp found in your cintools Metrowerks Files PPC Libraries folder in the same folder as your CodeWarrior project Rename this file to projectName exp where projectName is the name of the project file CodeWarrior will look in this file to determine what symbols y
26. for this argument For a two dimensional array of two rows by three columns you pass a value of 6 for this argument Error Description noErr No error mFullErr Not enough memory to perform operation mZoneErr Handle is not in specified zone Chapter 2 CIN Parameter Passing National Instruments Corporation 2 15 LabVIEW Code Interface Reference Manual Examples with Variably Sized Data The following examples show the steps for creating CINs and how to work with variably sized data types Concatenating Two Strings The following example shows how to create a CIN that concatenates two strings This example also shows how to use input output terminals by passing the first string as an input output parameter to the CIN The top right terminal of the CIN returns the result of the concatenation This example gives only the diagram and the code Follow the instructions in Chapter 1 CIN Overview to create this CIN The diagram for this CIN is shown in the following illustration Save the VI as lstrcat vi Create a c file for the CIN and name it lstrcat c The c file LabVIEW creates is as follows CIN source file include extcode h CIN MgErr CINRun LStrHandle var1 LStrHandle var2 CIN MgErr CINRun LStrHandle var1 LStrHandle var2 ENTER YOUR CODE HERE return noErr Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 16 National Instruments Co
27. global state information you first need to understand more of how LabVIEW manages data and CINs 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 node At that point LabVIEW loads a copy of the code called a code resource into memory and attaches it to the node When you save the VI this 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 a block of data storage memory for that VI This data space is used for instance to store the values in shift registers If the VI is reentrant then LabVIEW allocates a data space for each usage of the VI See Chapter 26 Understanding the Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 2 National Instruments Corporation Execution System in your G Programming Reference Manual for more information on reentrancy Within your CIN code resource you may have declared global data Global data includes variables declared outside of the scope of all routines and for the purposes of this discussion variables declared as static variables within routines LabVIEW allocates space for this global data As with the code itself there is always only one instance of these globals in memory Regardless of how many nodes reference the code resource and regardless of whether the surro
28. instead of a CIN For example if you want to create an external subroutine called find you could use the following command lvmkmf t LVSB find This command creates a makefile you could use to create the external subroutine Calling Code You call external subroutines the same way you call standard C subroutines LabVIEW modifies the code at load time to ensure the calling code passes control to the subroutine correctly When you call the external subroutine do not use the function name LVSBMain to call the function Instead use the name you gave the external subroutine If you created an external subroutine called fact lsb which in turn contained an LVSBMain subroutine for example you should call the function as though it were named fact The argument list and return type should be the same as the argument and return type for the LVSBMain subroutine You should also create a prototype for the function This prototype should have the keyword extern so the compiler will compile the CIN even though the subroutine is not present When you create the makefile for the CIN you identify the names of the external subroutines the CIN calls The LabVIEW makefile embeds information in your code LabVIEW uses to determine your code calls external subroutines When you load external code referencing external subroutines into a VI LabVIEW searches for the subroutine files If it finds the subroutines LabVIEW performs the appropriate
29. not modify the value you pass to it If another node on the block diagram uses the input data LabVIEW does Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 8 National Instruments Corporation 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 may 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 selecting Output Only from the terminal pair pop up menu If a terminal pair is output only the input terminal is gray as shown in the following illustration 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 You can remove this ambiguity by wiring a control to the left input terminal of the terminal pair as shown in the preceding figure In this case output terminal takes on the same data type as the input terminal LabVIEW uses the input type only to determi
30. resources are using in CINUnload After LabVIEW calls CINUnload the code resource itself is unloaded from memory Loading a New Resource into the CIN 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 First LabVIEW calls CINDispose for each CIN data space and each reference to the code resource followed by the CINUnload for the old resource The new code resource is then given a chance to perform any initialization it needs to perform LabVIEW calls the CINLoad for the new code resource followed by the CINInit routine called once for each data space and each reference to the code resource Compiling a VI When you compile a VI LabVIEW recreates the VI data space resetting all uninitialized shift registers for instance to their default values In the same way your CIN is given a chance to dispose or initialize any storage it manages Before disposing of the current data space LabVIEW calls the CINDispose routine for each reference to the code resource within the VI s being compiled to give the code resource a chance to dispose of any old results it is managing LabVIEW then compiles the VI and creates a new data space for the VI s being compiled multiple data spaces for any reentrant VI The CINInit routine is then called for each reference to the Chapter 3 CIN Advanced Topics National Instruments Corporation 3 5 LabVIEW Code Interface Refe
31. the following illustration Chapter 1 CIN Overview National Instruments Corporation 1 15 LabVIEW Code Interface Reference Manual After these parameters are set add the libraries CINLib TC7 and LabVIEWLib TC7 found in cintools Symantic THINK Files Think C 7 Libraries to the project You must also add the default version of each standard CIN procedure not defined by your code Each default procedure is in its own correspondingly named library located in cintools Symantic THINK Files THINK C 7 Libraries These libraries are CINLoad TC7 CINUnload TC7 CINInit TC7 CINDispose TC7 CINAbort TC7 CINSave TC7 and CINProperties TC7 Then add your c files You are now ready to build the code resource Go to the Project menu and select Build Code Resource A dialog box will appear allowing you to save the code resource The name of the code resource must be the same as the name of the CIN plus the extension tmp After you build a code resource and give it a tmp extension you must run the application lvsbutil app also included with LabVIEW to prepare external code for use as a CIN or external subroutine This utility prompts you to select your tmp file The utility also uses the THINK C link map file which carries a map extension and must be in the folder with your tmp file The application lvsbutil app uses the tmp and the map files to produce a lsb file that can be loaded into a VI If you are making a CIN select the C
32. the instructions in the Metrowerks CodeWarrior for 68K subsection of the Compile the CIN Source Code section of Chapter 1 Watcom C Compiler for Window 3 x Create a file named mult lvm Make sure the name variable is set to mult Build mult lvm according to the instructions in the Watcom C Compiler subsection of the Compile the CIN Source Code section of Chapter 1 Microsoft Visual C Compiler Command Line and Symantec C for Windows 95 and Windows NT Create a file named mult lvm Make sure the name variable is set to mult Build mult lvm according to the instructions in the Visual C IDE subsection of the Compile the CIN Source Code section of Chapter 1 Microsoft Visual C Compiler IDE for Windows 95 and Windows NT Create a project according to the instructions in the Visual C IDE subsection of the Compile the CIN Source Code section of Chapter 1 All Unix Compilers As described in the Steps for Creating a CIN section of Chapter 1 CIN Overview you can create a makefile using the shell script lvmkmf For this example you should first enter the following command lvmkmf mult Chapter 2 CIN Parameter Passing National Instruments Corporation 2 7 LabVIEW Code Interface Reference Manual This creates a file called Makefile After executing lvmkmf you should enter the standard make command which uses Makefile to create a file called mult lsb which you can load into the CIN in LabVIEW 6 Select Load Code Resource
33. the node to add parameters Chapter 1 CIN Overview National Instruments Corporation 1 7 LabVIEW Code Interface Reference Manual or use the pop up menu to add a parameter Each pair of terminals corresponds to a parameter LabVIEW passes to the CIN The two types of terminal pairs are input output and output only Input Output Terminals By default a terminal pair is input output the left terminal is the input terminal and the right terminal is the output terminal As an example consider a CIN that has a single terminal pair Assume a 32 bit integer control is wired to the input terminal and a 32 bit integer indicator is wired to the output terminal as shown in the following illustration 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 integer input When the CIN completes LabVIEW then passes the value referenced by the pointer to the 32 bit integer indicator When you wire controls and indicators to the input and the output terminals 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 may have to copy the input data before passing it to the CIN Now consider the same CIN but with no indicator wired to the output terminal as shown in the following illustration If you do not wire an indicator to the output terminal of a terminal pair LabVIEW assumes the CIN will
34. the size of the array using SetCINArraySize and fills the last position with a copy of the element 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 National Instruments Corporation 3 1 LabVIEW Code Interface Reference Manual 3 CIN Advanced Topics This chapter covers several topics needed only in advanced applications including how to use the CINInit CINDispose CINAbort CINLoad CINUnload CINSave and CINProperties routines The chapter also discusses how global data works within CIN source code and how users of Windows 3 1 Windows 95 and Windows NT can call a DLL from a CIN CIN Routines A CIN consists of several routines as described by the c file LabVIEW creates when you select Create c File from the CIN pop up menu The previous chapters have discussed only the CINRun routine The other routines are CINLoad CINInit CINAbort CINSave CINDispose CINUnload and CINProperties It is important to understand that for most CINs you need to write only the CINRun routine The other routines are supplied mainly for the cases in which you have special initialization needs such as when your CIN is going to maintain some information across calls and you want to preallocate or initialize global state information In the case where you want to preallocate initialize
35. 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 a global in a CIN code resource LabVIEW creates storage for only one instance of it regardless of whether the CIN s VI is reentrant or whether you have multiple references to the same code resource in memory Chapter 3 CIN Advanced Topics National Instruments Corporation 3 9 LabVIEW Code Interface Reference Manual In some cases you may 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 code interface node 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 can also call SetDSStorage to set the value of the CIN data space for thi
36. to 2 byte boundary radio button In the Prefix sub page remove the line that reads include lt PPCMacheaders gt Build the CIN by selecting Build Library from the Build menu Then convert the tmp file with lvsbutil app with For PowerPC checked Metrowerks CodeWarrior for 68K You need the following files in your project to be able to create a Metrowerks 68K CIN CustHdr 68k mwerks This file must be the first file in the project CINLib 68k mwerks LabVIEW 68k mwerks Your source files Note All of your files must be in a single segment LabVIEW does not support multi segment CINs An easy way to set up your CIN project is to use the CIN project stationery in the cintools Metrowerks Files Project Stationery folder For CodeWarrior 68K projects the project stationery is a file called LabVIEW CIN MW68K The file provides a template for CINs containing almost all of the settings you need See the Read Me file in the Project Stationery folder for details Chapter 1 CIN Overview National Instruments Corporation 1 19 LabVIEW Code Interface Reference Manual When building a CIN using CodeWarrior for 68K you can set many of the preferences to whatever you wish Others however must be set to specific values to correctly create a CIN If you do not use the CIN project stationery you need to make the following settings in the CodeWarrior Preferences dialog box Language Set the Source Model pop
37. to correctly create a CIN If for some reason you do not use the CIN project stationery you will need to ensure the following settings in the THINK C Preferences dialog box are made Pull down the THINK C Edit menu and pop up on the Options item select THINK Project Manager Under Preferences check the Generate link map box and then click on the OK button Now go back to the Options item under the Edit menu and select THINK C To complete the project set up process select the Require prototypes button under Language Settings and then check the Check Pointer Types box Under Prefix delete the line include lt MacHeaders gt if it is present Finally under Compiler Settings check the Generate 68881 instructions box the Native floating point format box and the Generate 68020 instructions box You can use the Copy button at the top of the dialog box to make these settings the default settings for new projects which will make the set up process for subsequent CINs simpler When you have finished selecting the options in the Edit menu turn to the THINK C Project menu select Set Project Type First set the type to Code Resource From the new options that appear set the File Type to tmp the Creator to LVsb the Name to the name of the CIN plus the extension tmp the Type to CUST the ID to 128 and check the Custom Header box If you are creating a CIN called test you must name the resource test tmp as shown in
38. 5 8248 512 794 5678 Technical Support Form Photocopy this form and update it each time you make changes to your software or hardware and use the completed copy of this form as a reference for your current configuration Completing this form accurately before contacting National Instruments for technical support helps our applications engineers answer your questions more efficiently If you are using any National Instruments hardware or software products related to this problem include the configuration forms from their user manuals Include additional pages if necessary Name __________________________________________________________________________ Company _______________________________________________________________________ Address ________________________________________________________________________ _______________________________________________________________________________ Fax ___ ________________Phone ___ __________________________________________ Computer brand____________ Model ___________________Processor _____________________ Operating system include version number ____________________________________________ Clock speed ______MHz RAM _____MB Display adapter __________________________ Mouse ___yes ___no Other adapters installed_______________________________________ Hard disk capacity _____MB Brand_________________________________________________ Instruments used ____________________________________
39. CIN Name the makefile by appending lvm to the CIN name This indicates this is a LabVIEW makefile The makefile should resemble the following pseudocode Be sure each Dir command ends with the colon character name name Name for the code 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 file name lsb lsb is a mnemonic for LabVIEW subroutine type type Type of external code you want to create For CINs you should use a type of CIN codeDir codeDir Complete pathname to the folder containing the c file used for the CIN Chapter 1 CIN Overview National Instruments Corporation 1 23 LabVIEW Code Interface Reference Manual cinToolsDir cinToolsDir Complete pathname to the LabVIEW cintools MPW folder which is located in the LabVIEW folder LVMVers 2 Version of CINMake script reading this lvm file inclDir i inclDir optional Complete or partial pathname to a folder containing any additional h files otherM68ObjFiles otherM68ObjFiles optional For 68K Macintosh only list of additional object files files with a o extension your code needs to compile Separate the names of files with spaces otherPPCObjFiles otherPPCObjFiles optional For Power Macintosh only list of additional object files files with a o extension your code needs to compile Separate the names of files with spaces s
40. CIN Overview National Instruments Corporation 1 13 LabVIEW Code Interface Reference Manual Macintosh LabVIEW for the Macintosh uses external code as a customized code resource on a 68K Macintosh or as a shared library on a Power Macintosh prepared for LabVIEW using the separate utilities lvsbutil app for THINK and Metrowerks or lvsbutil tool for MPW Both these utilities are included with LabVIEW You can create CINs on the Macintosh with compilers from any of the three major C compiler vendors Symantec s THINK environment Metrowerks CodeWarrior environment and Apple s Macintosh Programmer s Workshop MPW environment Always use the latest Universal headers containing definitions for both 68K and Power Macintosh compilers The LabVIEW utilities for building Power Macintosh CINs are the same ones used for the 68K Macintosh and can be used to build both versions of a CIN If you want to place both versions in the same folder however some development conflicts may arise Because the naming conventions for object files and lsb files are the same make sure one version does not replace the other These kinds of issues can be handled in different ways depending on your development environment Some CIN code that compiles and works on the 68K Macintosh and calls Macintosh OS or Toolbox functions requires changes to the source code before it will work on the Power Macintosh Any code that passes a function pointer to a Mac O
41. CINRun TD1Hdl ah TD1Hdl bh TD1Hdl resulth LVBoolean errorp CIN MgErr CINRun TD1Hdl ah TD1Hdl bh TD1Hdl resulth LVBoolean errorp int32 i j k l int32 rows cols float64 aElmtp bElmtp resultElmtp MgErr err noErr int32 newNumElmts if k ah gt dimSizes 1 bh gt dimSizes 0 errorp LVTRUE goto out errorp LVFALSE rows ah gt dimSizes 0 number of rows in a and result cols bh gt dimSizes 1 number of cols in b and result newNumElmts rows cols if err SetCINArraySize UHandle resulth ParamNumber newNumElmts goto out resulth gt dimSizes 0 rows resulth gt dimSizes 1 cols aElmtp ah gt arg1 bElmtp bh gt arg1 resultElmtp resulth gt arg1 for i 0 i lt rows i for j 0 j lt cols j resultElmtp 0 Chapter 2 CIN Parameter Passing National Instruments Corporation 2 19 LabVIEW Code Interface Reference Manual for l 0 l lt k l resultElmtp aElmtp i k l bElmtp l cos j resultElmtp out return err In this example CINRun is the only routine performing substantial operations CINRun cross multiplies the two dimensional arrays ah and bh LabVIEW stores the resulting array in resulth If the number of columns in ah is not equal to the number of rows in bh CINRun sets errorp to LVTRUE to inform the calling diagram of invalid data SetCINArraySize
42. Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 22 National Instruments Corporation Macintosh Programmer s Workshop for 68K and Power Macintosh You can use Macintosh Programmer s Workshop MPW to build CINs for either the Motorola 680x0 68K Macintosh or the Power Macintosh Several scripts are available for the MPW environment to help you build CINs To deal with the problem of building CINs for two different CPUs these new scripts are designed to use two subdirectories in your CIN folder PPCObj and M68Obj The platform specific object and CIN files are kept in these subdirectories The scripts make use of the MrC compiler on PowerPC and the SC compiler on 68K Macintosh Older compilers PPCC and C may also be used The scripts are CINMake A script capable of building both Power Macintosh and 68K Macintosh CINs It uses a simplified form of a makefile you provide It can be run every time you need to rebuild your CIN LVMakeMake A script similar to the lvmkmf LabVIEW Make Makefile script available for building CINs under the Solaris operating system It builds a skeletal but complete makefile you can then customize and use with the MPW make tool CINMake can be used for building both Power Macintosh and 68K Macintosh versions of your CINs By default the CINMake script builds 68K Macintosh CINs and puts the resulting cinName lsb into the M68Obj folder You must have one makefile for each
43. Code Interface Reference Manual LabVIEW Code Interface Reference Manual January 1998 Edition Part Number 320539D 01 Internet Support E mail support natinst com FTP Site ftp natinst com Web Address http www natinst com Bulletin Board Support BBS United States 512 794 5422 BBS United Kingdom 01635 551422 BBS France 01 48 65 15 59 Fax on Demand Support 512 418 1111 Telephone Support USA Tel 512 795 8248 Fax 512 794 5678 International Offices Australia 03 9879 5166 Austria 0662 45 79 90 0 Belgium 02 757 00 20 Brazil 011 288 3336 Canada Ontario 905 785 0085 Canada Qu bec 514 694 8521 Denmark 45 76 26 00 Finland 09 725 725 11 France 01 48 14 24 24 Germany 089 741 31 30 Hong Kong 2645 3186 Israel 03 6120092 Italy 02 413091 Japan 03 5472 2970 Korea 02 596 7456 Mexico 5 520 2635 Netherlands 0348 433466 Norway 32 84 84 00 Singapore 2265886 Spain 91 640 0085 Sweden 08 730 49 70 Switzerland 056 200 51 51 Taiwan 02 377 1200 United Kingdom 01635 523545 National Instruments Corporate Headquarters 6504 Bridge Point Parkway Austin Texas 78730 5039 USA Tel 512 794 0100 Copyright 1992 1998 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 evi
44. EW 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 Paths 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 variable you should release the Path using file manager routines In addition to providing routines for the creation and elimination of Paths the file manager provides routines for comparing Paths duplicating Paths determining characteristics of Paths and converting Paths to and from other formats such as the platform specific format for the system on which LabVIEW is running File Descriptors When you open a file LabVIEW returns a file descriptor associated with the file A file descriptor is a data type LabVIEW 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 subsequently open the file th
45. F 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 copyright 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 LabVIEW natinst com National Instruments are trademarks of Nationa
46. Finally this line sets myInt32H to refer to the master pointer The third line places the value 5 in the memory location to which myInt32H 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 the 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 Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 12 National Instruments Corporation operators you can use with pointers and a more detailed discussion of how to work with pointers Reference to the Memory Manager See the CIN Function Overview section of the LabVIEW Online Reference for descriptions of the routines used for managing memory in external code segments of LabVIEW For every function if XX is AZ the referenced handle pointer or block of memory is in the application zone If XX is DS the referenced handle pointer or block of memory is in the data space zone Memory Manager Data Structures The memory manager defines generic handle and pointer data types as follows typedef uChar Ptr typedef uChar UHandle File Manager The file manager supports routines for opening and creating files reading data from and writing data to files a
47. HINK C Compiler and CodeWarrior 68K Compiler To make a subroutine using the THINK or CodeWarrior 68K C Compiler build the code resource the tmp file as discussed in the Steps for Creating a CIN section of Chapter 1 CIN Overview but replace the CINLib library with the appropriate LVSBLib library and select the subroutine option when running lvsbutil app MPW Compiler The only difference between the makefiles of subroutines and of CINs is that for a subroutine you specify a type of LVSB in your lvm file instead of CIN See the Steps for Creating a CIN section of Chapter 1 CIN Overview for a discussion of the makefile contents Microsoft Windows 3 1 Windows 95 and Windows NT The only difference between the makefiles of subroutines and of CINs is that for a subroutine you specify a type of LVSB in your lvm file instead of CIN See the Steps for Creating a CIN section of Chapter 1 CIN Overview for a discussion of the makefile contents Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 4 National Instruments Corporation Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX Unbundled Sun C Compiler HP UX C ANSI C Compiler and Concurrent C Compiler The lvmkmf command for a CIN calling an external subroutine is the same as described in the Steps for Creating a CIN section of Chapter 1 CIN Overview except you use the t option with the type LVSB to indicate you are creating a LabVIEW subroutine
48. IN option in the dialog box as shown in the above illustration If you are making a CIN for the Power Macintosh also check the For Power PC box If you are making an external subroutine select the Subroutine option Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 16 National Instruments Corporation Advanced programmers can check the Add separate resource file box to add additional resources to their CINs or the Put directly into VI box to put the lsb code into a VI without opening it or launching LabVIEW Remember the VI designated to receive the lsb code must already contain lsb code with the same name Notice you cannot put the code directly into a library If your tmp code resource file does not show up in the dialog box check its file type When building the tmp file specify the file type as tmp which is under the Set Project Type menu item of the Project menu in THINK C The lsb file this application produces is what the LabVIEW CIN node should load Note The THINK C compiler will only find extcode h if the file extcode h is located on the THINK C search path You can place the cintools folder in the same folder as your THINK C application or you can make sure the line include extcode h is a full pathname to extcode h under THINK C For example include harddrive cintools extcode h If you are using System 7 0 or later you can extend the THINK C search path To do so first create a new fol
49. LL behaves as expected You can test the C program using the debugging tools supplied by your compiler Chapter 3 CIN Advanced Topics National Instruments Corporation 3 13 LabVIEW Code Interface Reference Manual After you are sure the DLL works and you are calling it correctly write the 32 bit CIN that LabVIEW can call The main purpose of this CIN is to act as a go between translating LabVIEW 32 bit data to 16 bit data This CIN will take 32 bit pointers from LabVIEW and then call the DLL with the appropriate arguments See the Calling 16 bit DLLs section of Chapter 37 Programming Overview in the Windows 32 bit Programming Guide section of the Watcom C 386 User s Guide for a detailed discussion of how to call a 16 bit DLL No special techniques are necessary to call a Windows 95 or Windows NT DLL Calling a 16 Bit DLL The following steps are a brief summary of how to call a 16 bit DLL from a CIN If you are not familiar with the functions used in this example you should refer to Microsoft Windows Programmer s Reference or the Watcom C 386 User s Guide 1 Load the DLL Load the DLL by calling the function LoadLibrary with the name of the DLL For example the following code returns a handle to a specified library HANDLE hDLL hDLL LoadLibrary library name This is a standard Windows function and is documented in the Microsoft Windows Programmer s Reference Note If you do not specify a full pat
50. S or Toolbox function must be modified to pass a Routine Descriptor see Apple s Inside Macintosh chapter on the Mixed Mode Manager available in the Macintosh on RISC SDK from APDA Also if you use any 68K assembly language in your CIN it must be ported to either C or Power Macintosh assembly language THINK C for 68K Version 7 To create a THINK C CIN project make a new folder for the project Launch THINK C and create a new project in the new folder The name of your THINK C project must match your CIN name exactly and must not use any of the conventional project suffixes such as or proj If you name your CIN test your THINK C project must also be named test so it produces a link map file named test map You should keep the new project and the CIN files associated with it within the same folder With THINK C 7 an easy way to set up your CIN project is to make use of the project stationery in the cintools Symantec THINK Files Project Stationery folder For THINK C 7 projects the project stationery is a folder called LabVIEW CIN TC7 It provides a template Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 14 National Instruments Corporation for new CINs with most of the settings you need See the Read Me file in the Project Stationery folder for details When building a CIN using THINK C for 68K many of the preferences can be set to whatever you wish Others however must be set to specific values
51. VIEW Code Interface Reference Manual SPrintf messageCStr CStr P message SPrintf winTitleCStr CStr P winTitle cb WORD InvokeIndirectFunction hMessageBox messageCStr winTitleCStr 0x1 out if messageCStr DSDisposePtr messageCStr if winTitleCStr DSDisposePtr winTitleCStr if hDLL FreeLibrary hDLL return cinErr The CIN first loads the library and then gets the address of the DLL entry point As described in the Watcom C 386 User s Guide a Watcom DLL has only one entry point Win386LibEntry Calling GetProcAddress for a Watcom DLL requests the address of this entry point For a DLL created using a compiler other than the Watcom C compiler request the address of the function you want to call To prepare for the DLL call after getting the address the example calls GetIndirectFunctionHandle Use this function to specify the data types for the parameters you want to pass The list is terminated with the INDIR_ENDLIST value Because there is only one entry point with a Watcom DLL pass an additional parameter the INDIR_WORD parameter that is the number of the routine you want to call in the DLL With a DLL created using another compiler you do not need to pass a function number because GetProcAddress returns the address of the desired function This example uses InvokeIndirectFunction to call the desired DLL function passing the number of the routine the example calls as the last par
52. _____________________________ _______________________________________________________________________________ National Instruments hardware product model _____________ Revision ____________________ Configuration ___________________________________________________________________ National Instruments software product ___________________ Version _____________________ Configuration ___________________________________________________________________ The problem is __________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ List any error messages ___________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ The following steps reproduce the problem ___________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _____________________
53. _________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ Thank you for your help Name _________________________________________________________________________ Title __________________________________________________________________________ Company _______________________________________________________________________ Address ________________________________________________________________________ _______________________________________________________________________________ E Mail Address __________________________________________________________________ Phone ___ __________________________ Fax ___ _______________________________ Mail to Technical Publications Fax to Technical Publications National Instruments Corporation National Instruments Corporation 6504 Bridge Point Parkway 512 794 5678 Austin Texas 78730 5039 National Instruments Corporation G 1 LabVIEW Code Interface Reference Manual Glossary Prefix Meanings Value m milli 10 3 micro 10 6 n nano 10 9 Numbers Symbols 1D One dimensional 2D Two dimensional A ANSI American National Standards Institute application zone See AZ array An ordered indexed set of data elements of the same type asynchronous execution Mode in which multiple processes sha
54. __________________________________________________________ Documentation Comment Form National Instruments encourages you to comment on the documentation supplied with our products This information helps us provide quality products to meet your needs Title LabVIEW Code Interface Reference Manual Edition Date January 1998 Part Number 320539D 01 Please comment on the completeness clarity and organization of the manual _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ If you find errors in the manual please record the page numbers and describe the errors _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ _______________________________________________________________________________ ______________________________________
55. age back from math functions such as atan2 pow ceil floor ldexp frexp modf and fmod when using MPW C Include Math h at the top of your c file Appendix A CIN Common Questions LabVIEW Code Interface Reference Manual A 4 National Instruments Corporation Why can t I link to the math functions sin cos and so on when using THINK C Find the math c and error c functions that came with THINK C and include them in the project Be sure to also include Math h in the c file Then enable the 68881 options under THINK C preferences National Instruments Corporation B 1 LabVIEW Code Interface Reference Manual B Customer Communication For your convenience this appendix contains forms to help you gather the information necessary to help us solve your technical problems and a form you can use to comment on the product documentation When you contact us we need the information on the Technical Support Form and the configuration form if your manual contains one about your system configuration to answer your questions as quickly as possible National Instruments has technical assistance through electronic fax and telephone systems to quickly provide the information you need Our electronic services include a bulletin board service an FTP site a fax on demand system and e mail support If you have a hardware or software problem first try the electronic support systems If the information available on these systems doe
56. amed msgbox h This example does not pass a full path to LoadLibrary You should move the DLL to the top level of your LabVIEW directory so it will be found See the note in the section 1 Load the DLL earlier in this chapter for more information CIN source file include extcode h include hosttype h include lt windows h gt CIN MgErr CINRun LStrHandle message LStrHandle winTitle Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 18 National Instruments Corporation int32 err HANDLE hDLL NULL FARPROC addr NULL HINDIR hMessageBox int cb char messageCStr NULL winTitleCStr NULL MgErr cinErr noErr err 0 hDLL LoadLibrary msgbxdll dll if hDLL lt HINSTANCE_ERROR err 1 LoadLibrary failed goto out addr GetProcAddress hDLL Win386LibEntry if addr err 2 GetProcAddress failed goto out hMessageBox GetIndirectFunctionHandle addr INDIR_PTR INDIR_PTR INDIR_WORD INDIR_ENDLIST if hMessageBox err 3 GetIndirectFunctionHandle failed goto out if messageCStr DSNewPtr LStrLen message 1 mem errs are serious stop execution cinErr mFullErr goto out if winTitleCStr DSNewPtr LStrLen winTitle 1 mem errs are serious stop execution cinErr mFullErr goto out Chapter 3 CIN Advanced Topics National Instruments Corporation 3 19 Lab
57. ameter With a DLL made by a compiler other than the Watcom C compiler you don t need to pass the function number because GetProcAddress returns the address of the desired function Notice at each stage of calling the DLL the code checks for errors and returns an error code if it fails Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 20 National Instruments Corporation Notice also LabVIEW strings are different from C strings C strings are terminated with a null character LabVIEW strings are not null terminated instead they begin with a four byte value indicating the length of the string Because the DLL expects C strings this example creates temporary buffers for the C strings using DSNewPtr and then uses SPrintf to copy the LabVIEW string into the temporary buffers You might consider modifying the DLL to accept LabVIEW strings instead because that would require no temporary copies of the strings Compiling the CIN Following is the LabVIEW makefile for this CIN It assumes the c file is named msgbox c the makefile is named msgbox lvm and the three pathnames for the directives codeDir cinToolsDir and wcDir are set correctly name msgbox type CIN codeDir c labview examples cins dll cinToolsDir c labview cintools wcDir c wc include cinToolsDir generic mak The following command line prompt compiles the CIN c gt wmake f msgbox lvm Optimization To optimize the performance o
58. an 8 bit integer INDIR_PTR The parameter is a pointer Watcom will automatically convert the 32 bit address to a 16 bit far pointer before calling the code Notice this 16 bit pointer is good only for the duration of the call after the function returns the 16 bit reference to the data is no longer valid Chapter 3 CIN Advanced Topics National Instruments Corporation 3 15 LabVIEW Code Interface Reference Manual INDIR_CDECL Make the call using Microsoft C calling conventions This keyword can be present anywhere in the parameter list For terminator pass a value of INDIR_ENDLIST which marks the end of the parameter list GetIndirectFunctionHandle returns a handle used when you want to call the function 4 Call the function Use InvokeIndirectFunction to call the function Pass it the handle returned in step 3 along with the arguments you want to pass to the CIN This function uses the following format long InvokeIndirectFunction HINDIR proc param1 param2 proc is the address of the function returned in step 3 Following that are the parameters you want to pass to the DLL Example A CIN that Displays a Dialog Box You cannot call most Windows functions directly from a CIN You can however call a DLL which in turn can call Windows functions The following example shows how to call a DLL from a CIN The DLL calls the Windows MessageBox function which displays a window containing a specified
59. and Windows NT is to insert a debugger break using an in line assembly command _asm int 3 Adding this to CINLoad gives you the following CIN MgErr CINLoad RsrcFile reserved Unused reserved _asm int 3 return noErr When the debugger trap is hit Visual C pops up a debug window highlighting that line Under Windows NT you may use the DebugBreak function This function exists under Windows 95 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 include lt windows h gt CIN MgErr CINLoad RsrcFile reserved Unused reserved DebugBreak return noErr When that line executes you will be in assembly Step out of that function to get to the point of the DebugBreak call 2 Rebuild your CIN with debugging symbols If you built your CIN from the command line add the following lines to the lvm file of your CIN to add debug information to the CIN DEGUG 1 cinLibraries Kernel32 lib If you built your CIN using the IDE build a debug version of the DLL In Projects Settings go to the Debug tab and select the General category Enter your LabVIEW executable in the Executable for debug session box Chapter 1 CIN Overview National Instruments Corporation 1 39 LabVIEW Code Interface Reference Manual 3 Run LabVIEW If you built your CIN from the command lin
60. ant VIs will affect the same set of globals In the code globals averaging example the result will indicate the average of all values passed to the CIN Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 10 National Instruments Corporation 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 averaging example the results would 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 containing that CIN is not reentrant it does not matter which method you choose Using Code Globals The following code implements averaging using code globals Notice the variables are initialized in CINLoad If the variables are dynamically created 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 do this because CINLoad and CINUnload are called only once regardless of the number of references to the code resources and the number of data spaces Notice the UseDefaultCINLoad macro is not used because this c file has a CINLoad function CIN source file include extcode h float64 gTotal int32 gNumElements CIN MgErr CINRun float64 new_num float64 avg CIN MgErr CINRun float64 new_num float64 avg gTota
61. atcom C compiler 1 Add a CINTOOLSDIR definition to your list of user environment variables Under Windows NT you can edit this list with the System control panel accessory For example if you installed LabVIEW for Windows 95 NT in c lv50nt the CIN tools directory should be Chapter 1 CIN Overview National Instruments Corporation 1 29 LabVIEW Code Interface Reference Manual c lv50nt cintools In this instance you would add the following line to the user environment variables using the System control panel CINTOOLSDIR c lv50nt cintools Under Windows 95 you must modify your AUTOEXEC BAT to set CINTOOLSDIR to the correct value 2 Build a lvm file LabVIEW Makefile for your CIN LabVIEW for Windows 95 NT requires you to define fewer variables than LabVIEW for Windows 3 1 You must specify the following items name name of CIN or external subroutine mult for example type CIN or LVSB depending on whether it is a CIN or an external subroutine include CINTOOLSDIR ntlvsb mak If your CIN uses extra object files or external subroutines you can specify the objFiles and subrNames options 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 command where
62. ate initialize and deallocate resources at the correct time Most CINs perform a specific action at run time only After you have written 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 no matter what the development system Classes of External Code LabVIEW supports code resources for CINs and external subroutines An external subroutine is a section of code you can call from other external code If you write multiple CINs that call the same subroutine you may want to make the shared subroutine an external subroutine The code for an external subroutine is a separate file when LabVIEW loads a section of external code that references an external subroutine it also loads the appropriate external subroutine into memory Using an external subroutine makes each section of calling code smaller because the external subroutine does not require embedded code Further you need to make changes only once if you want to modify the subroutine Note LabVIEW does not support code resources for external subroutines on the Power Macintosh If you are working with a Power Macintosh you should use shared libraries instead of external subroutines For information on building shared libraries consult your development environment documentation Chapter 1 CIN Overview National Instruments Corporat
63. ause it models the appearance of a physical instrument W wire Data path between nodes
64. best to always use the ENTERLVSB and LEAVELVSB macros whenever you create a new entry point to your CIN When you use these macros be sure your function does not return before calling the LEAVELVSB macro One technique is to use a goto endOfFunction statement where endOfFunction is a label just before the LEAVELVSB macro at the end of your function in place of any return statements you may place in your function Compile the CIN Source Code You must compile the source code for the CIN in a format LabVIEW can use There are two steps to this process First you compile the code using a compiler LabVIEW supports Then you use a LabVIEW utility to modify the object code putting it into a format LabVIEW can use 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 These tools vary depending on the platform and compiler you use The following sections summarize the steps for each platform Note Compiling the source code is different for each platform Look under the heading for your platform and compiler in the following sections to find the instructions for your system Every source code file for a CIN should list include extcode h before any other code If your code needs to make system calls you should also use include hosttype h immediately after include extcode h Chapter 1
65. brary will not be what it was when compiled Instead it will be a unique name generated by the C library function tmpnam The name will always begin with the string LV Use the debugger command mm to display the memory map of all currently loaded shared libraries CIN shared libraries are ordered by load time on the name space so CINs loaded later appear in the memory map before CINs loaded earlier As an example to break at CINRun for the library usr tmp LVAAAa17732 set the breakpoint as follows gt b CINRun LVAAAa17732 Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 40 National Instruments Corporation If you reload a CIN that is already loaded the debugger will not function properly If you change a CIN you must quit and restart the debugger to enable it to work as desired National Instruments Corporation 2 1 LabVIEW Code Interface Reference Manual 2 CIN Parameter Passing This chapter describes the data structures LabVIEW uses when passing data to a CIN Introduction LabVIEW passes parameters to the CINRun routine These 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 there is no limit to the number of parameters you can pass to and from the CIN CIN c File When you select the Create c File option LabVIEW creates a c file in which you can enter your CIN code The CINRun function and its prototype ar
66. ce within that VI Figure 3 3 Three VIs Referencing a Reentrant VI Containing One CIN global storage code globals code resource My VI data space 1 4 byte CIN data space data space globals My VI data space 3 4 byte CIN data space data space globals My VI data space 2 4 byte CIN data space data space globals caller 1 caller 2 My VI caller 3 Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 8 National Instruments Corporation Multithreaded Operating Systems By default CINs written before LabVIEW 5 0 run in a single thread the user interface thread When you change a CIN to be reentrant execute in multiple threads more than one execution thread can call the CIN at the same time If you want a CIN to run in the diagram s current execution thread add the following code to your c file CIN MgErr CINProperties int32 mode void data switch mode case kCINIsReentrant Bool32 data TRUE return noErr break return mgNotSupported 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 This means CINInit and CINDispose for example are never called from two different threads at the same time but CINRun might be running when
67. ces to two different code resources having the same name only one code resource is actually loaded into memory and both references point to the same code The difference is that LabVIEW can verify a subVI call matches the subVI connector pane terminal but LabVIEW cannot verify your source code matches the CIN call CIN Routines The Basic Case The following discussion describes what happens in the standard case in which you have a code resource referenced by only one CIN and the VI containing the CIN is non reentrant The other cases have slightly more complicated behavior 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 This gives you a chance to load any file based resources at load time because LabVIEW calls this routine only when the VI is first loaded see the Loading a New Resource into the CIN section that follows for an exception to this rule After LabVIEW calls the CINLoad routine it calls CINInit Together these two routines perform any initialization you need before the VI runs LabVIEW calls CINLoad once for a given code resource regardless of the number of data spaces and the number of references to that code resource This is why 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
68. ckets containing numbers separated by an ellipsis represent a range of values associated with a bit or signal name for example DBIO lt 3 0 gt A hyphen between two or more key names enclosed in angle brackets denotes that you should simultaneously press the named keys for example lt Control Alt Delete gt paths Paths in this manual are denoted using backslashes to separate drive names directories folders and files This icon to the left of bold italicized text denotes a note which alerts you to important information About This Manual National Instruments Corporation xiii LabVIEW Code Interface Reference Manual This icon to the left of bold italicized text denotes a caution which advises you of precautions to take to avoid injury data loss or a system crash Abbreviations acronyms metric prefixes mnemonics symbols and terms are listed in the Glossary Related Documentation The following documents contain information that you might find helpful as you read this manual G Programming Reference Manual LabVIEW User Manual LabVIEW Function and VI Reference Manual LabVIEW Online Reference available by selecting Help Online Reference Sun users might also find the following document useful Sun Workshop CD ROM Sun Microsystems Inc U S A 1997 Windows users might also find the following documents useful Microsoft Windows documentation set Microsoft Cor
69. code resource in the VI corresponding to that data space If you want to use CIN data space globals you should initialize them in CINInit See the Code Globals and CIN Data Space Globals the Loading a New Resource into the CIN and the Compiling a VI sections of this chapter for related information Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 4 National Instruments Corporation Unloading a VI When you close a VI front panel LabVIEW checks to see if there are any references to that VI in memory If so then 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 that 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 last reference to the code resource is removed from memory LabVIEW calls the CINUnload routine for that code resource once giving you the chance to dispose of anything allocated in CINLoad As with CINDispose CINInit a CINUnload is called for each CINLoad For example if you loaded some resources from a file in CINLoad you can free the memory those
70. compile the code you run a utility that puts the compiled code into a format LabVIEW can use You then instruct LabVIEW to load the CIN If you execute the VI at this point and the block diagram needs to execute the CIN LabVIEW calls the CIN object 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 directory contains a cins directory that includes all of the examples given in this manual The names of the directories in the cins directory correspond to the CIN name given in the examples The following steps explain how to create a CIN Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 6 National Instruments Corporation Place the CIN on a Block Diagram Select the Code Interface Node function from the Advanced palette of the Functions palette as shown in the following illustration Add Input and Output Terminals to the CIN 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 You add additional terminals by resizing the node or by selecting Add Parameter from the CIN terminal pop up menu Both methods are shown in the following illustration You can resize
71. d BASIC are control flow languages conversion Changing the type of a data element CPStr See concatenated Pascal string D data acquisition Process of acquiring data typically from A D or digital input plug in boards data dependency Condition in a dataflow programming language in which a node cannot execute until it receives data from another node See also artificial data dependency data flow Programming system consisting of executable nodes in which nodes execute only when they have received all required input data and produce output automatically when they have executed LabVIEW is a dataflow system data space zone See DS zone data type descriptor Code that identifies data types used in data storage and representation diagram window VI window containing the VI s block diagram code dimension Size and structure attribute of an array DS data space zone Memory allocation section that holds VI execution data E empty array Array that has zero elements but has a defined data type For example an array that has a numeric control in its data display window but has no defined values for any element is an empty numeric array Glossary LabVIEW Code Interface Reference Manual G 4 National Instruments Corporation EOF End of file Character offset of the end of file relative to the beginning of the file the EOF is the size of the file executable A stand alone piece of code that will run or
72. de compiled for 32 bit applications This is because CINs reside in the same memory space as VIs and work with LabVIEW data To create CINs a compiler must be able to create 32 bit relocatable object code The only compiler that currently supports the correct format of executables is Watcom C The following section lists the steps for compiling a CIN with the Watcom compiler Watcom C Compiler With the Watcom C compiler you create a specification that includes the name of the file you want to create relevant directories and any external subroutines or object files the CIN needs External subroutines are described in Chapter 4 External Subroutines You then use the wmake utility included with Watcom to compile the CIN In addition to compiling the CIN the makefile directs wmake to put the CIN in the appropriate form for LabVIEW Chapter 1 CIN Overview National Instruments Corporation 1 27 LabVIEW Code Interface Reference Manual The makefile should look like the following pseudocode Append lvm to the makefile name to indicate this is a LabVIEW makefile name name Name for the code 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 file name lsb lsb is a mnemonic for LabVIEW subroutine type type Type of external code you want to create For CINs you should use a type of CIN codeDir codeDir Complete or partial pat
73. denced 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 manual 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 National 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 O
74. der in the same folder as your THINK C project and name it Aliases Then make an alias for the cintools folder and drag this alias into your newly created Aliases folder This technique enables the include line to read include extcode h therefore it is not necessary to type the full pathname Symantec C 8 0 for Power Macintosh To create CINs using this environment you will need to install the ToolServer application from the Symantec C 8 0 distribution disks ToolServer is an Apple tool that performs the final linking steps in creating your CIN It can be found in the Apple Software Tools folder Copy the ToolServer 1 1 1 folder to your hard drive and place an alias to ToolServer in the Tools folder in your Symantec C for PowerMac folder Chapter 1 CIN Overview National Instruments Corporation 1 17 LabVIEW Code Interface Reference Manual You need the following files in your project to create a CIN for Power Macintosh CINLib ppc This file is shipped with LabVIEW and can be found in the cintools Symantic THINK Files Symantic C 8 folder Your source files You might also need the LabVIEW xcoff file This file is shipped with LabVIEW and can be found in the cintools PowerPC Libraries folder It is needed if you call any routines within LabVIEW such as DSSetHandleSize or SetCINArraySize An easy way to set up your CIN project is to make use of the CIN project stationery in the cintools Symantec THINK F
75. dows 95 or Windows NT In addition CINs cannot manipulate hardware directly To perform register or memory mapped I O you need to write a Windows 95 or Windows NT driver If you call Windows 3 1 functions you should check to make sure those functions are still valid under Windows 95 and Windows NT To create CINs using Watcom C for Windows 3 1 follow the Watcom C instructions given in the Watcom C Compiler subsection of the Compile the CIN Source Code section of this chapter You must compile the source code for the CINs under Windows 3 1 Use the LabVIEW for Windows 3 1 CIN libraries to compile the CINs Solaris 1 x LabVIEW for Sun can use external code compiled in a out format and prepared for LabVIEW using a LabVIEW utility The unbundled Sun C compiler is the only compiler tested thoroughly with LabVIEW Other compilers that can generate code in a out format might also work with LabVIEW but this has not been verified The C compiler that comes with the operating system does not use extended precision floating point numbers code using this numeric type will not compile However the unbundled C compiler does use them Solaris 2 x The preceding information for Solaris 1 x is true for Solaris 2 x with one exception LabVIEW 3 1 and higher for Solaris 2 x uses code compiled in a shared library format rather than the a out format previously specified Note LabVIEW 3 0 for Solaris 2 x supported external code compiled in ELF format
76. e start LabVIEW normally When the debugger trap is run a dialog box appears A Breakpoint has been reached Click OK to terminate application Click CANCEL to debug the application Click CANCEL This launches 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 can then debug your code If you built your CIN using the IDE open your CIN project and click the GO button LabVIEW will be launched by Visual C Debugging CINs Under Sun or Solaris It is not currently possible to use Sun s debugger dbx to debug CINs The best you can do is use standard C printf calls or the DbgPrintf function mentioned earlier Debugging CINs Under HP UX You can debug CINs built on the HP UX platform using xdb the HP source level debugger To do so compile the CIN with debugging turned on You must also enable shared library debugging with the s flag and direct xdb to the source files for your CIN For example if your CIN source code is in the tests first directory you could invoke xdb with the following command xdb s d tests first labview See the xdb manual for more information Once the CIN is loaded break into the debugger and set your breakpoints You may need to qualify function names with the name of the shared library Qualified names are in the form function_name library_name The name of the shared li
77. e 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 one of these handles to a CIN your CIN should use AZ routines to work with the handle Using Pointers and Handles Most memory manager functions have a DS routine and an AZ routine In the following discussion XXFunctionName refers to a function in a general context In these situations XX can be either DS or AZ When a difference exists between the two zones the specific function name is given You create a handle using XXNewHandle with which you specify the size of the memory block You create a pointer using XXNewPtr XXNewHandleClr and XXNewPClr are variations that create the memory block and set it to all zeros Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 10 National Instruments Corporation When you are finished with the handle or pointer release it using XXDisposeHandle or XXDisposePtr If you need to resize an existing handle you can use the XXSetHandleSize routine XXGetHandleSize 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 acc
78. e block of memory to store data and you reference that data 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 program 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 This avoids problems that occur when you need to change the amount of memory allocated to a pointer because other references would be out of date If you need more memory there might not be sufficient memory to expand the pointer s memory space without moving the memory block to a new location This causes problems if an application had multiple references to the pointer because each pointer refers to the old memory address of the data Using invalid pointers can cause severe problems A second form of memory allocation uses handles to address this problem As with pointers when you allocate memory using handles you request a block of memory of a given 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 As long as you look up the correct address using
79. e given and its parameters are typed to correspond to the data types being passed to the CIN in the block diagram If you want to refer to any of the other CIN routines CINInit CINLoad and so on see their descriptions in Chapter 1 CIN Overview 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 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 explicit about data type size such as int16 int32 float32 and so on LabVIEW comes with a header file extcode h that contains typedefs associating these LabVIEW data types with the corresponding data type for the supported compilers of each platform extcode h defines some constants and types whose definitions may conflict with the definitions of system header files The LabVIEW cintools directory also contains a file hosttype h that resolves these differences This header file also includes many of the common header files for a given platform Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 2 National Instruments Corporation Note You should always use include extcode h at the beginning of your source code If your code needs to include system header files you should include extcode h hosttype h and then any system header files in that order If you write a CIN
80. e is loaded LabVIEW must be able to modify the memory image of the calling code so it correctly references the memory location of the external code Finally LabVIEW may need to create and initialize memory space the external subroutine uses for global data The following sections describe how to make this work Chapter 4 External Subroutines National Instruments Corporation 4 3 LabVIEW Code Interface Reference Manual External Subroutines LabVIEW calls CINs but only your code calls external subroutines Instead of creating seven routines CINRun CINSave and so on you create only one entry point LVSBMain for an external subroutine When another external code module calls this external subroutine the LVSBMain subroutine executes LVSBMain is similar to CINRun You can have an arbitrary number of parameters and each parameter can be of arbitrary data type Also because only your code calls the subroutine you can declare any return data type and you do not need to place the word CIN in front of the function prototype You must ensure the parameters and return value are consistent between the calling and called code You compile an external subroutine almost the same way you compile a CIN Because multiple external code modules can call the same external subroutine LabVIEW does not load the code into a specific VI Instead LabVIEW loads the code from the file created by the makefile when the code is needed Macintosh T
81. e new file descriptor will most likely be different from the file descriptor LabVIEW used previously File Refnums In the file manager LabVIEW accesses open files using file descriptors On the front panel and block diagram however LabVIEW accesses open files through 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 If you want to pass references to open files into or out of a CIN use the functions in the File Refnums Manipulating topic of the Online Reference to convert file refnums to file descriptors and to convert file descriptors to file refnums Chapter 5 Manager Overview National Instruments Corporation 5 17 LabVIEW Code Interface Reference Manual Support Manager The support manager is a collection of constants macros basic data types and functions that perform operations on strings and numbers The support manager also has functions for determining the current time in a variety of formats Note This section gives only a brief overview of the support manager For descriptions of specific support manager functions see the Support Manager section of the LabVIEW Online Reference available by selecting Help Online Reference The support manager s string functions contain much of the functionality of the string libra
82. e their size For example if a routine requires a 4 byte integer as a parameter you define the parameter as an int32 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 a long int When writing external code modules use the manager data types instead of the host computer data types because your code will be more portable and have fewer errors Most applications need routines for allocating and deallocating memory on request You can use the memory manager to dynamically allocate manipulate and release memory The LabVIEW memory manager Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 2 National Instruments Corporation supports dynamic allocation of both non relocatable and relocatable blocks using pointers and handles For more information see the Memory Manager section of the LabVIEW Online Reference for more information Applications that manipulate files can use the functions in the file manager This set of routines supports basic file operations such as creating opening and closing files writing data to files and reading data from files In addition file manager routines allow you to create directories determine characteristics of files and directories and copy files File manager routines use a LabVIEW data type for file pathnames
83. ection of Chapter 1 CIN Overview except you use the optional ext option with the name of a file listing the names of the subroutines called by the CIN one name per line The makefile lvmkmf creates uses this file to append linkage information to the CIN object file For example if your code calls two external subroutines A and B you create a new text file with the name A on the first line and B on the second If the list of subroutines is in a file called subrs and you want to call the calling CIN lookup you can use the following command to create a makefile lvmkmf ext subrs lookup This command creates a makefile you can use to create the CIN Chapter 4 External Subroutines National Instruments Corporation 4 7 LabVIEW Code Interface Reference Manual External Subroutine Example The following example illustrates the process of building an external subroutine that sums the elements of an array This external subroutine can be used by a CIN that computes the mean and also by a CIN that computes the definite integral As described in the External Subroutines section of this chapter you must write a function called LVSBMain When you call the external subroutine from your CIN or another external subroutine LabVIEW passes control to the LVSBMain function When you call the external subroutine the arguments to it and to its return type should be the same as in the definition of LVSBMain The following is the C code
84. ee environments Header files may need modification for other environments CINs compiled for the 68K Macintosh will not be recognized by LabVIEW for the Power Macintosh and vice versa LabVIEW does not currently work with fat binaries a format including multiple executables in one file in this case both 68K and Power Macintosh executables Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 4 National Instruments Corporation Microsoft Windows 3 1 LabVIEW for Windows supports external code compiled as a REX file and prepared for LabVIEW using an application included with LabVIEW This application requires dos4gw exe which comes with Watcom C LabVIEW is a 32 bit flat memory model application so you must compile external code for a 32 bit memory model when you install the Watcom C compiler Watcom C is the only LabVIEW supported compiler that can create 32 bit code of the correct format Microsoft Windows 95 and Windows NT You can use CINs in LabVIEW for Windows 95 NT created with any of the following compilers The Microsoft Visual C compiler Symantec C Compiler See the Microsoft Windows 95 and Windows NT subsection of the Compile the CIN Source Code section of this chapter for information on how to create a CIN using these compilers The Watcom C 386 compiler for Windows 3 1 In most cases you can use CINs created using the Watcom C compiler for Windows 3 1 with LabVIEW for
85. eration Choose 1 Byte from the Struct member alignment tab Choose 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 Choose Multithreaded DLL from the Use run time library tab Make a custom build command to run lvsbutil Select Project Settings and change Settings for to All configurations Select the Custom Build tab and change the Build commands field to lt your path to cintools gt win32 lvsbutil TargetName d WkspDir OutDir and the Output file fields to OutDir TargetName lsb Symantec C The process for creating CINs using Symantec C is similar to the process for Visual C Command Line Use smake instead of nmake on your lvm file Note You cannot currently create external subroutines using Symantec C Chapter 1 CIN Overview National Instruments Corporation 1 31 LabVIEW Code Interface Reference Manual Watcom C Compiler for Windows 3 1 under Windows 95 or Windows NT CINs you have created using the Watcom C compiler for Windows 3 1 should work under Windows 95 or Windows NT However your CIN may not work without modification if it makes calls to communicate with hardware drivers performs register or memory mapped I O or calls Windows 3 1 functions Windows 3 1 drivers do not run under Windows 95 or Windows NT so you must port any drivers you may have written for Windows 3 1 to Win
86. es rows and columns in the array These dimension fields are followed by four bytes of filler which ensures the first double precision number is on an 8 byte boundary and then the data 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 ensures the next element is properly aligned Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 10 National Instruments Corporation Arrays and Strings LabVIEW passes arrays by handle as described in the Alignment Considerations section of this chapter 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 and 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 unsigned 8 bit integers Note LabVIEW 4 x stored Boolean arrays in memory as a series of bits packed to the nearest 16 bit word LabVIEW 4 x ignored unused bits in the last word LabVIEW 4 x ordered the bits from left to ri
87. ess of one of your functions to some other piece of code that may call your function later An example of this is the use of the QSort routine in the LabVIEW support manager described in the CIN Function Overview section of the LabVIEW Online Reference You must pass a comparison routine to QSort This routine gets called directly by QSort without going through the CIN library Therefore it is your responsibility to set up your global context with ENTERLVSB and LEAVELVSB To use these macros properly place the ENTERLVSB macro at the beginning of your function between your local variables and the first statement of the function Place the LEAVELVSB macro at the end of your function just before returning as in the following example CStr gNameTable kNNames int32 MyComparisonProc int32 pa int32 pb int32 comparisonResult ENTERLVSB comparisonResult StrCmp gNameTable pa gNameTable pb LEAVELVSB return comparisonResult Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 12 National Instruments Corporation The function MyComparisonProc is an example of a routine that might be passed to the QSort routine Because it explicitly references a global variable gNameTable it must use the ENTERLVSB and LEAVELVSB macros There are other things that can implicitly reference globals Depending on the compiler and settings of various options literal strings may also be referenced as globals It is
88. essing 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 A simple example of how to work with pointers and handles in C is shown in the following section While operating within a single call of a CIN node an AZ handle will not move unless you specifically resize it In this context there is no need to lock or unlock handles If your CIN maintains an AZ handle across different calls of the same CIN an asynchronous CIN the AZ handle may be relocated between calls In this case AZHLock and AZHUnlock may be useful if you do not want the handle to relocate A DS handle will never move unless 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 The following example code shows how you 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 signed 32 bit integer This does not actually allocate memory for the int32 it 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
89. f this CIN call LoadLibrary during the CINLoad routine and call FreeLibrary during the CINUnload routine This keeps the overhead of loading and unloading the DLL from affecting your run time performance The following code shows the modifications you need to make to CINRun CINLoad and CINUnload to implement this optimization HANDLE hDLL NULL CIN MgErr CINLoad RsrcFile rf hDLL LoadLibrary msgbxdll dll return noErr CIN MgErr CINRun LStrHandle message LStrHandle winTitle int32 err Chapter 3 CIN Advanced Topics National Instruments Corporation 3 21 LabVIEW Code Interface Reference Manual FARPROC addr NULL HINDIR hMessageBox int cb char messageCStr NULL winTitleCStr NULL MgErr cinErr noErr err 0 if hDLL lt HINSTANCE_ERROR err 1 LoadLibrary failed goto out addr GetProcAddress hDLL Win386LibEntry if addr err 2 GetProcAddress failed goto out hMessageBox GetIndirectFunctionHandle addr INDIR_PTR INDIR_PTR INDIR_WORD INDIR_ENDLIST if hMessageBox GetIndirectFunctionHandle failed err 3 goto out if messageCStr DSNewPtr LStrLen message 1 mem errs are serious stop execution cinErr mFullErr goto out if winTitleCStr DSNewPtr LStrLen winTitle 1 mem errs are serious stop execution cinErr mFullErr goto out SPrintf messageCStr CStr P message
90. fficult to calculate the size correctly in a platform independent manner however because some platforms have special requirements about how you align and pad memory Instead of using XXSetHandleSize use the LabVIEW routines that take this alignment into account when resizing handles You can use the SetCINArraySize routine to resize a string or an array of arbitrary data type This function is described in the Resizing Arrays and Strings section of this chapter If you are not familiar with alignment differences for various platforms the following examples highlight the problem Keep in mind SetCINArraySize and NumericArrayResize take care of these issues for you Consider the case of a 1D array of double precision numbers On the PC an array of double precision floating point numbers is stored in a handle and 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 On the Sun 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 ensures the array data falls on eight byte boundaries As a more complicated example consider a three dimensional array of clusters in which each cluster contains a double precision floating point number and a 4 byte integer As in the previous example the Sun stores this array in a handle The first 12 bytes contain the number of pag
91. for this external subroutine Name it sum c sum c include extcode h float64 LVSBMain float64 x int32 n float64 LVSBMain float64 x int32 n int32 i float64 sum sum 0 0 for i 0 i lt n i sum x return sum Compiling the External Subroutine The procedure you use in compiling the external subroutine depends upon the platform and programming environment you are using Macintosh THINK C Compiler and CodeWarrior 68K Compiler To make a subroutine using the THINK or CodeWarrior 68K C Compiler create a project named sum or sum respectively and add sum c and LVSBLib to the project Do not include the CINLib file in your project Set the options in the Options and Set Project Type dialog boxes as described in the Steps for Creating a CIN section of Chapter 1 CIN Overview After you create sum tmp run lvsbutil app and select the Subroutine option Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 8 National Instruments Corporation MPW Compiler As described in the External Subroutines section of this chapter you compile an external subroutine the same way you compile a CIN The first step is to create a makefile specification Following are the contents of the makefile specification for this example Notice all Dir commands must end with a colon Name the file sum lvm name name sum type type LVSB codeDir codeDir Complete pathname to
92. from the CIN pop up menu and select mult lsb the object code file you created If you followed the preceding steps correctly you should be able to run the VI at this point If you save the VI the CIN object code is saved along with the VI Comparing Two Numbers Producing a Boolean Scalar The following example shows how to create a CIN that compares two single precision numbers If the first number is greater than the second one the return value is TRUE otherwise the return value is FALSE This example gives only the block diagram and the code Follow the instructions in the Steps for Creating a CIN section of Chapter 1 to create the CIN The diagram for this CIN is shown in the following illustration Save the VI as aequalb vi Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 8 National Instruments Corporation Create a c file for the CIN and name it aequalb c The c file LabVIEW creates is as follows CIN source file include extcode h CIN MgErr CINRun float32 ap float32 bp LVBoolean aequalbp CIN MgErr CINRun float32 ap float32 bp LVBoolean aequalbp if ap bp aequalbp LVTRUE else aequalbp LVFALSE return noErr How LabVIEW Passes Variably Sized Data to CINs LabVIEW allocates memory for arrays and strings dynamically If a string or array needs more space to hold new data its current location may not offer enough contiguous space to hold t
93. g gLVSBsum LVSB void sum void void sum void asm move l gLVSBsum a0 jmp a0 CodeWarrior 68K Compiler The CodeWarrior project must have an extra file called glue c which specifies each external subroutine Each reference to the external subroutine sum should have an entry as follows in the glue c file long gLVSBsum LVSB void sum void asm void sum void move l gLVSBsum a0 jmp a0 MPW Compiler As described in the Calling Code Example section of this chapter when you compile a CIN referencing an external subroutine you use the same makefile as described in the Steps for Creating a CIN section of the Chapter 1 CIN Overview with the addition of a directive identifying the subroutines this CIN uses Following are the contents of the makefile specification for this example Notice the Dir command must end in a colon Name the makefile calcmean lvm Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 12 National Instruments Corporation name name calcmean type type CIN codeDir codeDir Complete pathname to the folder containing the c file cinToolsDir cinToolsDir Complete or partial pathname to the LabVIEW cintools folder inclDir inclDir optional Complete or partial pathname to a folder containing additional h files subrNames subrNames sum Create the CIN using the following command Directory lt full pathname to CIN directory g
94. generated c file to multiply a number by two This code is included for illustrative purposes Chapter 2 CIN Parameter Passing discusses how LabVIEW passes data to a CIN with several examples CIN MgErr CINRun int32 num_in int32 num_out num_out num_in 2 return noErr Chapter 1 CIN Overview National Instruments Corporation 1 11 LabVIEW Code Interface Reference Manual Special Macintosh Considerations If you compile your code for a 68K Macintosh there are certain circumstances under which you must use the ENTERLVSB and LEAVELVSB macros at the entry and exit of some functions These macros ensure the global context register A5 for MPW builds A4 for Symantec THINK and Metrowerks builds for your CIN is established during your function and the caller s is saved and restored This is necessary to enable you to reference global variables call external subroutines and call LabVIEW routines such as those described in subsequent chapters You need not use these macros in any of the eight predefined entry points CINRun CINLoad CINUnload CINSave CINInit CINDispose CINAbort and CINProperties because the CIN libraries already establish and restore the global context before and after calling these routines Using them here would be harmless but unnecessary However if you create any other entry points to your CIN you should use these macros You create another entry point to your CIN whenever you pass the addr
95. ght 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 Paths Path 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 For more information about the functions that manipulate Paths refer to the CIN Function Overview section of the LabVIEW Online Reference 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 this 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 Chapter 2 CIN Parameter Passing National Instruments Corporation 2 11 LabVIEW Code Interface Reference Manual Resizing Arrays and Strings You can use the LabVIEW SetCINArraySize routine to resize return arrays and strings you pass to a CIN You pass to the function the handle you want to resize information describing the data structure and the desired size of the array or handle The fu
96. h Windows searches the Windows directory the Windows system directory the LabVIEW directory and the directories listed in the Path variable Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 14 National Instruments Corporation 2 Get the address of the desired function Call GetProcAddress with the name of the function you want to call For example the following code returns the address of a specified function This address is a 16 bit pointer and cannot be called using standard DLL call methods Instead you have to use the Watcom C method shown as follows FARPROC lpfn lpfn GetProcAddress hDLL function name As with LoadLibrary this function is a standard Windows function and is documented in the Microsoft Windows Programmer s Reference 3 Describe the function Use GetIndirectFunctionHandle to describe the function and the types of each parameter it accepts This function uses the following format HINDIR GetIndirectFunctionHandle FARPROC proc long param1type long param2type long terminator proc is the address of the function returned in step 2 The paramXtype values should be one of the following five constants describing the parameters for the call to the function INDIR_DWORD The parameter will be a long word value a 32 bit integer INDIR_WORD The parameter will be a word value a 16 bit integer INDIR_CHAR The parameter will be a byte value
97. he Chapter 1 CIN Overview with the addition of a directive identifying the subroutines this CIN uses Following are the contents of the makefile specification for this example Name the makefile calcmean lvm name name calcmean type type CIN subrNames subrNames sum include CINTOOLSDIR ntlvsb mak Create the CIN using the following command nmake f calcmean lvm Microsoft Visual C IDE Building CINs that use external subroutines is not supported using Microsoft Visual C IDE A possible alternative would be to use a DLL instead of an external subroutine Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX Unbundled Sun C Compiler HP UX C ANSI C Compiler and Concurrent C Compiler As described in the Calling Code section of this chapter when you compile a CIN referencing an external subroutine you use the lvmkmf script with an addition directive identifying a file with the names of all subroutines the CIN calls For this example create a text file with the name meansubs It should contain a single line with the word sum Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 14 National Instruments Corporation You then create the makefile for this CIN using the following command lvmkmf ext meansubs calcmean This creates a file called Makefile After executing lvmkmf enter make which uses the makefile to create a file called calcmean lsb You can load the calcmean lsb fi
98. he resulting string or array In this case LabVIEW may have to move the data to a location that offers more space To accommodate this 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 Handles are described in detail in Chapter 5 Manager Overview Information about specific handle functions is available in the CIN Function Overview section of the LabVIEW Online Reference Chapter 2 CIN Parameter Passing National Instruments Corporation 2 9 LabVIEW Code Interface Reference Manual Alignment Considerations When a CIN returns variably sized data you need to adjust the size of the handle that references the array One method of adjusting the handle size is to use the memory manager routine DSSetHandleSize or if the data is stored in the application zone the AZSetHandleSize routine to adjust the size of the return data handle Both techniques work but they are trouble prone because you have to calculate the size of the new handle correctly It is di
99. his chapter you compile an external subroutine the same way you compile a CIN The first step is to create a makefile specification Following are the contents of the makefile specification for this example Name the file sum lvm name name sum type type LVSB include CINTOOLSDIR ntlvsb mak Create the subroutine using the following command nmake f sum lvm Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX Unbundled Sun C Compiler HP UX C ANSI C Compiler and Concurrent C Compiler As described in the External Subroutines section of this chapter you compile an external subroutine the same way you compile a CIN The first step is to create the makefile for the subroutine using the shell script lvmkmf You can then use the standard make command to make the subroutine code For this example enter the following command lvmkmf t LVSB sum This creates a file called Makefile After executing lvmkmf enter make which uses the makefile to create a file called sum lsb CINs and other external subroutines can call this sum lsb file Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 10 National Instruments Corporation Calling Code Example The following example shows how to call an external subroutine In this example a CIN uses the external subroutine to calculate the mean of an array The diagram for the VI is shown in the following illustration To avoid confusion create the ca
100. hname to the directory containing the c file used for the CIN wcDir wcDir Complete or partial pathname to the overall Watcom directory cinToolsDir cinToolsDir Complete or partial pathname to the LabVIEW cintools directory which is located in the LabVIEW directory This directory contains header files you can use for creating CINs and tools the wmake utility uses to create the CIN inclDir inclDir optional Complete or partial pathname to a directory containing any additional h files objFiles objFiles optional List of additional object files files with an obj extension your code needs to compile Separate the names of files with spaces subrNames subrNames optional List of external subroutines the CIN calls You need subrNames only if the CIN calls external subroutines Separate the names of subroutines with spaces include CinToolsDir generic mak Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 28 National Instruments Corporation Execute the wmake command by entering the following in DOS wmake f lt name of your CIN gt lvm Note The wmake utility sometimes erroneously stops a make with an incorrectly reported error when it is run in the DOS shell within Windows If this happens run it in normal DOS The wmake utility scans the specified LabVIEW makefile and remembers the defined values The last line of the makefile include CinToolsDir generic mak instruct
101. hreaded Operating Systems 3 7 Multithreaded Operating Systems 3 8 Code Globals and CIN Data Space Globals 3 8 Examples 3 9 Using Code Globals 3 10 Using CIN Data Space Globals 3 11 Calling a Windows 95 or Windows NT Dynamic Link Library 3 12 Calling a Windows 3 1 Dynamic Link Library 3 12 Calling a 16 Bit DLL 3 13 1 Load the DLL 3 13 2 Get the address of the desired function 3 14 3 Describe the function 3 14 4 Call the function 3 15 Example A CIN that Displays a Dialog Box 3 15 The DLL 3 15 The CIN Code
102. ies the calling code so it can call the subroutine LabVIEW modifies any additional subroutines referencing the same external subroutine to reference the code already in memory When you remove the last code referencing the external subroutine from memory when you close the VI containing the CIN LabVIEW also unloads the external subroutine Placing code in external subroutines is helpful for several reasons A single subroutine is easier to maintain because you need update only a single file to affect all calls on the subroutine A single subroutine can also reduce memory requirements because only a single instance of the code is in memory regardless of the number of calls to the subroutine An external subroutine can maintain information used by multiple external code modules The first time the external subroutine is called it can store data in a variable global to the external subroutine Other external code modules can call the same external subroutine to retrieve the common data Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 2 National Instruments Corporation You store external subroutines as files so you have to give each one a unique name When LabVIEW searches for a subroutine file it loads the first file it finds with the correct name Note External subroutines are not supported on the Power Macintosh The Macintosh OS on the Power Macintosh uses shared libraries which p
103. ilable for both Solaris 1 x and 2 x through anonymous ftp to prep ai mit edu Appendix A CIN Common Questions LabVIEW Code Interface Reference Manual A 2 National Instruments Corporation SPARCstations with Solaris 1 x come with the bundled C compiler cc that is not ANSI compliant Because the cc compiler requires substantial modification to the header files included with LabVIEW National Instruments does not recommend using this compiler for CIN development Please note LabVIEW for Solaris 1 x does not accept object files created with the g debugging flag turned on during compilation HP and Concurrent You can use the vendor supplied compilers on these platforms My VI which contains a CIN crashes LabVIEW or gives a memory c error In almost all cases this indicates an error in the C code of the CIN Make sure the CIN code properly allocates or deallocates memory as necessary See the section entitled How LabVIEW Passes Variably Sized Data to CINs in Chapter 2 CIN Parameter Passing of this manual for further details and examples How do I debug my CIN You have several debugging options depending upon the platform you use The following list gives descriptions of some of the available methods Use the DbgPrintf function which creates a debugging window Although the position and size of the window cannot be controlled information can be posted to the window as the CIN code executes Notice the window does no
104. iles Project Stationery folder For Symantec C version 8 projects the project stationery is a folder called LabVIEW CIN SC8PPC The folder provides a template for new CINs containing almost all of the files and preference settings you need See the Read Me file in the Project Stationery folder for details When building a CIN using Symantec C for PowerMac you can set many of the preferences to whatever you wish Others however must be set to specific values to correctly create a CIN If you do not use the CIN project stationery you need to make the following settings in the Symantec Project Manager Options dialog box accessed from the Project menu Project Type Set the Project Type pop up menu to Shared Library Set the File Type text field to tmp Set the Destination text field to cinName tmp where cinName is the name of your CIN Set the Creator to LVsb Linker Set the Linker pop up menu to PPCLink amp MakePEF Set the PPCLink settings text field to export Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 18 National Instruments Corporation gLVExtCodeDispatchTable LVSBhead Set the MakePEF settings text field to have librename LabVIEW xcoff o LabVIEW in addition to the factory setting Extensions Set the File Extension text field to ppc the Translator pop up menu to XCOFF convertor and press the Add button PowerPC C In the Compiler Settings sub page select the Align
105. ine LabVIEW uses Pascal calling conventions on the Macintosh when calling CIN routines so the header file declares the word CIN to be equivalent to Pascal on the Macintosh On the PC and Unix however 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 This behavior enables LabVIEW to handle conditions when a VI runs out of memory By aborting the running VI LabVIEW can possibly free enough memory to continue running correctly Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 4 National Instruments Corporation Examples with Scalars The following examples show the steps for creating CINs and how to work with scalar data types Chapter 5 Manager Overview contains more examples Creating a CIN That Multiplies Two Numbers Consider a CIN that takes two single precision floating point numbers and returns their prod
106. ines memory requirements when you create a program When you launch the program LabVIEW creates memory for the known global memory requirements of the application This memory remains allocated while the program runs This form of memory management is very simple to work with because the compiler handles all the details Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 8 National Instruments Corporation Static memory allocation cannot address the memory management requirements of most real world applications however because you cannot determine most memory requirements until run time Also statically declared memory may result in larger memory requirements because the memory is allocated for the life of the program Dynamic Memory Allocation Pointers and Handles 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 on your part than static memory allocation because you have to determine memory requirements and allocate and deallocate memory as necessary The LabVIEW memory manager supports two kinds of dynamic memory allocation The more conventional method uses pointers to allocate memory With pointers you request a block of memory of a given size and the routine returns the address of the block to your CIN When you no longer need the block of memory you call a routine to free the block You can use th
107. ing 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 is not included by hosttype h you can include it in the c file for your CIN just 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 called at specific times to give you the opportunity to take care of specialized tasks with your CIN For instance CINLoad is called when a VI is first loaded If you need to accomplish some special task when your VI is first loaded put the code for that task in the CINLoad routine To do this write your CINLoad routine as follows CIN MgErr CINLoad RsrcFile reserved Unused reserved ENTER YOUR CODE HERE return noErr In general you only need to write the CINRun routine The other routines are supplied for instances 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 code shows how to fill out the CINRun routine from the previously shown LabVIEW
108. ing with Clusters 2 20 Contents National Instruments Corporation vii LabVIEW Code Interface Reference Manual Chapter 3 CIN Advanced Topics CIN Routines 3 1 Data Spaces and Code Resources 3 1 CIN Routines The Basic Case 3 3 Loading a VI 3 3 Unloading a VI 3 4 Loading a New Resource into the CIN 3 4 Compiling a VI 3 4 Running a VI 3 5 Saving a VI 3 5 Aborting a VI 3 5 Multiple References to the Same CIN in a Single VI 3 5 Multiple Reference to the same CIN in different VIs 3 6 Single T
109. ion 1 3 LabVIEW Code Interface Reference Manual Although LabVIEW for Solaris 2 x HP UX and Concurrent PowerMAX support external routines it is recommended you use UNIX shared libraries instead because they are a more standard library format Supported Languages The interface for CINs and external subroutines 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 same memory space as the main application Macintosh LabVIEW for the Macintosh uses external code as a customized code resource for 68K or shared library for Power Macintosh that is prepared for LabVIEW using the separate utilities lvsbutil app for THINK C and Metrowerks CodeWarrior and lvsbutil tool for the Macintosh Programmer s Workshop These utilities are included with LabVIEW The LabVIEW utilities and object files are compatible with the three major C development environments for the Power Macintosh THINK C version 7 for Macintosh and Symantec C version 8 for Power Macintosh from Symantec Corporation of Cupertino CA Metrowerks CodeWarrior from Metrowerks Corporation of Austin Texas Macintosh Programmer s Workshop MPW from Apple Computer Inc of Cupertino CA LabVIEW header files are compatible with these thr
110. l new_num gNumElements avg gTotal gNumElements return noErr CIN MgErr CINLoad RsrcFile rf gTotal 0 gNumElements 0 return noErr Chapter 3 CIN Advanced Topics National Instruments Corporation 3 11 LabVIEW Code Interface Reference Manual Using CIN Data Space Globals The following is an alternative implementation of averaging using CIN data space globals 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 ensures GetDSStorage and SetDSStorage will return the 4 byte CIN data space value for that node or CIN data space When you want to access that data use GetDSStorage to retrieve the handle and then dereference the appropriate fields see the code for CINRun in the following example Finally in your CINDispose routine you need to dispose of the handle CIN source file include extcode h typedef struct float64 total int32 numElements dsGlobalStruct CIN MgErr CINInit 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 noErr CIN MgErr CINDispose dsGlobalStruct dsG
111. l Instruments Corporation Product and company names listed are trademarks or trade names of their respective companies WARNING REGARDING MEDICAL AND CLINICAL USE OF NATIONAL INSTRUMENTS PRODUCTS National Instruments products are not designed with components and testing intended to ensure a level of reliability suitable for use in treatment and diagnosis of humans Applications of National Instruments products involving medical or clinical treatment can create a potential for accidental injury caused by product failure or by errors on the part of the user or application designer Any use or application of National Instruments products for or involving medical or clinical treatment must be performed by properly trained and qualified medical personnel and all traditional medical safeguards equipment and procedures that are appropriate in the particular situation to prevent serious injury or death should always continue to be used when National Instruments products are being used National Instruments products are NOT intended to be a substitute for any form of established process procedure or equipment used to monitor or safeguard human health and safety in medical or clinical treatment National Instruments Corporation v LabVIEW Code Interface Reference Manual Contents About This Manual Organization of This Manual xi Conventions Used in This Manual
112. ld 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 Two relative paths to the same file are as follows gregg myapps README relative to usr home myapps README relative to a directory inside of the gregg directory On the PC 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 followed by the backslash You can 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 Two relative paths to the same file are as follows GREGG MYAPPS README relative to the HOME directory MYAPPS README relative to a directory inside of the GREGG directory Chapter 5 Manager Overview National Instruments Corporation 5 15 LabVIEW Code Interface Reference Manual On the Macintosh 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 it specifies a volume it must end with a colon If the path is a relative path it begins with a colon This colon is optional for a rela
113. le into the CIN National Instruments Corporation 5 1 LabVIEW Code Interface Reference Manual 5 Manager Overview This chapter gives an overview of the function libraries called managers which you can use in external code modules These include the memory manager the file manager and the support manager The chapter also introduces many of the basic constants data types and globals contained in the LabVIEW libraries Note For descriptions of specific manager functions see the CIN Function Overview section of the LabVIEW Online Reference available by selecting Help Online Reference Introduction External code modules have a large set of functions 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 these routines you can create external code modules that will work on all platforms LabVIEW supports A fundamental component of platform independence are data types that do not depend on the peculiarities of various compilers The C language for example does not define the size of an integer Without an explicit definition of the size of each data type it is almost impossible to create code that works identically across multiple compilers LabVIEW managers use data types that explicitly indicat
114. linking If a file is not found LabVIEW displays a dialog box prompting you to find it If you dismiss the dialog box without selecting the file the VI loads into memory with a broken run arrow indicating the VI is not executable Chapter 4 External Subroutines National Instruments Corporation 4 5 LabVIEW Code Interface Reference Manual One way to ensure LabVIEW can find external subroutines is to place them in the directories you defined in the search path section of the LabVIEW defaults file See the Configuring LabVIEW section of Chapter 8 Customizing Your LabVIEW Environment of your LabVIEW User Manual for more information on setting path preferences Macintosh THINK C Compiler The THINK C project must have an extra file named glue c specifying each external subroutine Each reference to the external subroutine should have an entry as follows in the glue c file long gLVSB lt external subroutine name gt LVSB void lt external subroutine name gt void void lt external subroutine name gt void asm move l gLVSB lt external subroutine name gt a0 jmp a0 CodeWarrior 68K Compiler The CodeWarrior project must have an extra file called glue c which specifies each external subroutine Each reference to the external subroutine should have an entry as follows in the glue c file long gLVSB lt external subroutine name gt LVSB void lt external subroutine name gt void asm void lt external subro
115. lling source code and makefiles in a directory separate from the external subroutine Save the VI as calcmean vi Save the c file for the CIN as calcmean c The following is a listing of calcmean c with its CINRun routine filled in and the prototype for the sum external routine added CIN source file include extcode h typedefs typedef struct int32 dimSize float64 arg1 1 TD1 typedef TD1 TD1Hdl extern float64 sum float64 x int32 n CIN MgErr CINRun TD1Hdl xArray float64 mean CIN MgErr CINRun TD1Hdl xArray float64 mean float64 x total int32 n x xArray gt arg1 n xArray gt dimSize total sum x n mean total float64 n return noErr Chapter 4 External Subroutines National Instruments Corporation 4 11 LabVIEW Code Interface Reference Manual CINRun calculates the mean using the external subroutine sum to calculate the sum of the array The external subroutine is declared with the keyword extern so the code compiles even though the subroutine is not present Compiling the Calling Code The procedure you use for compiling the calling code depends upon which platform and programming environment you are using Macintosh THINK C Compiler The THINK C project must have an extra file called glue c which specifies each external subroutine The reference to the external subroutine sum should have an entry as follows in the glue c file lon
116. llocate memory for a return value Chapter 1 CIN Overview National Instruments Corporation 1 35 LabVIEW Code Interface Reference Manual Table 1 1 lists the functions with parameters that return a value for which you must pre allocate memory It is important to allocate space for this return value The following examples illustrate correct and incorrect ways to call one of these functions from within a generic function foo 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 Table 1 1 Functions with Parameters Needing Pre allocated Memory AZHandToHand FGetInfo FPathToDString AZMemStats FGetPathType FPathToPath AZPtrToHand FGetVolInfo FRefNumToFD DateToSecs FMOpen FStringToPath DSHandToHand FMRead FTextToPath DSMemStats FMTell FUnflattenPath DSPtrToHand FMWrite GetAlong FCreate FNamePtr NumericArrayResize FCreateAlways FNewRefNum RandomGen FFlattenPath FPathToArr SecsToDate FGetAccessRights FPathToAZString SetALong FGetEOF Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 36 National Instruments Corporation Incorrect example foo Path path PStr p an uninitialized pointer File fd an uninitialized pointer MgErr err err FNamePtr path p err FMOpen fd path openReadOnly denyWriteOnly
117. llow uChar str 1 cnt bytes LStr LStrPtr LStrHandle Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 6 National Instruments Corporation Concatenated Pascal String CPStr Many algorithms require manipulation of lists of strings Arrays of strings are usually the most convenient representation for lists This representation can place a burden on the memory manager however because of the large number of dynamic objects that must be managed To make working with lists more efficient LabVIEW supports the concatenated Pascal string CPStr data type that is a list of Pascal style strings concatenated into a single block of memory You can use support manager routines to create and manipulate lists using this data structure This data type is defined as follows typedef struct int32 cnt number of pascal strings that follow uChar str 1 cnt concatenated pascal strings CPStr CPStrPtr CPStrHandle Paths Path A path short for pathname specifies the location of a file or directory in a computer s file system There is a separate LabVIEW data type for a path represented as Path which the file manager defines in a platform independent manner The actual data type for a path is private to the file manager and subject to change You create and manipulate Paths using file manager routines Memory Related Types LabVIEW uses pointers and handles to reference dynamica
118. lly allocated memory These data types are described in detail in the CIN Function Overview section of the LabVIEW Online Reference and have the following type definitions typedef uChar UPtr typedef uChar UHandle Chapter 5 Manager Overview National Instruments Corporation 5 7 LabVIEW Code Interface Reference Manual Constants The managers define the following constant for use with external code modules NULL 0 uInt32 The following constants define the possible values of the Bool32 data type FALSE 0 int32 TRUE 1 int32 The following constants define the possible values of the LVBoolean data type LVFALSE 0 uInt8 LVTRUE 1 uInt8 Memory Manager This section describes the memory manager a set of platform independent routines for allocating manipulating and deallocating memory from external code modules Read this section if you need to perform dynamic memory allocation or manipulation from external code modules If your external code operates on data types other than scalars you need to understand how LabVIEW manages memory and know the utilities that manipulate data Note For descriptions of specific memory manager functions see the Memory Manager section of the LabVIEW Online Reference available by selecting Help Online Reference Memory Allocation Applications use two types of memory allocation static and dynamic Static Memory Allocation With static allocation the compiler determ
119. lobals dsGlobals dsGlobalStruct GetDSStorage Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 12 National Instruments Corporation 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 if dsGlobals dsGlobals gt total new_num dsGlobals gt numElements avg dsGlobals gt total dsGlobals gt numElements return noErr Calling a Windows 95 or Windows NT Dynamic Link Library No special techniques are necessary to call a Windows 95 or Windows NT DLL Call DLLs the way you ordinarily would in a Windows 95 or Windows NT program Calling a Windows 3 1 Dynamic Link Library Although dynamic link libraries DLLs can be called from a CIN the method for doing so is somewhat cumbersome The Call Library Function is a more convenient way to call a DLL and the Watcom compiler is not required For more information on the Call Library Function see Chapter 13 Advanced Functions in the LabVIEW Function and VI Reference Manual and Chapter 25 Calling Code from Other Languages in your G Programming Reference Manual Before you attempt to link a dynamic link library with a CIN first write a C program calling it Do this to ensure you are calling the DLL properly and the D
120. ls About This Manual LabVIEW Code Interface Reference Manual xii National Instruments Corporation The Glossary contains an alphabetical list and description of terms used in this manual including acronyms abbreviations metric prefixes mnemonics and symbols Conventions Used in This Manual The following conventions are used in this manual bold Bold text denotes the names of menus menu items parameters dialog boxes dialog box buttons or options icons windows Windows 95 tabs or LEDs italic Italic text denotes variables emphasis a cross reference or an introduction to a key concept This font also denotes text from which you supply the appropriate word or value as in Windows 3 x bold italic Bold italic text denotes an activity objective note caution or warning monospace Text in this font denotes text or characters that you should literally 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 for statements and comments taken from programs monospace italic Italic text in this font denotes that you must enter the appropriate words or values in the place of these items lt gt Angle brackets enclose the name of a key on the keyboard for example lt shift gt Angle bra
121. message This function returns after the user presses a button in the window The DLL Most Windows compilers can create a DLL Regardless of the compiler you use to create a DLL the way you call it from a CIN will be roughly the same Because you must have Watcom C 386 to write a Windows CIN the following example is for a Watcom DLL The process for creating a DLL using the Watcom compiler is described in Chapter 38 Windows 32 Bit Dynamic Link Libraries of the Watcom C 386 User s Guide The following code is for a Watcom C 386 32 bit DLL that calls the MessageBox function The _16MessageBox function calls the Windows MessageBox function the only difference between these functions is the former takes far 16 bit pointers which are pointers passed to the DLL In this 32 bit environment MessageBox expects near 32 bit pointers Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 16 National Instruments Corporation Passing pointers to 32 bit DLLs is inherently tricky In this example a 32 bit near pointer is converted to a 16 bit far pointer and passed to MessageBox via _16MessageBox You cannot dereference a 16 bit pointer directly in this DL it must first be converted to a 32 bit pointer These pointer issues are not related to LabVIEW but are unique to the Windows 3 1 environment It may be helpful to build a rudimentary 32 bit Windows application in place of LabVIEW calling the DLL to test the use of poin
122. names for data types For most C compilers the float32 data type corresponds to the float data type However this may 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 extcode 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 These data types and routines are described in Chapter 5 Manager Overview of this manual and in the CIN Function Overview section of the LabVIEW Online Reference Note The line include extcode h must be a full pathname to extcode h under THINK C For example include harddrive cintools extcode h Optionally System 7 x users can use the Aliases folder technique described in the THINK C for 68K Version 7 subsection of Chapter 1 CIN Overview to enable the include line to read include extcode h For this multiplication example fill in the code for the CINRun routine You do not have to use the variable names LabVIEW gives you in CINRun you can change them to increase the readability of the code CIN MgErr CINRun float32 A float32 B float32 A_B A_B A B return noErr CINRun multiplies the values to which A and B refer and stores the results in the location to which A_B refers It is important CIN routines return an error code so
123. nction takes into account any padding and alignment needed for the data structure The function does not however 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 You pass to this function the array you want to resize a description of the data structure and information about the new size of the array When you resize arrays of variably sized data for example arrays of strings with the SetCINArraySize or NumericArrayResize routines you should be aware of the following facts If the new size of the array is smaller LabVIEW disposes of the handles used by the disposed element Neither function sets the dimension field of the array You must do this in your code after the function call If the new size is larger however LabVIEW does not automatically create the handles for the new elements You have to create these handles after the function returns The SetCINArraySize and NumericArrayResize functions are described in the following sections Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 12 National Instruments Corporation SetCINArraySize syntax MgErr SetCINArraySize UHandle dataH int32 paramNum int32 newNumElmts SetCINArraySize resizes a data handle based on the data structure of an argument you pa
124. nd closing files In addition with these routines 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 With other file routines you can move copy and rename files determine and set file characteristics and delete files Note For descriptions of specific file manager functions see the File Manager section of the LabVIEW Online Reference available by selecting Help Online Reference The file manager contains a number of routines for directories With these routines you can create and delete directories You can also 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 can also lock a range of the file if you need to ensure a range is nonvolatile at a given time Finally the file manager provides many routines for manipulating paths short for pathnames in a platform independent manner The file manager supports the creation of path descriptions which are either relative to a Chapter 5 Manager Overview National Instruments Corporation 5 13 LabVIEW Code Interface Reference Manual specific location or absolute the full path With file manager routines you can create and compare
125. ne the data type for the output terminal the CIN does not use or affect the data of the input wire To remove a pair of terminals from a CIN pop up on the terminal you want to remove and choose Remove Terminal from the 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 Wire the Inputs and Outputs to the CIN 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 Notice you can use any LabVIEW data types as CIN parameters Thus you can pass arbitrarily complex hierarchical data structures such as arrays containing clusters which may in turn contain other arrays or clusters to a CIN See Chapter 2 CIN Parameter Passing for a description of how LabVIEW passes parameters of specific data types to CINs Chapter 1 CIN Overview National Instruments Corporation 1 9 LabVIEW Code Interface Reference Manual Create c File If you select Create c File from the CIN pop up menu as shown in the following illustration LabVIEW creates 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 pa
126. nflict remove the unnecessary map file before using lvsbutil app When you have successfully built the cinName tmp file you must then use the lvsbutil app application to create the cinName lsb file The lvsbutil app application has a checkbox in the file selection dialog box labelled For Power PC This checkbox must not be checked for 68K CINs Select any other options you want for your CIN and then select your cinName tmp file cinName lsb will be created in the same folder as cinName tmp Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 20 National Instruments Corporation Caution This operation will destroy the contents of any previous file named cinName lsb in that folder This could easily be the case if this is the same folder in which you build a 68K Macintosh version of your CIN Metrowerks CodeWarrior for Power Macintosh You need the following files in your CodeWarrior project to create a CIN for Power Macintosh CINLib ppc mwerks is shipped with LabVIEW and is found in the cintools Metrowerks Files PPC Libraries folder Your source files You may also need the LabVIEW xcoff file This file is shipped with LabVIEW and is found in the cintools PowerPC Libraries folder It is needed if you call any routines within LabVIEW e g DSSetHandleSize or SetCINArraySize Finally if you call any routines from a system shared library you must add the appropriate shared library interface
127. ns are summarized in the following table Numerics The managers support 8 16 and 32 bit signed and unsigned integers For floating point numbers LabVIEW supports the single 32 bit double 64 bit and extended floating point at least 80 bit data types LabVIEW supports complex numbers containing two floating point numbers with different complex numeric types for each of the floating point data types The following lists show the basic LabVIEW data types for numbers Signed Integers int8 8 bit integer int16 16 bit integer int32 32 bit integer Unsigned Integers uInt8 8 bit unsigned integer uInt16 16 bit unsigned integer uInt32 32 bit unsigned integer Floating Point Numbers float32 32 bit floating point number float64 64 bit floating point number floatExt extended precision floating point number In Windows extended precision numbers are stored as an 80 bit structure with two int32 components mhi and mlo and an int16 component e On the Sun extended precision numbers are stored as 128 bit floating point numbers On the 68K Macintosh extended precision numbers are stored in the 96 bit MC68881 format On the Power Macintosh extended precision numbers are stored in the 128 bit double double format On HP and Concurrent extended precision numbers are the same as float64 Name Description Bool32 32 bit integer 1 if TRUE 0 if FALSE
128. o be linked into your CIN The format of a LVMakeMake command follows with optional parameters listed in brackets LVMakeMake o makeFile PPC lt name of your CIN gt make o makeFile specifies the name of the output makefile If this argument is not specified LVMakeMake writes to standard output PPC If this argument is specified a makefile suitable for building a Power Macintosh CIN is created By default a 68K Macintosh makefile is created For example to build a Power Macintosh makefile for a CIN named myCIN execute the following command LVMakeMake PPC myCIN gt myCIN ppc make creates the makefile Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 26 National Instruments Corporation You can then 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 You should load the lsb file this application produces into your LabVIEW CIN node Microsoft Windows 3 x Microsoft Windows 3 x is a 16 bit operating system A 16 bit application faces several obstacles when working with large amounts of information such as manipulating arrays requiring more than 64 kilobytes of memory LabVIEW is a 32 bit application without most of the inherent limitations found in 16 bit applications Because of the way CINs are linked to VIs however LabVIEW can use only co
129. ode when the node executes passing input data from the block diagram to the executable code and returning data from the executable code to the block diagram The LabVIEW compiler can usually generate code fast enough for most of your programming tasks However you can use CINs for tasks a conventional language can accomplish more easily such as tasks that are time critical or require a great deal of data manipulation CINs are also useful for tasks you cannot perform directly from the diagram such as calling system routines for which no corresponding LabVIEW functions exist CINs can also link existing code to LabVIEW although you may need to modify the code so it uses the correct LabVIEW data types CINs execute synchronously which means LabVIEW cannot use the execution thread used by the CIN for any other purpose When a VI executes LabVIEW monitors menus and the keyboard When running multi threaded there is a separate thread for these tasks When running single threaded the VI returns to LabVIEW to allow it time to scan menus and the keyboard and run other VIs When CIN object code executes it takes control of its execution thread If LabVIEW has only a single thread of control then all of LabVIEW is stopped until the CIN object code returns On single threaded operation systems such as Macintosh and Windows 3 1 CINs even prevent other applications from running In multi threaded operating systems such as Windows 95 NT only the e
130. our CIN exports LabVIEW needs these to link to your CIN Project Set the Project Type pop up menu to Shared Library Set the file name to be cinName tmp where cinName is the name of your CIN Set the Type field to tmp Set the Creator to LVsb Access Paths Add your cintools folder to the list of access paths Build the CIN by selecting Make from the CodeWarrior Project menu Caution This operation will destroy the contents of any other file named cinName tmp in that folder This could easily be the case if this is the same folder in which you build a 68K Macintosh version of your CIN If you are building for both platforms you should keep separate folders for each The convention used by the MPW CIN tools is to have two subdirectories named PPCObj and M68Obj where all platform specific files reside When you have successfully built the cinName tmp file you must then use the lvsbutil app application to create the cinName lsb file The lvsbutil app application has a checkbox in the file selection dialog box labelled For Power PC Check this box along with any other options necessary for your CIN and then select your cinName tmp file cinName lsb will be created in the same folder as cinName tmp Caution This operation will destroy the contents of any previous file named cinName lsb in that folder This could easily be the case if this is the same folder in which you build a 68K Macintosh version of your CIN
131. p menu Organization of This Manual This manual is organized as follows Chapter 1 CIN Overview introduces the LabVIEW Code Interface Node CIN a node that links external code written in a conventional programming language to LabVIEW Chapter 2 CIN Parameter Passing describes the data structures that LabVIEW uses when passing data to a CIN Chapter 3 CIN Advanced Topics covers several topics that are needed only in advanced applications including how to use the CINInit CINDispose CINAbort CINLoad CINUnload CINSave and CINProperties routines The chapter also discusses how global data works within CIN source code and how users of Windows 3 1 Windows 95 and Windows NT can call a DLL from a CIN Chapter 4 External Subroutines describes how to create and call shared external subroutines from other external code modules Chapter 5 Manager Overview gives an overview of the function libraries called managers which you can use in external code modules These include the memory manager the file manager and the support manager The chapter also introduces many of the basic constants data types and globals contained in the LabVIEW libraries Appendix A CIN Common Questions answers some of the questions commonly asked by LabVIEW CIN users Appendix B Customer Communication contains forms you can use to request help from National Instruments or to comment on our products and manua
132. paths determine characteristics of paths and convert a path between platform specific descriptions and the platform independent form 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 file systems support the connection of multiple discrete storage media called volumes For example DOS based systems support multiple drives connected to the system For most of these file systems you must include the volume name to completely specify the location of a file On other systems such as UNIX you do not 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 you specify the target using the target s path The path describes the volume containing the target the directories between the top level and the target and the target s name If the target is an open file you use a file descriptor to specify 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 Pa
133. pecification 5 16 File Descriptors 5 16 File Refnums 5 16 Support Manager 5 17 Appendix A CIN Common Questions Appendix B Customer Communication Glossary Figures Figure 3 1 Data Storage Spaces for One CIN Simple Case 3 2 Figure 3 2 Three CINs Referencing the Same Code Resource 3 6 Figure 3 3 Three VIs Referencing a Reentrant VI Containing One CIN 3 7 Tables Table 1 1 Functions with Parameters Needing Pre allocated Memory 1 35 National Instruments Corporation xi LabVIEW Code Interface Reference Manual About This Manual The LabVIEW Code Interface Reference Manual describes Code Interface Nodes and external subroutines for users who need to use code written in conventional programming languages The manual includes information about shared external subroutines libraries of functions memory and file manipulation routines and diagnostic routines Additional information not included in this manual is also available by selecting Online Reference from LabVIEW s Hel
134. poration Redmond WA 1992 1995 Microsoft Windows Programmer s Reference Microsoft Corporation Redmond WA 1992 1995 Win32 Programmer s Reference Microsoft Corporation Redmond WA 1992 1995 Watcom C C User s Guide CD ROM Watcom Publications Limited Waterloo Ontario Canada 1995 Help file The Watcom C C Compilers Microsoft Visual C CD ROM Microsoft Corporation Redmond WA 1997 About This Manual LabVIEW Code Interface Reference Manual xiv National Instruments Corporation Customer Communication National Instruments wants to receive your comments on our products and manuals We are interested in the applications you develop with our products and we want to help if you have problems with them To make it easy for you to contact us this manual contains comment and configuration forms for you to complete These forms are in Appendix B Customer Communication at the end of this manual National Instruments Corporation 1 1 LabVIEW Code Interface Reference Manual 1 CIN Overview This chapter introduces the LabVIEW Code Interface Node CIN a node that links external code written in a conventional programming language to LabVIEW Introduction A CIN is a block diagram node associated with a section of source code written in a conventional programming language You compile the source code first and link it to form executable code LabVIEW calls the executable c
135. pport manager External code written using the managers is portable you can compile it without modification on any platform that supports LabVIEW This portability has two advantages First the LabVIEW application is built on top of the managers except for the managers the LabVIEW source code is identical across platforms Second the analysis VIs are built mainly from CINs the source code for these CINs is the same for all platforms For general information about the memory manager the file manager and the support manager see Chapter 5 Manager Overview Online Reference For descriptions of functions or file manager data structures refer to the CIN Function Overview section of the LabVIEW Online Reference available by selecting Help Online Reference Pointers as Parameters Some manager functions have a parameter that is a pointer These parameter type descriptions are identified by a trailing asterisk such as the hp parameter of the AZHandToHand memory manager function documented in the CIN Function Overview section of the LabVIEW Online Reference or are type defined as such such as the name parameter of the FNamePtr function documented in the CIN Function Overview section of the LabVIEW Online Reference In most cases this means the manager function will write 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 don t have to pre a
136. re processor time one executing while the others for example wait for interrupts as while performing device I O or waiting for a clock tick AZ application zone Memory allocation section that holds all data in a VI except execution data B block diagram Pictorial description or representation of a program or algorithm In LabVIEW the block diagram which consists of executable icons called nodes and wires that carry data between the nodes is the source code for the virtual instrument The block diagram resides in the block diagram of the VI Glossary LabVIEW Code Interface Reference Manual G 2 National Instruments Corporation Boolean controls and indicators Front panel objects used to manipulate and display or input and output Boolean True or False data Several styles are available such as switches buttons and LEDs breakpoint Mode that halts execution when a subVI is called You set a breakpoint by clicking on the toolbar and then on a node broken VI VI that cannot be compiled or run signified by a run button with a broken arrow Bundle node Function that creates clusters from various types of elements C C string CStr A series of zero or more unsigned characters terminated by a zero used in the C programming language Case Structure Conditional branching control structure which executes one and only one of its subdiagrams based on its input It is the combination of the IF THEN ELSE and CASE
137. rence Manual code resource within the compiled VI s to give the code resource a chance to create or initialize any data it wants to manage Running a VI When you press the Run button of a VI the VI begins to execute When LabVIEW encounters a code interface node it calls the CINRun routine for that node Saving a VI When you save a VI LabVIEW calls the CINSave routine for that VI giving you the chance to save any resources for example something you loaded in CINLoad Notice 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 anything you expect to be able to load in CINLoad needs to be saved in CINSave Aborting a VI When you abort a VI LabVIEW calls the CINAbort routine for every reference to a code resource contained in the VI being aborted The CINAbort routine of all actively running subVIs is also called If a CIN is in a reentrant VI it is called for each CIN data space as well CINs in VIs not currently executing are not notified by LabVIEW of the abort event CINs are synchronous When a CIN begins execution it takes over control of its thread until the CIN completes If your version of LabVIEW is single threaded LabVIEW is not notified if the user clicks on the abort button and therefore cannot abort the CIN No other LabVIEW tasks can execu
138. ries supplied with standard C compilers such as string concatenation and formatting You can use variations of many of these functions with LabVIEW strings 4 byte length field followed by data generally stored in a handle Pascal strings 1 byte length field followed by data and C strings 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 The support manager contains transcendental functions for many complex and extended floating point operations Certain routines specify time as a data structure with the following form typedef struct 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 A 1 LabVIEW Code Interface Reference Manual A CIN Common Questions This appendix answers some of the questions commonly asked by LabVIEW CIN users What compilers can be used to write CINs for LabVIEW Microsoft Windows 3 1 Windows 95 and Windows NT You can use the Watcom C 386 compiler version 9 0 or later to write CINs for LabVIEW for Windows 3 1 Other compilers for Windows 3 1 including the Micro
139. rovide a much cleaner mechanism for sharing code If you need to share code among multiple CINs on the Power Macintosh consult your development environment documentation to learn how to build a shared library Although external subroutines are supported on Solaris 2 HP UX and Concurrent PowerMAX it is suggested you use shared libraries instead Shared library mechanisms compatible with LabVIEW are available on all platforms Under Microsoft Windows 3 1 Windows 95 and Windows NT they are referred to as DLLs dynamic link libraries Under UNIX they are referred to as shared libraries or dynamic libraries Creating Shared External Subroutines Normally when you use a compiler to create a program the compiler includes the code for all subroutines in a single file called the executable External subroutines differ from standard subroutines in that you do not compile the code for the external subroutine with the code for the calling subroutine Instead your makefile and consequently the code indicate the calling code references an external subroutine LabVIEW loads external subroutines based on this information and links the calling code in memory so the calling code points correctly to the external subroutine You need to compile the calling code even though its subroutines are not all present LabVIEW must be able to determine that your code calls an external subroutine find the subroutine and load it into memory When the subroutin
140. rporation Now fill in the CINRun function as follows CIN MgErr CINRun LStrHandle strh1 LStrHandle strh2 int32 size1 size2 newSize MgErr err size1 LStrLen strh1 size2 LStrLen strh2 newSize size1 size2 if err NumericArrayResize uB 1L UHandle amp strh1 newSize goto out append the data from the second string to first string MoveBlock LStrBuf strh2 LStrBuf strh1 size1 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 you need to resize strh1 with the LabVIEW routine NumericArrayResize to hold the additional data If NumericArrayResize fails it returns a non zero value of type MgErr In this case 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 may free up enough memory so LabVIEW can continue running After resizing the string handle this example copies the second string to the end of the first string using MoveBlock MoveBlock is a support manager routine that moves blocks of data Finally this example sets the si
141. s instance You can use this storage location 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 you can store a handle or pointer to a structure containing your globals The following two lines of code are examples of the exact syntax of these two 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 You should call this routine only from CINInit CINDispose 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 Examples The following two 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 When you design your code 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 nodes or different reentr
142. s not answer your questions we offer fax and telephone support through our technical support centers which are staffed by applications engineers Electronic Services Bulletin Board Support National Instruments has BBS and FTP sites dedicated for 24 hour support with a collection of files and documents to answer most common customer questions From these sites you can also download the latest instrument drivers updates and example programs For recorded instructions on how to use the bulletin board and FTP services and for BBS automated information call 512 795 6990 You can access these services at United States 512 794 5422 Up to 14 400 baud 8 data bits 1 stop bit no parity United Kingdom 01635 551422 Up to 9 600 baud 8 data bits 1 stop bit no parity France 01 48 65 15 59 Up to 9 600 baud 8 data bits 1 stop bit no parity FTP Support To access our FTP site log on to our Internet host ftp natinst com as anonymous and use your Internet address such as joesmith anywhere com as your password The support files and documents are located in the support directories LabVIEW Code Interface Reference Manual B 2 National Instruments Corporation Fax on Demand Support Fax on Demand is a 24 hour information retrieval system containing a library of documents on a wide range of technical information You can access Fax on Demand from a touch tone telephone at 512 418 1111 E Mail Support Currently USA Only You can s
143. s wmake to compile the code resource based on instructions in the generic mak file which is stored in the cintools directory The wmake utility compiles the code and then transforms it into a form LabVIEW can use The resulting code is stored in a name lsb file where name is the CIN name given in the name line of the makefile Note You cannot link most of the Watcom C libraries to your CIN because precompiled libraries contain code that cannot be properly resolved by LabVIEW when it links a VI to a CIN If you try to call those functions your CIN may crash LabVIEW provides functions that correspond to many of the functions in these libraries These functions are described in subsequent chapters of this manual If you need to call a function not supplied by LabVIEW you can access the function from a dynamic link library DLL A CIN can call a DLL using the techniques described in the Watcom C manuals A DLL can call any function from the C libraries See Chapter 3 CIN Advanced Topics for information on calling a DLL Microsoft Windows 95 and Windows NT You can use the Microsoft Visual C compiler and Symantec C compiler to build CINs for LabVIEW for Windows 95 NT With some restrictions you can also use some CINs created using Watcom C for Windows 3 1 Visual C Command Line The method for building CINs using command line tools under Windows 95 and Windows NT is similar to the method for building CINs under Windows 3 1 using the W
144. soft C compiler do not generate the proper code for LabVIEW to operate as a 32 bit application For a compiler to work with LabVIEW it must generate a file in the REX format a 32 bit Phar Lap relocatable executable LabVIEW for Windows 95 NT supports additional compilers including Microsoft Visual C and Symantec C Macintosh You can use the following compilers to compile your CIN source code THINK C version 7 for 68K from Symantec Corporation of Cupertino CA Symantec C version 8 for PowerPC from Symantec Corporation of Cupertino CA Metrowerks CodeWarrior for 68K from Metrowerks Corporation of Austin TX Metrowerks CodeWarrior for Power Macintosh from Metrowerks Corporation of Austin TX Macintosh Programmer s Workshop MPW for 68K and PowerPC from Apple Computer Inc of Cupertino CA Sun You can use the Sun ANSI compatible compiler and the gcc compiler The only officially supported compiler is the ANSI C compiler also known as the unbundled C compiler or SPARCompiler C which can be purchased from Sun On Solaris 1 x machines this compiler is commonly referred to as acc ANSI C compiler on Solaris 2 x machines the compiler is called cc The Gnu C compiler gcc is also ANSI compatible and can be used to create CINs for LabVIEW for Sun The only known limitation of the gcc compiler is it does not support extended precision floating point numbers under Solaris 1 x Source code for the gcc compiler is ava
145. ss to the CIN It does not set the array dimension field returns MgErr which can contain the errors in the following list MgErrs are discussed in Chapter 5 Manager Overview Parameter Type Description dataH UHandle The handle you want to resize paramNum int32 The number for this parameter in the argument list to the CIN The leftmost parameter has a parameter number of 0 and the rightmost has a parameter number of n 1 where n is the total number of parameters newNumElmts int32 The new number of elements to which the handle should refer For a one dimensional array of five values you pass a value of 5 for this argument For a two dimensional array of two rows by three columns you pass a value of 6 for this argument Error Description noErr No error mFullErr Not enough memory to perform operation mZoneErr Handle is not in specified zone Chapter 2 CIN Parameter Passing National Instruments Corporation 2 13 LabVIEW Code Interface Reference Manual NumericArrayResize syntax MgErr NumericArrayResize int32 typeCode int32 numDims UHandle dataHP int32 totalNewSize NumericArrayResize resizes a data handle referring 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 Parameter Type Description typeCode int32 Describes the data type for the array you wan
146. ss to the CIN For example consider the following call to a CIN which takes a 32 bit integer as an input and returns a 32 bit integer as an output The following code excerpt is the initial c file for this node Eight routines may be written for the CIN The CINRun routine is required the others are optional If an optional routine is not present a default routine is supplied when the CIN is built These eight routines are discussed in detail in subsequent chapters The c file is presented here to give you an idea of what LabVIEW creates at this stage in building a CIN CIN source file include extcode h CIN MgErr CINRun int32 num_in int32 num_out CIN MgErr CINRun int32 num_in int32 num_out ENTER YOUR CODE HERE return noErr Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 10 National Instruments Corporation This c file is a template in which you must write C code Notice extcode h is automatically included it is a file that defines basic data types and a number of routines that can be used by CINs and external subroutines extcode h defines some constants and types whose definitions may conflict with the definitions of system header files The LabVIEW cintools directory also contains a file hosttype h that resolves these differences This header file also includes many of the common header files for a given platform Always use include extcode h at the beginn
147. statements in control flow languages cast To change the type descriptor of a data element without altering the memory image of the data chart See scope chart strip chart and sweep chart CIN source code Original uncompiled text code See object code cluster A set of ordered unindexed data elements of any data type including numeric Boolean string array or cluster The elements must be all controls or all indicators Code Interface Node Special block diagram node through which you can link conventional text based code to a VI code resource Resource containing executable machine code You link code resources to LabVIEW through a CIN compile Process that converts high level code to machine executable code LabVIEW automatically compiles VIs before they run for the first time after creation or alteration concatenated Pascal string CPStr A list of Pascal type strings concatenated into a single block of memory Glossary National Instruments Corporation G 3 LabVIEW Code Interface Reference Manual connector Part of the VI or function node containing its input and output terminals through which data passes to and from the node control Front panel object for entering data to a VI interactively or to a subVI programmatically control flow Programming system in which the sequential order of instructions determines execution order Most conventional text based programming languages such as C Pascal an
148. t cinmake sum Microsoft Windows 3 1 Watcom C Compiler As described in the Calling Code section of this chapter when you compile a CIN referencing an external subroutine you use the same makefile as described in the Steps for Creating a CIN section of the Chapter 1 CIN Overview with the addition of a directive identifying the subroutines this CIN uses Following are the contents of the makefile specification for this example Notice the Dir command must end without a backslash Name the makefile calcmean lvm name name calcmean type type CIN codeDir codeDir Complete pathname to the directory containing the c file cinToolsDir cinToolsDir Complete or partial pathname to the LabVIEW cintools directory inclDir inclDir optional Complete or partial pathname to a directory containing additional h files Chapter 4 External Subroutines National Instruments Corporation 4 13 LabVIEW Code Interface Reference Manual wcDir wcDir Complete pathname to the directory containing the Watcom C compiler subrNames subrNames sum include cinToolsDir generic mak Create the CIN using the following command wmake f calcmean lvm Microsoft Windows 95 and Windows NT Microsoft Visual C Command Line As described in the Calling Code section of this chapter when you compile a CIN referencing an external subroutine you use the same makefile as described in the Steps for Creating a CIN section of t
149. t contain a scrollbar DbgPrintf is described in the section entitled Debugging External Code in Chapter 1 CIN Overview of this manual If you are using a Macintosh and have Macsbug you can use the Debugger and DebugStr statements to set breakpoints in the code If you suspect your CIN is corrupting memory use DSHeapCheck FALSE to test for integrity Observe the heap integrity when you enter and again when you exit the CIN code to determine if your code is corrupting the heap Use the File Manager functions to write your debugging information to a file If you are observing this file while the CIN is running do not forget to flush the file before the information gets to the disk If the VI containing the CIN executes without crashing but you do not have an external window and decide not to use DbgPrintf then a determine what information is pertinent to your problem and b return the information from one of the parameters of the CIN to the block diagram of the VI Appendix A CIN Common Questions National Instruments Corporation A 3 LabVIEW Code Interface Reference Manual Is there any sort of scanf function in the LabVIEW manager routines No National Instruments is investigating this functionality for a future version of LabVIEW CINs with LabVIEW for Sun can call the standard scanf and related functions I can t seem to link to any of the globals mentioned in the LabVIEW Code Interface Reference
150. t to resize The header file extcode h defines the following constants for this argument iB Data is an array of signed 8 bit integers iW is an array of signed 16 bit integers iL Data is an array of signed 32 bit integers uB Data is an array of unsigned 8 bit integers uW Data is an array of unsigned 16 bit integers uL Data is an array of unsigned 32 bit integers fS Data is an array of single precision 32 bit numbers fD Data is an array of double precision 64 bit numbers fX Data is an array of extended precision numbers cS Data is an array of single precision complex numbers cD Data is an array of double precision complex numbers cX Data is an array of extended precision complex numbers Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 14 National Instruments Corporation returns MgErr which can contain the errors in the following list Parameter Type Description numDims int32 The number of dimensions in the data structure to which the handle refers Thus if the handle refers to a two dimensional array you pass a value of 2 for numDims dataHP UHandle A pointer to the handle you want to resize If this is a pointer to NULL LabVIEW allocates and sizes a new handle appropriately and returns the handle in dataHP totalNewSize int32 The new number of elements to which the handle should refer For a unidimensional array of five values you pass a value of 5
151. te arrays Chapter 5 Manager Overview National Instruments Corporation 5 5 LabVIEW Code Interface Reference Manual Strings LabVIEW supports C style strings and Pascal style strings a special string data type you use for string parameters to external code modules called LStr and lists of strings The support manager contains routines for manipulating strings and converting them among the different types of strings C Style Strings CStr A C 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 segment is the type definition for a C style string typedef uChar CStr Pascal Style Strings PStr A Pascal string PStr is a series of unsigned characters The value of the first character indicates the length of the string This gives a range of 0 to 255 characters The following code segment is the type definition for a Pascal style string typedef uChar Str255 256 Str31 32 StringPtr StringHandle typedef uChar PStr LabVIEW Strings LStr The first four bytes of a LabVIEW string LStr indicate the length of the string and the specified number of characters follow This is the string data type used by LabVIEW block diagrams The following code segment is the type definition for an LStr string typedef struct int32 cnt number of bytes that fo
152. te while a CIN executes Multiple References to the Same CIN in a Single VI If you have loaded the same code resource into multiple CINs or you have duplicated a given code interface node 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 the LabVIEW calls the CINLoad routine only once when the resource is first loaded into memory though it is also called if you load a new version of the resource as described in the previous section When you unload the VI LabVIEW calls CINUnload once Chapter 3 CIN Advanced Topics LabVIEW Code Interface Reference Manual 3 6 National Instruments Corporation After LabVIEW calls CINLoad it calls CINInit once for each reference to the CIN because its CIN data space may need initialization Thus if you have two nodes in the same VI where both reference the same code the LabVIEW calls the CINLoad routine once and the CINInit twice If you later load another VI referencing the same code resource then LabVIEW calls CINInit again for the new version LabVIEW has already called CINLoad once and does not call it again for this new reference Figure 3 2 Three CINs Referencing the Same Code Resource 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
153. ters The DLL function will accept two parameters The first is the message to display in the window The second is the title to display in the window Both parameters are C strings meaning they are pointers to the characters of the string followed by a terminating null character Save the code in a file called MSGBXDLL C MSGBXDLL C include lt windows h gt include lt dos h gt void FAR PASCAL Lib1 LPSTR message LPSTR winTitle _16MessageBox NULL message winTitle MB_OK MB_TASKMODAL int PASCAL WinMain HANDLE hInstance HANDLE x1 LPSTR lpCmdLine int x2 DefineDLLEntry 1 void Lib1 DLL_PTR DLL_PTR DLL_ENDLIST return 1 Chapter 3 CIN Advanced Topics National Instruments Corporation 3 17 LabVIEW Code Interface Reference Manual In addition to the C file you also need to create the following MSGBXDLL LNK file system win386 file msgbxdll option map option stack 12K option maxdata 8K option mindata 4K Enter the following commands at the DOS prompt to create the DLL C gt wcc386 msgbxdll zw C gt wlink msgbxdll C gt wbind msgbxdll d n Following is the LabVIEW block diagram for a VI calling a CIN that calls the previously described DLL It passes two LabVIEW strings to the CIN and the CIN returns an error code The CIN Code The following C code is for a CIN calling the DLL you created previously This code assumes the h file created by LabVIEW is n
154. th Specifications LabVIEW uses three different kinds of filepath specifications conventional empty and LabVIEW specifications described below Conventional Path Specifications 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 and the last name is the file or directory the path identifies There are two types of paths relative paths and absolute paths A relative path describes the location of a file or directory relative to Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 14 National Instruments Corporation 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 For instance on a UNIX system 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 You can indicate the path shou
155. that accepts a single 32 bit signed integer the c file indicates the CINRun routine is passed an int32 by reference extcode h typedefs an int32 to the appropriate data type for the compiler you use if it is a supported compiler therefore you can use the int32 data type in external code you write How LabVIEW Passes Fixed Sized Data to CINs As described in the Steps for Creating a CIN section of Chapter 1 CIN Overview you can designate terminals on the CIN as either input output or output only Regardless of the designation LabVIEW passes data by reference to the CIN When modifying a parameter value be careful to follow the rules described for each kind of terminal in the Steps for Creating a CIN section of Chapter 1 CIN Overview 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 and the last terminal pair corresponds to the last parameter The following section describes how LabVIEW passes fixed sized parameters to CINs See the How LabVIEW Passes Variably Sized Data to CINs section of this chapter for information on manipulating variably sized data such as arrays and strings 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 subsequent Arrays
156. the LabVIEW routine that accounts for alignment and padding requirements resizes the array Notice 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 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 the following illustration For an array with r rows and c columns you can access the element at row i and column j as shown in the following code fragment value arrayh gt arg1 i c j Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 20 National Instruments Corporation Working with Clusters The following example takes an array of clusters and a single cluster as inputs and the clusters contain a signed 16 bit integer and a string The input for the array of clusters is an input output terminal In addition to the array of clusters the CIN returns a Boolean and a signed 32 bit integer If the cluster value is already present in the array of clusters the CIN sets the Boolean to TRUE and returns the position of the cluster in the array of clusters using the 32 bit integer output If the cluster value is not present the CIN adds it to the array sets the Boolean output to FALSE and returns the new position of the cluster in the array of clusters
157. the VI you are saving Multiple Reference 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 it is for mutlithreaded operating systems To take advantage of multithreading you must use LabVIEW 5 x on an operating system supporting it Windows 95 Windows NT Solaris 2 x and Concurrent PowerMAX global storage code globals VI data space 4 byte CIN data space 4 byte CIN data space 4 byte CIN data space data space globals code resource VI Chapter 3 CIN Advanced Topics National Instruments Corporation 3 7 LabVIEW Code Interface Reference Manual Single Threaded Operating Systems When you make a VI reentrant LabVIEW creates a separate data space for each usage of that VI If you have a CIN data space in a reentrant VI and you call that VI in seven places LabVIEW allocates memory to store seven CIN data spaces for that VI each of which contains a unique storage location for the CIN data space for that calling instance As with multiple instances of the same node LabVIEW calls the CINInit CINDispose and CINAbort routines for each individual CIN data space In the case where 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 resour
158. the folder containing the c file cinToolsDir cinToolsDir Complete or partial pathname to the LabVIEW cintools folder inclDir inclDir optional Complete or partial pathname to a folder containing additional h files Create the subroutine using the following command Directory lt full pathname to CIN directory gt cinmake sum Microsoft Windows 3 1 Watcom C Compiler As described in the External Subroutines section of this chapter you compile an external subroutine the same way you compile a CIN The first step is to create a makefile specification Following are the contents of the makefile specification for this example Notice all Dir commands must end without a backslash Name the file sum lvm name name sum type type LVSB codeDir codeDir Complete pathname to the directory containing the c file cinToolsDir cinToolsDir Complete or partial pathname to the LabVIEW cintools directory Chapter 4 External Subroutines National Instruments Corporation 4 9 LabVIEW Code Interface Reference Manual inclDir inclDir optional Complete or partial pathname to a directory containing any additional h files wcDir wcDir Complete pathname to the directory containing the Watcom C compiler include cinToolsDir generic mak Create the subroutine using the following command wmake f sum lvm Microsoft Windows 95 and Windows NT As described in the External Subroutines section of t
159. the handle you access the correct data Chapter 5 Manager Overview National Instruments Corporation 5 9 LabVIEW Code Interface Reference Manual You use handles to perform most memory allocation in LabVIEW Pointers are available however because in some cases they are more convenient and simpler to use Memory Zones LabVIEW s memory manager interface has the ability to distinguish between two distinct sections called zones 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 and routines for the application zone begin with AZ Currently the two zones are actually one zone but this may change in future releases of LabVIEW therefore a CIN programmer should write programs 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 you 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 Paths which use AZ handles You should only use file manager functions not the AZ memory manager routines to manipulate Paths Thus your CINs should use the DS memory routines when working with parameters passed from th
160. the variable is a pointer Chapter 5 Manager Overview National Instruments Corporation 5 11 LabVIEW Code Interface Reference Manual The second line creates a block of memory in the data space large enough to hold a single signed 32 bit 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 fourth 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 The first line declares the variable myInt32H as a handle to an a signed 32 bit integer Strictly speaking this line declares myInt32H as a pointer to a pointer to an int32 As with the previous example this declaration does not allocate memory for the int32 it 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
161. tive path consisting of only one name You can 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 Hard Drive Home Gregg MyApps README Two relative paths to the same file are as follows Gregg MyApps README relative to the Home directory MyApps README relative to a directory inside of the Gregg directory Empty Path Specifications In LabVIEW you can define 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 On a UNIX system a slash represents the empty absolute path The slash specifies the root of the file hierarchy A period represents the empty relative path On the PC you represent the empty absolute path as an empty string It specifies the set of all volumes on the system A period represents the empty relative path On the Macintosh the empty absolute path is represented as an empty string It specifies the set of all volumes on the system A colon represents the empty relative path Chapter 5 Manager Overview LabVIEW Code Interface Reference Manual 5 16 National Instruments Corporation LabVIEW Path Specification In LabVI
162. tmpp gt number elementp gt number if LStrCmp tmpp gt string elementp gt string 0 break tmpp if i lt size positionp i presentp LVTRUE goto out newStringh elementp gt string if err DSHandToHand UHandle amp newStringh goto out newNumElements size 1 if err SetCINArraySize UHandle clusterTableh ParamNumber newNumElements DSDisposeHandle newStringh goto out clusterTableh gt dimSize size 1 newElementp amp clusterTableh gt arg1 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 element is present CINRun then compares string components using the LabVIEW routine LStrCmp which is described in the CIN Function Overview section of the LabVIEW Online Reference If CINRun finds the element the routine returns the position of the element in the array Chapter 2 CIN Parameter Passing National Instruments Corporation 2 23 LabVIEW Code Interface Reference Manual If the routine does not find the element you have to add a new element to the array Use the memory manager routine DSHandToHand to create a new handle containing the same string as the one in the cluster element you passed to the CIN CINRun then increases
163. u call DbgPrintf LabVIEW opens a window to display the text you pass to the function Subsequent calls to DbgPrintf 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 DbgPrintf 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 var1 print the contents of an LStrHandle LabVIEW string opening the window if necessary DbgPrintf NULL close the debugging window Debugging CINs Under Windows 95 NT Windows 95 and Windows NT support source level debugging of CINs using Microsoft s Visual C environment To debug CINs under Windows 95 NT complete the following steps 1 Modify your CIN to set 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 Once the debugging symbols are loaded you can set normal debug points inside Visual C Windows 95 has a single method of setting a debugger trap Windows NT can use the Windows 95 method or another Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 38 National Instruments Corporation The method common to Windows 95
164. ubmit technical support questions to the applications engineering team through e mail at the Internet address listed below Remember to include your name address and phone number so we can contact you with solutions and suggestions support natinst com Telephone and Fax Support National Instruments has branch offices all over the world Use the list below to find the technical support number for your country If there is no National Instruments office in your country contact the source from which you purchased your software to obtain support Country Telephone Fax Australia 03 9879 5166 03 9879 6277 Austria 0662 45 79 90 0 0662 45 79 90 19 Belgium 02 757 00 20 02 757 03 11 Brazil 011 288 3336 011 288 8528 Canada Ontario 905 785 0085 905 785 0086 Canada Quebec 514 694 8521 514 694 4399 Denmark 45 76 26 00 45 76 26 02 Finland 09 725 725 11 09 725 725 55 France 01 48 14 24 24 01 48 14 24 14 Germany 089 741 31 30 089 714 60 35 Hong Kong 2645 3186 2686 8505 Israel 03 6120092 03 6120095 Italy 02 413091 02 41309215 Japan 03 5472 2970 03 5472 2977 Korea 02 596 7456 02 596 7455 Mexico 5 520 2635 5 520 3282 Netherlands 0348 433466 0348 430673 Norway 32 84 84 00 32 84 86 00 Singapore 2265886 2265887 Spain 91 640 0085 91 640 0533 Sweden 08 730 49 70 08 730 43 70 Switzerland 056 200 51 51 056 200 51 55 Taiwan 02 377 1200 02 737 4644 United Kingdom 01635 523545 01635 523154 United States 512 79
165. ubrNames subrNames optional For 68K Macintosh only list of external subroutines the CIN calls You need subrNames only if the CIN calls external subroutines Separate the names of subroutines with spaces ShLibs sharedLibraryNames optional For Power Macintosh only a space separated 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 Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 24 National Instruments Corporation ShLibMaps sharedLibMappings optional For Power Macintosh only the command 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 will usually look something like the following librename libA xcoff libA librename libB xcoff libB Notice 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 set commands commands lt pathname to directory of cinToolsDir gt Go to the MPW Worksheet and enter the following commands First set your current folder to the CIN folder using the MPW Directory command Directory lt pathname to directory of your CIN gt Next r
166. uct 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 a front panel Wire the node as shown in the following illustration Notice A B is wired to an output only terminal pair Save the VI as mult vi 4 Select Create c File from the CIN node pop up menu LabVIEW prompts you to select a name and a storage location for a c file Name the file mult c LabVIEW creates a c file shown in the following listing CIN source file 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 Chapter 2 CIN Parameter Passing National Instruments Corporation 2 5 LabVIEW Code Interface Reference Manual This c file contains a prototype and a template for the CIN s CINRun routine LabVIEW calls the CINRun routine when the CIN executes In this example LabVIEW passes CINRun the addresses of the three 32 bit floating point numbers The parameters are listed left to right in the same order as you wired them top to bottom to the CIN Thus A B and A_B are pointers to A B and A B respectively As described in the CIN c File section of this chapter the float32 data type is not a standard C data type When LabVIEW creates a c file it gives unambiguous
167. un the LabVIEW CINMake script CINMake lt name of your CIN gt If CINMake does not find a lvm file in the current folder it builds a file named cinName lvm and prompts you for necessary information This file cinName lvm is in a format compatible with building both Power Macintosh and 68K Macintosh CINs in the same folder If CINMake finds a cinName lvm but it does not have the line LVMVers 2 saves the lvm file in cinName lvm old and update the cinName lvm file to be compatible with the new version of CINMake Chapter 1 CIN Overview National Instruments Corporation 1 25 LabVIEW Code Interface Reference Manual The format of the CINMake command follows with the optional parameters listed in brackets CINMake MakeOpts opts RShell PPC MrC SC C dbg noDelete lt name of your CIN gt MakeOpts opts specifies extra options to pass to make Rshell PPC MrC SC C Use one of these options to specify the compiler to use dbg If this argument is specified CINMake prints out statements describing what it is doing noDelete If this argument is specified CINMake will not delete temporary files used when making the CIN You can use LVMakeMake to build an MPW makefile you can then customize for your own purposes You should only have to run LVMakeMake once for a given CIN You can modify the resulting makefile by adding the proper header file dependencies or by adding other object files t
168. unding VI is reentrant there is only one copy of these globals in memory and their values are consistent When you create a CIN node LabVIEW allocates a CIN data space a 4 byte storage location in the VI data space s strictly for the use of the CIN node Each CIN may have one or more CIN data spaces reserved for the node depending on how many times the node 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 later in this chapter Figure 3 1 Data Storage Spaces for One CIN Simple Case A CIN node 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 so LabVIEW links the CIN to the code resource for execution purposes VI data space code resource global storage code globals data space globals 4 byte CIN data space VI Chapter 3 CIN Advanced Topics National Instruments Corporation 3 3 LabVIEW Code Interface Reference Manual This linking behaves the same way as links between VIs and subVIs When you try to reference 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 referen
169. up menu to Apple C Empty the Prefix File text field Processor Check the 68881 Codegen and MPW C Calling Conventions checkboxes Leave the 4 Byte Ints and 8 Byte Doubles checkboxes unchecked Linker Check the Generate Link Map checkbox Project Set the Project Type pop up menu to Code Resource Set the File Name text field to cinName tmp where cinName is the name of your CIN Set the Resource Name text field to the same text as in the File Name text field Set the Type text field to tmp and the ResType text field to CUST Set the ResID text field to 128 Set the Header Type pop up menu to Custom Set the Creator to LVsb Access Paths Add your cintools folder to the list of access paths Build the CIN by selecting Make from the CodeWarrior Project menu Caution This operation will destroy the contents of any other file named cinName tmp in that folder This could easily be the case if this is the same folder in which you build a Power Macintosh version of your CIN If you are building for both platforms you should keep separate directories for each The convention used by the MPW CIN tools is to have two subdirectories named PPCObj and M68Obj where all platform specific files reside Note If you have both a ThinkC68K and a MetrowerksC68K map file lvbutil cannot know in advance which compiler your tmp file came from It will first look for a ThinkC map file then for a Metrowerks map file To avoid any co
170. utine name gt void move l gLVSB lt external subroutine name gt a0 jmp a0 MPW Compiler The makefile for a calling CIN is the same as described in the Steps for Creating a CIN section of Chapter 1 CIN Overview except you use the optional subrNames directive to identify the subroutines the CIN references Specifically if your code calls two external subroutines A and B you need to have the following line in the makefile code subrNames A B Chapter 4 External Subroutines LabVIEW Code Interface Reference Manual 4 6 National Instruments Corporation Microsoft Windows 3 1 Windows 95 and Windows NT The makefile for a calling CIN is the same as described in the Steps for Creating a CIN section of Chapter 1 CIN Overview except you use the optional subrNames directive to identify the subroutines the CIN references Specifically if your code calls two external subroutines A and B you need to have the following line in the code makefile prior to the include statement subrNames A B If you are using the Visual C IDE follow the steps described in Steps for Creating a CIN section of Chapter 1 CIN Overview with the exception of adding lvsb obj instead of cin obj to your project Solaris 1 x Solaris 2 x HP UX and Concurrent PowerMAX Unbundled Sun C Compiler HP UX C ANSI C Compiler and Concurrent C Compiler The lvmkmf command for a calling CIN is the same as described in the Steps for Creating a CIN s
171. xecution thread running the CIN is locked up However if there is only one execution thread other VIs are prevented from running Chapter 1 CIN Overview LabVIEW Code Interface Reference Manual 1 2 National Instruments Corporation A VI executing a CIN can not be reset until the CIN completes the executing CIN object code cannot be interrupted by LabVIEW Although you can create VIs that use CINs and behave in a more asynchronous fashion be aware of this potential problem if you intend to write a CIN that executes a long task and you need LabVIEW to multitask in the interim A CIN appears on the diagram as an icon with input and output terminals You associate this node with a section of code you want LabVIEW to call When it is time for the node to execute LabVIEW calls the code associated with the CIN passing it the specified data In some cases you may want a CIN to perform additional actions at certain execution times For example you might want to initialize data structures at load time or free private data structures when the user closes the VI containing the CIN For these situations you can write routines 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 on going action such as accumulating results from call to call so you can alloc
172. xternal code you want to create For CINs you should use CIN which is the default ext is needed only if this external code calls external subroutines The argument to this directive is the name of a file containing the names of all subroutines this code calls with one name per line The file is not necessary to run the lvmkmf script but it must be present before you can successfully make the CIN If you do not specify a ext option lvmkmf assumes the CIN does not reference any external subroutines The makefile produced assumes the cin o libcin a makeglueXXX awk and lvsbutil files are in certain locations where XXX is BSD on Solaris 1 x SVR4 or Solaris 2 x HP on HP UX and Concurrent on Concurrent PowerMAX If these assumptions are incorrect you can edit the makefile to correct the pathnames Chapter 1 CIN Overview National Instruments Corporation 1 33 LabVIEW Code Interface Reference Manual If you specify the ext argument to the lvmkmf script the makefile creates temporary files For example if the gluefile name is bar the makefile creates files bar s and bar o Neither the CIN nor the makefile needs these files after the CIN has been created If you make external subroutines you need to create a separate makefile for them The lvmkmf script creates a file called Makefile unless you use the o option For this reason you may want to place the code for each subroutine in separate directories to avoid writing over one
173. ze of the first string to the length of the concatenated string Chapter 2 CIN Parameter Passing National Instruments Corporation 2 17 LabVIEW Code Interface Reference Manual Computing the Cross Product of Two Two Dimensional Arrays The following example shows how to create a CIN that accepts two two dimensional arrays and then 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 This Boolean 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 Follow the instructions in the Steps for Creating a CIN section of Chapter 1 CIN Overview to create the CIN The front panel for this VI is shown in the following illustration Save the VI as cross vi The block diagram for this VI is shown in the following illustration Save the c file for the CIN as cross c Following is the source code for cross c with the CINRun routine added CIN source file include extcode h define ParamNumber 2 The return parameter is parameter 2 Chapter 2 CIN Parameter Passing LabVIEW Code Interface Reference Manual 2 18 National Instruments Corporation define NumDimensions 2 2D Array typedefs typedef struct int32 dimSizes 2 float64 arg1 1 TD1 typedef TD1 TD1Hdl CIN MgErr

LabVIEW Code Interface Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents