LabVIEWTM Intermediate II Connectivity Course Manual · · 2007-10-02Sample Lesson 1 Calling Shared Libraries in LabVIEW LabVIEW Intermediate II Course Manual 1-2 ni.com A. Shared

Sample

LabVIEWTM Intermediate II Connectivity Course Manual

Course Software Version 8.2February 2007 EditionPart Number 323758C-01

LabVIEW Intermediate II Course Manual

Copyright

© 2004–2007 National Instruments Corporation. All rights reserved. Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, includingphotocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National Instruments Corporation.

National Instruments respects the intellectual property of others, and we ask our users to do the same. NI software is protected by copyright and other intellectual property laws. Where NI software may be used to reproduce software or other materials belonging to others, you may use NI software only to reproduce materials that you may reproduce in accordance with the terms of any applicablelicense or other legal restriction.

The following notices relate to certain components used in USI (Xerces C++, ICU, and HDF5). For a listing of the conditions anddisclaimers regarding these components, refer to the USICopyrights.chm.

Xerces C++. This product includes software developed by the Apache Software Foundation (http://www.apache.org/).Copyright 1999 The Apache Software Foundation. All rights reserved.

ICU. Copyright 1995–2003 International Business Machines Corporation and others. All rights reserved.

HDF5. NCSA HDF5 (Hierarchical Data Format 5) Software Library and UtilitiesCopyright 1998, 1999, 2000, 2001, 2003 by the Board of Trustees of the University of Illinois. All rights reserved.

TrademarksNational Instruments, NI, ni.com, and LabVIEW are trademarks of National Instruments Corporation. Refer to the Terms of Use section on ni.com/legal for more information about National Instruments trademarks.

Other product and company names mentioned herein are trademarks or trade names of their respective companies.

Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no agency, partnership, or joint-venture relationship with National Instruments.

PatentsFor patents covering National Instruments products, refer to the appropriate location: Help»Patents in your software, the patents.txt file on your CD, or ni.com/legal/patents.

Sample

Worldwide Technical Support and Product Informationni.com

National Instruments Corporate Headquarters11500 North Mopac Expressway Austin, Texas 78759-3504 USA Tel: 512 683 0100

Worldwide Offices

Australia 1800 300 800, Austria 43 662 457990-0, Belgium 32 (0) 2 757 0020, Brazil 55 11 3262 3599, Canada 800 433 3488, China 86 21 6555 7838, Czech Republic 420 224 235 774, Denmark 45 45 76 26 00, Finland 385 (0) 9 725 72511, France 33 (0) 1 48 14 24 24, Germany 49 89 7413130, India 91 80 41190000, Israel 972 3 6393737, Italy 39 02 413091, Japan 81 3 5472 2970, Korea 82 02 3451 3400, Lebanon 961 (0) 1 33 28 28, Malaysia 1800 887710, Mexico 01 800 010 0793, Netherlands 31 (0) 348 433 466, New Zealand 0800 553 322, Norway 47 (0) 66 90 76 60, Poland 48 22 3390150, Portugal 351 210 311 210, Russia 7 495 783 6851, Singapore 1800 226 5886, Slovenia 386 3 425 42 00, South Africa 27 0 11 805 8197, Spain 34 91 640 0085, Sweden 46 (0) 8 587 895 00, Switzerland 41 56 2005151, Taiwan 886 02 2377 2222, Thailand 662 278 6777, Turkey 90 212 279 3031, United Kingdom 44 (0) 1635 523545

For further support information, refer to the Additional Information and Resources appendix. To comment on National Instruments documentation, refer to the National Instruments Web site at ni.com/info and enter the info code feedback.

Sample

© National Instruments Corporation iii LabVIEW Intermediate II Course Manual

Contents

Student GuideA. NI Certification .....................................................................................................vB. Course Description ...............................................................................................viC. What You Need to Get Started .............................................................................viD. Installing the Course Software..............................................................................viiE. Course Goals.........................................................................................................viiF. Course Conventions ..............................................................................................viii

Lesson 1Calling Shared Libraries in LabVIEW

A. Shared Library Overview......................................................................................1-2B. Calling Shared Libraries .......................................................................................1-2Exercise 1-1 Computer Name................................................................................1-13Summary.....................................................................................................................1-32

Lesson 2VI Server

A. What is VI Server?................................................................................................2-2B. VI Server Programming Model ............................................................................2-4C. VI Server Functions ..............................................................................................2-5Exercise 2-1 Concept: VI Server Options .............................................................2-13Exercise 2-2 VI Statistics ......................................................................................2-15D. Remote Communication .......................................................................................2-23Exercise 2-3 Concept: Remote Run VI .................................................................2-25E. Dynamically Calling and Loading VIs .................................................................2-29Exercise 2-4 Dynamically Calling VIs..................................................................2-34Summary.....................................................................................................................2-38

Lesson 3Calling Objects in LabVIEW

A. Calling Objects in LabVIEW Using ActiveX.......................................................3-2B. Using LabVIEW as an ActiveX Client.................................................................3-3Exercise 3-1 Browse to URL.................................................................................3-7Exercise 3-2 VI Statistics Report...........................................................................3-12C. Using LabVIEW as an ActiveX Server ................................................................3-15Exercise 3-3 Frequency Response VI....................................................................3-17D. ActiveX Events .....................................................................................................3-19E. Calling Objects in LabVIEW Using .NET ...........................................................3-21F. Implementing .NET ..............................................................................................3-23Exercise 3-4 Font Dialog.......................................................................................3-26Exercise 3-5 Word Processor ................................................................................3-32

Sample

Contents

LabVIEW Intermediate II Course Manual iv ni.com

G. Registering .NET Events ......................................................................................3-54Exercise 3-6 Auto Save .........................................................................................3-56Summary.....................................................................................................................3-64

Lesson 4Broadcasting Data

A. Broadcasting Data Overview ................................................................................4-2B. Implementing Broadcast Models ..........................................................................4-5Exercise 4-1 VI Statistics Broadcast .....................................................................4-7Summary.....................................................................................................................4-13

Lesson 5Serving Data to a Client Using TCP/IP

A. TCP/IP Overview..................................................................................................5-2Exercise 5-1 Concept: Simple Data Client VI and Simple Data Server VI ..........5-7B. Implementing the Client/Server Model ................................................................5-10Exercise 5-2 TCP File Transfer .............................................................................5-13Summary.....................................................................................................................5-25

Lesson 6Publishing Data to a Subscriber

A. Publisher/Subscriber Communication Model Overview ......................................6-2B. Implementing the Publisher/Subscriber Communication Model..........................6-10Exercise 6-1 Publisher and Subscriber ..................................................................6-17Summary.....................................................................................................................6-24

Appendix AAdditional Information and Resources

Index

Course Evaluation

Sample

© National Instruments Corporation 1-1 LabVIEW Intermediate II Course Manual

1Calling Shared Libraries in LabVIEW

You can use LabVIEW to call code written in other languages in the following ways:

• Using platform-specific protocols.

• Using the Call Library Function Node to call the following types of shared libraries:

– Dynamic Link Libraries (DLL) on Windows

– Frameworks on Mac OS

– Shared Libraries on Linux

The scope of this course covers using the Call Library Function Node tocall Dynamic Link Libraries (shared libraries) on Windows. Refer to the LabVIEW Help for information about other ways to use LabVIEW to call code written in other languages.

Topics

A. Shared Library OverviewB. Calling Shared Libraries

Sample

Lesson 1 Calling Shared Libraries in LabVIEW

LabVIEW Intermediate II Course Manual 1-2 ni.com

A. Shared Library OverviewOn Windows, a shared library is called a DLL. A shared library is a library of executable functions or data that can be used by a Windows application. A shared library provides one or more functions that a program can access by creating a static or dynamic link to the shared library. A static link remains constant during program execution and a dynamic link is created by the program as needed. The shared library is stored as a binary file.

You can use any language to write DLLs as long as the DLLs can be called using one of the calling conventions LabVIEW supports, either stdcall or C. Examples and troubleshooting information help you build and use DLLs and successfully configure the Call Library Function Node in LabVIEW. The general methods described here for DLLs also apply to other types of shared libraries.

LabVIEW loads DLLs in a unique application instance. Opening a DLLin a unique application instance prevents naming conflicts with VIs in the DLL, and VIs outside of the DLL.

Refer to the labview\examples\dll directory for examples of using shared libraries.

B. Calling Shared LibrariesThis section describes the process of using a shared library in LabVIEW.

Describing and Defining Shared LibrariesYou can call most standard shared libraries with the Call Library Function Node. On Windows, these shared libraries are DLLs, on Mac OS, they are Frameworks, and on Linux, they are Shared Libraries. The Call Library Function Node includes a large number of data types and calling conventions. You can use the Call Library Function Node to call functions from most standard and custom-made libraries.

Functions, Advantages, and Limitations of DLLsDLLs have the following advantages:

• You can change the DLL without changing any of the VIs that link to the DLL, provided you do not modify the function prototypes.

• Practically all modern development environments provide support for creating DLLs.

In some cases, you may want to perform additional tasks at certain execution times. For this purpose, the Call Library Function Node provides three entry points—Reserve, Unreserve, and Abort. For example, you may want to

Sample



initialize data structures at reserve time for the Call Library Function Node or free private data when the Call Library Function Node is unreserved or aborted. For these situations, you can write and export routines from your DLL that LabVIEW calls at these predefined times. You can configurethese entry points on the Callbacks page of the Call Library Functiondialog box.

The Call Library Function Node is most appropriate when you have existing code you want to call, or if you are familiar with the process of creating standard shared libraries. Because a library uses a format standard among several development environments, you can use almost any development environment to create a library that LabVIEW can call. Refer to the documentation for your compiler to determine whether you can create standard shared libraries.

The LabVIEW compiler can generate code fast enough for most programming tasks. Call shared libraries from LabVIEW to accomplish tasks a text-based language can accomplish more easily, such as time-critical tasks. Also use shared libraries for tasks you cannot perform directly from the block diagram, such as calling system routines for which no corresponding LabVIEW functions exist. Shared libraries also can link existing code to LabVIEW, although you might need to modify the code so it uses the correct LabVIEW data types.

Shared libraries execute synchronously, so LabVIEW cannot use the execution thread used by these objects for any other tasks.

LabVIEW cannot interrupt object code that is running, so you cannot reset a VI that is running a shared library until execution completes. If you want to write a shared library that performs a long task, be aware that LabVIEW cannot perform other tasks in the same thread while these objects execute.

When a VI runs, LabVIEW monitors the user interface, including the menus and keyboard. In multithreaded applications, LabVIEW uses a separate thread for user interface tasks. In single-threaded applications, LabVIEW switches between user interface tasks and running VIs.

When shared library object code executes, it takes control of its execution thread. If an application has only a single thread of control, the application waits until the object code returns. In single-threaded operating systems such as Mac OS, shared libraries prevent other applications from running.

Method for Calling Shared LibrariesUse the Call Library Function Node to directly call a 32-bit Windows DLL, a Mac OS Framework, or a Linux Shared Library function. With this node, you can create an interface in LabVIEW to call existing libraries or new

Sample



libraries specifically written for use with LabVIEW. National Instruments recommends using the Call Library Function Node to create an interface to external code.

Note Be aware when using the Call Library Function Node or writing code that is called by the Call Library Function Node that LabVIEW reserves Windows messages WM_USER through WM_USER+99 for internal use only.

Right-click the Call Library Function Node and select Configure from the shortcut menu to open the Call Library Function dialog box, shown in the following figure. Use the Call Library Function dialog box to specify the library, function, parameters, return value for the node, calling conventions, and function callbacks on Windows. When you click the OK button in the Call Library Function dialog box, LabVIEW updates the Call Library Function Node according to your settings, displaying the correct number of terminals and setting the terminals to the correct data types.

Setting the Calling ConventionCalling conventions define the way to pass information from a piece of code to a function. Use the Calling convention control on the Function tab of the Call Library Function dialog box to select the calling convention for the function. The default calling convention is C.

(Windows) You also can use the standard Windows calling convention, stdcall.

Sample



Refer to the documentation for the DLL you want to call for the appropriate calling conventions.

Caution Using the incorrect calling convention can cause an irregular shutdown of LabVIEW.

Configuring ParametersTo configure parameters for the Call Library Function Node, navigate to the Parameters tab of the Call Library Function dialog box. Initially, the Call Library Function Node has no parameters and has a return type of Void.

As you configure parameters, the Function Prototype text box displays the C prototype for the function you are building. This text box is a read-only display.

Note If a type library is found, the parameters are updated to match the parameters found in the type library for the selected function.

The return type for the Call Library Function Node returns to the right terminal of the top pair of terminals. If the return type is void, the top pair of terminals is unused. Each additional pair of terminals corresponds to a parameter in the Parameters list of the Call Library Function Node. To pass a value to the Call Library Function Node, wire to the left terminal of a terminal pair. To read the value of a parameter after the Call Library Function Node call, wire from the right terminal of a terminal pair. The following figure shows a Call Library Function Node that has a return type of void, a string parameter, and a numeric parameter.

Return TypeFor return type, you can set Type to void, Numeric, or String. void is only available for return type and is not available for other parameters. Use voidfor the return type if your function does not return any values.

Even if the function you call returns a value, you can use void for the return type. When the function returns a value and you select void as the return type, the value returned by the function is ignored.

Note If the function you are calling returns a data type not listed, choose a return data type the same data size as the one returned by the function. For example, if the function returns a char data type, use an 8-bit unsigned integer. A call to a function in a DLL cannot return a pointer because there are no pointer types in LabVIEW. However, you

Sample



can specify the return type as an integer that is the same size as the pointer. LabVIEW then treats the address as a simple integer, and you can pass it to future DLL calls.

Adding and Deleting ParametersTo add parameters to the Call Library Function Node, navigate to the Parameters tab of the Call Library Function dialog box. Click the Insertbutton. To remove a parameter, click the Delete button. To change the order of the parameters, use the Up and Down buttons to the right of the parameter list.

Editing ParametersSelect the parameter from the Parameters list to edit the data type or parameter name. You can edit the parameter name to something more descriptive, which makes it easier to distinguish between parameters. The parameter name does not affect the call, but it is propagated to output wires. Also, you can edit all fields in the Current Parameter section for the selected parameter.

Selecting the Parameter TypeUse the Type pull-down menu to indicate the type of each parameter. You can select from the following parameter types:

• Numeric

• Array

• String

• Waveform

• Digital Waveform

• Digital Data

• ActiveX

• Adapt to Type

• Instance Data Pointer

After you select an item from the Type pull-down menu, you see more items you can use to indicate details about the parameter and about how to pass the data to the library function. The Call Library Function Node has a number of different items for parameter types because of the variety of data types required by different libraries. Refer to the documentation for the library you call to determine which parameter types to use.

The following sections discuss the different parameter types available from the Type pull-down menu.

Sample



(Windows) Refer to the labview\examples\dll\data passing\Call Native Code.llb for an example of using data types in shared libraries.

NumericFor numeric data types, you must indicate the exact numeric type by using the Data Type pull-down menu. You can choose from the following data types:

• 8-, 16-, 32-, and 64-bit signed and unsigned integers

• 4-byte, single-precision numbers

• 8-byte, double-precision numbers

Note You can pass extended-precision numbers and complex numbers can by selecting Adapt to Type from the Type pull-down menu. However, standard libraries generally do not use extended-precision numbers and complex numbers.

Use the Pass pull-down menu to indicate whether you want to pass the value or a pointer to the value.

ArrayUse the Data Type pull-down menu to indicate the data type of the array. You can choose from the same data types available for numeric parameters.

Specify the dimensions of the array in Dimensions.

Use the Array Format pull-down menu to make one of the following choices:

• Array Data Pointer passes a one-dimensional pointer to the array data, allowing the called library to access the array data as the specified data type of the array data.

• Array Handle passes a pointer to a pointer that points to a four-byte value for each dimension, followed by the data.

• Array Handle Pointer passes a pointer to an array handle.

Use the Minimum Size control to indicate the minimum size of a 1D array and allocate the correct amount of memory. You can enter a numeric value, or, if you configure an integer parameter in the Parameters list, you can select the parameter from the pull-down menu.

Caution Do not attempt to resize an array with system functions, such as realloc.Doing so might crash your system. Instead, use one of the Code Interface Node (CIN) manager functions, such as NumericArrayResize.

Sample



StringUse the String Format pull-down menu to indicate the string format.You can choose from the following string formats:

• C String Pointer—a string followed by a null character

• Pascal String Pointer—a string preceded by a length byte

• String Handle—a pointer to a pointer to four bytes for length information, followed by string data

• String Handle Pointer—a pointer to an array of string handles.

Select a string format that the library function expects. Most standard libraries expect either a C string or a Pascal string. If the library functionyou are calling is written for LabVIEW, you might want to use the StringHandle format.

Use the Minimum Size control to indicate the minimum size of the string and allocate the correct amount of memory. You can enter a numeric value, or, if you configure an integer parameter in the Parameters list, you can select the parameter from the pull-down menu.

Caution Do not attempt to resize a string with system functions, such as realloc,because your system might crash. Instead, use one of the Code Interface Node (CIN) manager functions, such as NumericArrayResize.

String OptionsLabVIEW stores strings as arrays, that is, structures pointed to by handles. The Call Library Function Node works with C and Pascal-style string pointers or LabVIEW string handles. The following illustration shows an example of a LabVIEW string handle.

Think of a string as an array of characters. Assembling the characters in order forms a string. LabVIEW stores a string in a special format in which the first four bytes of the array of characters form a 32-bit signed integer that stores how many characters appear in the string. Thus, a string with n characters requires n + 4 bytes to store in memory. For example, the string text contains four characters. When LabVIEW stores the string, the first four bytes contain the value 4 as a 32-bit signed number, and each of the following four bytes contains a character of the string. The advantage of this

String Data

t\04 t e x\00\00\00

String Length

Sample



type of string storage is that NULL characters are allowed in the string. Strings are virtually unlimited in length, up to 231 characters.

The Pascal string format is similar to the LabVIEW string format, but instead of storing the length of the string as a 32-bit signed integer, it is stored as an 8-bit unsigned integer. This limits the length of a Pascal-style string to 255 characters. A graphical representation of a Pascal string appears in the following illustration. A Pascal string that is n characters long requires n + 1 bytes of memory to store.

C strings are probably the type of strings you deal with most often. The similarities between the C-style string and normal numeric arrays in C becomes much clearer when you notice that C strings are declared as char *. Unlike LabVIEW and Pascal strings, C strings do not contain information that indicates the length of the string. Instead, C strings use a special NULL character to indicate the end of the string, as shown in the following illustration. NULL has a value of zero in the ASCII character set. Notice that this is the number zero and not the character 0.

In C, a string containing n characters requires n + 1 bytes of memory to store, n bytes for the characters in the string and one additional byte for the NULL termination character. The advantage of C-style strings is that they are limited in size only by available memory. However, if you acquire data from an instrument that returns numeric data as a binary string, as is common with serial or GPIB instruments, values of zero in the string are possible. For binary data where NULLs might be present, use an array of 8-bit unsigned integers. If you treat the string as a C-style string, when the instrument returns a numeric value of zero, he program assumes incorrectly that the end of the string has been reached.

WaveformWhen you call a shared library that includes a waveform data type, you do not have to specify a numeric value from the Data Type pull-down menu; the default is 8-byte Double. However, you must specify Dimensions. If the

String Length

String Data

t\04 t e x

NULL Character

String Data

t \00t e x

Sample



parameter is a single waveform, specify Dimensions as 0. If the parameter is an array of waveforms, specify Dimensions as 1. LabVIEW does not support an array of waveforms greater than one-dimensional.

Digital WaveformSpecify Dimensions as 0 if the parameter is a single digital waveform. Specify Dimensions as 1 if the parameter is an array of digital waveforms. LabVIEW does not support an array of digital waveforms greater than one-dimensional.

Digital DataSpecify Dimensions as 1 if the Parameter is an array of digital data. Otherwise, specify Dimensions as 0. LabVIEW does not support an array of digital data greater than one-dimensional.

Note You can pass waveforms, digital waveforms, and digital data through shared libraries, but you cannot access the data inside the shared libraries.

ActiveXSelect one of the following items from the Data Type pull-down menu:

• ActiveX Variant Pointer passes a pointer to ActiveXdata.

• IDispatch* Pointer passes a pointer to the IDispatch interface of an ActiveX Automation server.

• IUnknown* Pointer passes a pointer to the IUnknown interface of an ActiveX Automation server.

Adapt to TypeUse Adapt to Type to pass arbitrary LabVIEW data types to DLLs. The arbitrary LabVIEW data types are passed to DLLs in the following ways:

• Scalars are passed by reference. A pointer to the scalar is passed to the library.

• Arrays and strings are passed according to the Data Format setting. You can choose from the following Data Format settings:

– Handles by Value passes the handle to the library. The handle is not NULL.

– Pointers to Handles passes a pointer to the handle to the library. If the handle is NULL, treat the handle as an empty string or array. To set a value when the handle is NULL, you must allocate a new handle.

• Clusters are passed by reference.

Sample



• Scalar elements in arrays or clusters are in line. For example, a cluster containing a numeric is passed as a pointer to a structure containing a numeric.

• Clusters within arrays are in line.

• Strings and arrays within clusters are referenced by a handle.

Note When one or more of the parameters of the function you want to call in a DLL are of types that do not exist in LabVIEW, ensure that each parameter is passed to the function in a way that allows the DLL to correctly interpret the data. Create a skeleton .c file from the current configuration of the Call Library Function Node. By viewing the .c file, you can determine whether LabVIEW will pass the data in a manner compatible with the DLL function. You then can make any necessary adjustments.

Instance Data PointerUse Instance Data Pointer to access data allocated for each instance of the Call Library Function Node. The instance data pointer references a pointer sized allocation that you may use at your own discretion. This allocation is also passed to each of the callback functions on the Callbacks tab.

Working with Unusual Data TypesYou might encounter a function that expects data in a form that the Call Library Function Node cannot pass. Specifically, the Call Library Function Node does not support structures or arrays containing a pointer to other data or structures containing flat arrays that can be variably sized. You can call a function that expects an unsupported data type in the following ways:

• If the data contains no pointers, you might be able to use the Flatten to String function to create a string containing the binary image of the data required and pass this string as a C string pointer. You will probably want to use the byte order input to Flatten to String to specify that the data be flattened in native byte order.

• Write a library function that accepts the data in the form used by LabVIEW and builds the data structure expected by the other library. This function then can call the other library and retrieve any returned values before returning. Your function will probably accept the data from the diagram as Adapt to Type, so that any diagram data type can be passed.

Thread-Safe and Thread-Unsafe DLLsIn a multithreaded operating system, you can make multiple calls to a DLL or shared library simultaneously. By default, all Call Library Function Nodes run in the user interface thread. The Thread control on the Functiontab of the Call Library Function dialog box reflects your selection of Runin UI Thread or Reentrant.

Sample



Before you configure a Call Library Function Node to be reentrant, make sure that multiple threads can call the function simultaneously. The following characteristics are the basic characteristics of thread safe codein a shared library:

• The code is thread safe when it does not store any global data, such as global variables, files on disk, and so on.

• The code is thread safe when it does not access any hardware. In other words, the code does not contain register-level programming.

• The code is thread safe when it does not make any calls to any functions, shared libraries, or drivers that are not thread safe.

• The code is thread safe when it uses semaphores or mutexes to protect access to global resources.

• The code is thread safe when it is called by only one non-reentrant VI.

Refer to the Execution Properties Page topic of the LabVIEW Help for more information about reentrancy. Refer to the Benefits of Multithreaded Applications topic of the LabVIEW Help for more information about multithreading in LabVIEW.

Sample



Exercise 1-1 Computer Name

GoalCall a DLL function from the Windows API.

ScenarioProgrammatically determining the Windows computer name is necessary in a number of situations. For example, if you have several computers logging data to a central server, you should identify the computer name for each set of data in order to track the data. The computer name is also helpful for storing or retrieving data over a Windows File Share and is a useful piece of information to include when generating reports.

There is not a native function within LabVIEW to retrieve the computer name. However, the Windows operating system provides an API, in the form of DLLs, which allows you to interface with the operating system. One common use of this API is retrieving useful information about the operating system or computer, such as the computer name.

Call a Windows API DLL function to determine the name of the computer. You should also handle any errors returned by the function in an appropriate manner.

Note The Windows computer name is different from the network address of a computer. You can determine a computer’s network address in LabVIEW by using the String to IP and IP to String functions located on the TCP/IP palette.

Design

Inputs and Outputs

Program StructureWhen you call functions from a DLL, the DLL often defines a method for reporting errors. The windows API returns a numeric value from each function call indicating whether the function was executed correctly. In the event of an incorrect execution, you can call additional Windows API

Table 1-1. Computer Name Inputs and Outputs

Type Name Properties Default Values

Numeric Control Buffer Size 32-bit Unsigned Integer

256

String Indicator Computer Name — Empty

Sample



functions to identify the error code and convert the code to an understandable string. In order to correctly identify the error, the error handling functions must be called immediately after the original function call, since the error information will be lost if any other Windows API calls are made from the same program. This error handling mechanism works differently than the normal error handling mechanism in LabVIEW, where each subVI reports its own errors and errors can be chained together and handled at the end of a program or section. To implement this error handling mechanism in LabVIEW, use a state machine to check the return value of each function call and then immediately transfer to an error handling state if an error occurs.

State Machine DesignFor this program you utilize a state machine with three states: Get Computer Name, Handle Error and Stop. The first state gets the computer name. If the state succeeds, the program moves to the Stop state and finishes. If the DLL call to get the computer name fails or if a normal LabVIEW error occurs, the program enters the Handle Error state, where it accesses an error code and translates the error code into an error message.

Get Computer Name CaseThe Windows API provides a function called GetComputerName in Kernel32.dll. You must allocate a string buffer large enough to storethe string returned by the function, fortunately, the Call Library Node in LabVIEW Version 8.20 or later can automatically allocate the buffer based on a size parameter passed to the function. If the buffer is too small to store the computer name, or if another error occurs, this function returns a value of zero. Use the return value from this function as well as the error out cluster from the Call Library Node to control the transition logic of the state machine.

Handle Errors CaseThis program has the potential to generate normal LabVIEW errors, such as a missing DLL file in a Call Library Function Node, as well as Windows API errors, such as an insufficient buffer size for the GetComputerName function to store the computer name. The handle errors case should handle both types of errors.

If a normal LabVIEW error occurs, you should ignore the DLL error handling code by using a case structure and simply pass the error to the General Error Handler VI. Use the General Error Handler instead of the Simple Error Handler to allow for custom messages generated by the Windows API error reporting calls.

Sample



In order to provide a meaningful error message for Windows API calls,you need to perform two steps. First, you must call the Windows API function GetLastError. This function returns a numeric value that represents any error encountered during the last function call, in thiscase, GetComputerName. In order to translate the numeric code into a meaningful message, you must call the FormatMessage Windows API function. You can use this function many different ways. Control the behavior of the function by setting one or more flags in a parametercalled dwFlags. In order to return a message for a system error, set the FORMAT_MESSAGE_FROM_SYSTEM flag. Also set the FORMAT_MESSAGE_IGNORE_INSERTS flag because you do not needto include any additional parameters in your message. Setting this parameter also allows you to ignore the arguments parameter of the function, thereby simplifying the function call. For more information on setting flags, refer to the Background: Windows API Reference section.

Tip All of the functions called in this exercise are in kernel32.dll. However, Windows API functions are found in many other DLLs. Refer to the Windows API Reference to determine in which DLL a given function is located.

Stop CaseThe stop case simply finishes the state machine, thereby ending the While Loop and the program.

Additional InformationThe following sections describe some issues particular to Windows API calls that you must address in order to implement a solution.

Background: Windows API ReferenceYou can find the Windows API definitions for each of the functions used in this exercise in the C:\Exercises\LabVIEW Intermediate II\Computer Name directory. Open each of the PDF files in this directory and browse the reference material in them. As you proceed through the exercise, refer to the references periodically to identify the meaning of each parameter you pass to the functions.

Note The function information in these PDF files is from the Windows API Reference in the MSDN library. You can access the full Windows API Reference at: http://msdn.microsoft.com/library/en-us/winprog/winprog/windows_api_reference.asp.

Sample



Bit Masked FlagsSome functions in the API contain a flags parameter that allows you to enable one or more options by masking the bits in an integer. The dwFlagsparameter of the FormatMessage function is an example of this technique.

In order to set a flag in LabVIEW, pass an integer constant with the appropriate size and value to the Call Library Function node. Remember that you can change the way a numeric constant is represented to makeit easier to enter the flag value. For example, the specification for the FormatMessage function gives the flags in hexadecimal format, you can set the format of your numeric constant to hexadecimal and then enter the value directly.

If you need to set multiple flags in a flags parameter, you can use aBitwise Or to combine multiple flags. In LabVIEW, the Or function is a polymorphic function which automatically becomes a Bitwise Or if you wire two integers to it.

Data TypesWindows API and other DLL function specifications often refer to many data types which have different names in LabVIEW. The following table lists LabVIEW types for some of the Windows data types used in this exercise. For a more complete list, the Call DLL example in the NI Example Finder provides a complete data type conversion list, as well as examples for each data type. The Windows Data Type reference is also a useful reference, it can be found at: http://msdn.microsoft.com/library/en-us/winprog/winprog/windows_data_types.asp.

Table 1-2. Data Type Conversion

Windows Data Type LabVIEW Data Type

LPTSTR String (Pass as C String Pointer)

DWORD U32

LPDWORD U32 (Pass by pointer)

BOOL I32

va_list* Varies (Use Adapt to Type)

LPCVOID Varies (Use Adapt to Type)

Sample



String TypesMany Windows API functions support two methods for representing strings. The first method is ASCII, in which each character in a string is represented by a single character. Traditional ASCII has a 128 character set, which contains all of the upper and lowercase letters, as well as other common symbols and a set of control characters. LabVIEW typically uses ASCII to represent strings.

The second method uses “wide” strings, which is another term for Unicode string representation (UTF-16 encoding). Unicode requires two bytes for each character, and allows for a much larger character set than traditional ASCII. Unicode is not natively supported in LabVIEW, but it is possible to use Unicode through add on libraries or calls to external functions.

Windows API functions which deal with strings often have two versions present in the DLL, marked with an “A” for ASCII and a “W” for wide. For example, there are two GetComputerName functions in kernel32.dll,GetComputerNameA and GetComputerNameW. In most cases, you should use the “A” version of the function in LabVIEW.

Implementation1. Create the front panel shown in Figure 1-1.

Figure 1-1. Computer Name Front Panel

❑ Create a blank VI and save the VI as Computer Name.vi in the C:\Exercises\LabVIEW Intermediate II\Computer Name directory.

❑ Create the Buffer Size control as described in Table 1-1.

❑ Create the Computer Name indicator as described in Table 1-1.

2. Create a type defined enumerated type control to control the state machine.

❑ Place an enum control on the front panel.

❑ Label the enum State Enum.

❑ Right-click the State Enum control and select Advanced»Customize from the shortcut menu to open the Control Editor.

Sample



❑ Right-click the control and select Edit Items from the shortcut menu.

❑ Enter the items as shown in Figure 1-2 and click the OK button.

Figure 1-2. State Enum Properties

❑ Select Type Def. from the Type Def. Status pull-down menu.

❑ Save the control as State Enum.ctl in the C:\Exercises\LabVIEW Intermediate II\Computer Name directory.

❑ Close the Control Editor and click Yes when prompted to replace the original with the customized control.

❑ From the block diagram, right-click the State Enum control and select Change to Constant from the shortcut menu.

❑ Set the value of the Computer Name constant to Get Computer Name.

Sample



3. Build a state machine to control the program as shown in Figure 1-3.

Figure 1-3. State Machine

❑ Place an Error In 3D control on the front panel.

❑ From the block diagram, right-click the error in (no error) controland select Change to Constant from the shortcut menu.

❑ Label the constant error in.

❑ Place a While Loop on the block diagram.

❑ Place a Case structure inside the While Loop.

❑ Wire the Computer Name constant to the case selector terminal through a shift register on the While Loop.

❑ Right-click the Case structure and select Add Case for Every Valuefrom the shortcut menu to add a case for every value in the Computer Name control.

❑ Wire the error in constant to the case structure through a shift register.

❑ Wire the Buffer Size control to the state machine as shown in Figure 1-3.

Sample



4. Call the GetComputerName function with the parameters shown in Table 1-3.

❑ Open the GetComputerName function reference from C:\Exercises\LabVIEW Intermediate II\Computer Name\getcomputername.pdf and identifythe prototype and parameters for the function.

❑ Place a Call Library Function Node in the Get Computer Name case of the Case structure.

❑ Double-click the Call Library Function Node to open the CallLibrary Function dialog box.

❑ Click the Browse button and navigate to C:\WINDOWS\system32\kernel32.dll.

❑ Select GetComputerNameA from the Function Name pull-down menu.

❑ Select Reentrant from the Thread section.

Note Because the Windows API functions are reentrant (multi-threaded), calling GetComputerName in UI thread functions correctly, except the error is not storedin the proper memory location for GetLastError to access it.

❑ Select stdcall (WINAPI) from the Calling Conventions section.

Table 1-3. GetComputerName Parameters

Parameter Name Type Format/Data type Other

return type Numeric Signed 32-bit Integer —

lpBuffer String C String Pointer Select lpnSize for Minimum size

lpnSize Numeric Unsigned 32-bit Integer

Select Pointer to Value for Pass

Sample



❑ Confirm that the Function tab settings match Figure 1-4.

Figure 1-4. GetComputerName Call Library Function

❑ Click the Parameters tab.

❑ Ensure the return type parameter is selected.

❑ Select Numeric from the Type pull-down menu in the Currentparameter section.

❑ Leave the Data type pull-down menu set to Signed 32-bit Integer.

❑ Click the Insert button to add a parameter after the return type parameter.

❑ Enter lpBuffer in the Name text box.

❑ Select String from the Type pull-down menu.

❑ Leave the String format pull-down menu set to C String Pointer.

Note You must declare an additional parameter before setting the minimum size for the lpBuffer parameter. Leave Minimum size blank.

❑ Click the Insert button to add a parameter.

Sample



❑ Enter lpnSize in the Name text box.

❑ Select Numeric from the Type pull-down menu.

❑ Select Unsigned 32-bit Integer from the Data type pull-down menu.

❑ Select Pointer to Value from the Pass pull-down menu.

❑ Select the lpBuffer parameter from the parameter list.

❑ Select lpnSize from the Minimum size pull-down menu.

❑ Confirm that the function prototype matches the following text.

long GetComputerNameA(CStr lpBuffer, unsigned long *lpnSize);

5. Create the Get Computer Name case as shown in Figure 1-5.

Figure 1-5. Get Computer Name Case

❑ Place an Equal To 0? function in the Case structure.

❑ Place an Unbundle by Name function in the Case structure.

❑ Place a Or function in the Case structure.

❑ Place a Select function in the Case structure.

❑ Place the Computer Name indicator inside the Case structure.

Sample



❑ Create two constants from the enum terminal on the right side of the Case structure. Set one value to Stop and the other to Handle Error.

❑ Place a False constant inside the Case structure.

❑ Wire the case as shown in Figure 1-5.

6. Create the Handle Error case as shown in Figure 1-6.

Figure 1-6. Handle Error Case

❑ Place a General Error Handler VI inside the Handle Error case.

❑ Create a constant from the enum terminal on the right side of the Case structure and set the value to Stop.

❑ Place a False constant inside the Handle Error case.

❑ Place a Case Structure inside the Handle Error case. Make the interior of the case structure large enough to include code but leave it blank.


7. Call the GetLastError function with the parameters shown in Table 1-4.

Table 1-4. GetLastError Parameters


return type Numeric Unsigned 32-bit Integer

—

Sample



8. Open the GetLastError function reference from C:\Exercises\LabVIEW Intermediate II\Computer Name\getlasterror.pdf and identify the prototype and parametersfor the function.

❑ Switch to the No Error case of the case structure within the Handle Error case of the state machine.

❑ Place a Call Library Function Node in the No Error case.



❑ Select GetLastError from the Function Name pull-down menu.






❑ Select Unsigned 32-bit Integer from the Type pull-down menu.


unsigned long GetLastError(void);

9. Call the FormatMessage function with the parameters shown in Table 1-5.

Table 1-5. FormatMessage Parameters


return type Numeric Unsigned 32-bit Integer

—

dwFlags Numeric Unsigned 32-bit Integer

Select Value for Pass

lpSource Adapt to Type Pointers to Handles —

Sample



10. Open the FormatMessage function reference from C:\Exercises\LabVIEW Intermediate II\Computer Name\formatmessage.pdf and identify the prototype and parametersfor the function.

❑ Place a Call Library Function Node in the No Error case.



❑ Select FormatMessageA from the Function Name pull-down menu.






❑ Select Unsigned 32-bit Integer from the Type pull-down menu.

❑ Click the Insert button to add a parameter.

❑ Enter dwFlags in the Name text box.

dwMessageId Numeric Unsigned 32-bit Integer


dwLanguageId Numeric Unsigned 32-bit Integer


lpBuffer String C String Pointer Select nSize for Minimum size

nSize Numeric Unsigned 32-bit Integer


Arguments Adapt to Type Pointers to Handles

Table 1-5. FormatMessage Parameters (Continued)


Sample





❑ Leave the Pass pull-down menu set to Value.

❑ Click the Insert button to add a parameter

❑ Enter lpSource in the Name text box.

❑ Select Adapt to Type from the Type pull-down menu.

❑ Select Pointers to Handles from the Data Format pull-down menu.


❑ Enter dwMessageId in the Name text box.





❑ Enter dwLanguageId in the Name text box.





❑ Enter lpBuffer in the Name text box.

❑ Select String from the Type pull-down menu.

❑ Leave the String format pull-down menu set to C String Pointer.

Note You must declare an additional parameter before setting the Minimum Size pull-down menu. Leave Minimum Size blank for now.

Sample




❑ Enter nSize in the Name text box.





❑ Enter Arguments in the Name text box.

❑ Select Adapt to Type from the Type pull-down menu.

❑ Select Pointers to Handles from the Data Format pull-down menu.

❑ Select the lpBuffer parameter from the parameter list.

❑ Select nSize from the Minimum size pull-down menu.


unsigned long FormatMessageA(unsigned long dwFlag, void *lpSource, unsigned long dwMessageId, unsigned long dwLanguageId, CStr lpBuffer, unsigned long nSize, void *Arguments);

Note The terminals corresponding to the arguments with type Void are blank until wired because void parameters accept any type of data.

Sample



11. Create the Handle Error case shown in Figure 1-7.

Figure 1-7. Handle Error Case

❑ Place a numeric constant with a representation of U32 in the Case structure. Label the constant String Size.

❑ Set the value of the String Size constant to 1000.

❑ Place a numeric constant with a representation of I32 in the Case structure. Label the constant Null Value.

❑ Place an Or function in the Case structure.

❑ Place a numeric constant with a representation of U32 in the Case structure.

❑ Right-click the numeric constant and select Format and Precisionfrom the shortcut menu.

Sample



❑ Configure the constant as shown in Figure 1-8.

Figure 1-8. Numeric Constant Properties

❑ Click the OK button.

❑ Set the value of the constant to 00000200.

❑ Label the constant Ignore Arguments.

❑ Create a copy of the Ignore Arguments constant.

❑ Change the label of the new constant to System Message.

❑ Set the value of the System Message constant to 00001000.

❑ Place a Error Cluster From Error Code VI in the Case structure.


Sample



12. Create the Stop case as shown in Figure 1-9.

Figure 1-9. Stop Case

❑ Select the Stop case of the Case structure.

❑ Create a constant from the enum tunnel on the right side of the Case structure and set the value to Stop.

❑ Create a constant from the stop tunnel on the right side of the Case structure and set the value to True.


13. Save the VI.

Testing1. Test the VI with an appropriate buffer size.

❑ Switch to the front panel of the VI.

❑ Run the VI with the default Buffer Size (256).

❑ The name of your computer should display in the Computer Nameindicator.

2. Verify that the correct computer name displays.

❑ Locate My Computer on the desktop of your computer or in Windows Explorer.

Sample



❑ Right-click My Computer and select Properties from the shortcut menu.

❑ Select the Computer Name tab and verify that the Full Computer Name matches the value the VI returns.

Note The case of the names does not need to match.

3. Test the error handling in the VI.

❑ Set the Buffer Size control to 1 and run the VI.

❑ Verify that the VI displays The file name is too long. as an error message.

Tip The error message that displays for this VI is the description for the Windows error message ERROR_BUFFER_OVERFLOW (System Error 111). Refer to http://msdn.microsoft.com/library/en-us/debug/base/system_error_codes.asp for more information about system error codes and their descriptions.

End of Exercise 1-1

Sample



Summary• Dynamic linking is a mechanism that links applications to libraries at

run time.

• The Call Library Function Node offers easy access to DLLs.

• To call a function in a DLL, you need to know the following:

– The calling convention used.

– The data type returned by the function.

– The parameters to be sent to the function, their types, and the order in which they must be passed.

– The location of the DLL on the computer.

– Whether the function can be called safely by multiple threads simultaneously.

Sample



Notes

Sample



Notes

Documents

LabVIEWTM Intermediate II Connectivity Course Manual · · 2007-10-02Sample Lesson 1 Calling Shared Libraries in LabVIEW LabVIEW Intermediate II Course Manual 1-2 ni.com A. Shared