Chapter 1 CIN Overview

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 determine 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.

3. Wire the Inputs and Outputs to the CIN

Connect wires to all the terminal pairs on the CIN to specify the data that you want to pass to the CIN, and the data that 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 that 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.

4. 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 pass to the CIN.

Chapter 1 CIN Overview

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. It specifies seven routines (initially empty of any code) that must be written for the CIN. The UseDefault macros are the default for six of the seven routines, but because the CINRun routine is the most commonly used, it gets an actual function structure into which you can enter code. The six macros are actually #defines in extcode.h, which expand into empty routines; the CINRun routine is provided for you.

These seven 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.

Chapter 1 CIN Overview

/*

* CIN source file */

#include "extcode.h"

/* stubs for advanced CIN functions */

UseDefaultCINInit

UseDefaultCINDispose

UseDefaultCINAbort

UseDefaultCINLoad

UseDefaultCINUnload

UseDefaultCINSave

CIN MgErr CINRun(int32 *num_in, int32 *num_out);

CIN MgErr CINRun(int32 *num_in, int32 *num_out) {

/* ENTER YOUR CODE HERE */

return noErr;

}

This .c file is a template in which you must write C code. Notice that 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.

You should always use #include "extcode.h" at the beginning of your source code. If your code needs to make system calls, you should also use #include "hosttype.h" immediately after #include "extcode.h", and then include your system header files. You should know that 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.

Chapter 1 CIN Overview

The other routines (CINLoad, CINSave, CINUnload, CINAbort,

CINInit, and CINDispose) 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, first remove the UseDefaultCINLoad macro, and then write your CINLoad routine as follows:

CIN MgErr CINLoad(RsrcFile reserved) {

Unused (reserved)

/* your code goes here */

return noErr;

}

In general, you only need to write the CINRun routine. The other routines are mainly supplied for those instances in which 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-generated .c file to multiply a number by two. This code is included for illustrative purposes. Chapter 2, CIN Parameter Passing, discusses in depth 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;

}

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 that the global context register (A5 for MPW builds, A4 for Symantec/THINK and Metrowerks builds) for your CIN is established during your function, and that 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.

Chapter 1 CIN Overview

You need not use these macros in any of the seven predefined entry points (CINRun, CINLoad, CINUnload, CINSave, CINInit,

CINDispose, CINAbort), 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 address of one of your functions to some other piece of code that may call your function later. An example of this would be in the use of the QSort routine in the LabVIEW support manager (described in the Online Reference or online manual). 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;

}

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.