Creating C Language Functions in IC-CAP

Manuals >User's Guide >Using Transforms and Functions
Print version of this Book (PDF file)

Creating C Language Functions in IC-CAP

You can create custom mathematical and other functions in the C language to augment the capabilities of the existing executable code. User-written functions appear in IC-CAP's Function List. The files associated with this customization capability reside in the $ICCAP_ROOT/src directory.

You can add functions to a source file named userc.c, then re-link and re-run IC-CAP. A Makefile and other necessary provisions exist in $ICCAP_ROOT/src. Functions written in C must be consistent with the examples in userc.c. The file userc.c in $ICCAP_ROOT/src includes several working examples of C functions added to IC-CAP by users. The examples demonstrate how to receive data sets and other arguments and how to return results.

To add a new function to the IC-CAP system:

1 Change to the $ICCAP_ROOT/src directory.

  2 Using functions declared in xf_util.c.h, add the new function to add_users_c_funcs() in userc.c with an appropriate call. For example:

     • Use add_double_c_func1.

     • Use one of the 3 function calls (add_input_name, add_variable_name, and add_parameter_name) to establish the labels that appear in the editor of any transform that uses the new function. These functions are declared in xf_util.c.h and are described in Declarations and Implementation Examples. (Consult declarations in userc.h, where various types are declared.)

To compile the file containing the new function:

1 Create a work directory for the source files (for example, mkdir my_source, and change it to (cd my_source).

2 Copy the set of source files from $ICCAP_ROOT/src to the new work directory (cp $ICCAP_ROOT/src/* . ).

3 Use the touch command on the *.o files so that all *.c and *.o files appear to have been created at the same time (touch *.o). (This step is important for the make procedure.)

Note


		If the drive you're copying to is NFS mounted, clock skews can result if the NFS drive's system has a slightly different system time than the local system. If you think this might apply to you, first, execute touch * then execute touch *.o. The first touch synchronizes all files to your local system's time; the following touch causes the make system to believe that all of the .o files were generated later than the source files, so it will not attempt to rebuild any unnecessary files.

4 Copy your source code to the working directory. Modify the function add_users_c_funcs() in userc.c to add your C functions to IC-CAP's list of functions, and/or modify the function add_users_drivers() in user_meas.cxx to add your drivers to IC-CAP's library of instrument drivers. Modify the Makefile to add your source code modules to the list of objects.

5 Issue the make command and debug any compiler errors.

6 Set the environment variable ICCAP_OPEN_DIR to point to the directory containing the libicuserc.<ext> or libicusercxx.<ext> file where ext is a platform-specific file extension (ext is .so on Solaris).

Alternately, if you want to use the new files site wide, you can replace the original files (after copying to another name to preserve them) under $ICCAP_ROOT/lib/<platform>, where <platform> is sun2x on SUN Solaris 2.X.

7 Start IC-CAP as usual.

For more information about generating shared libraries for new functions, see "Creating a New Shared Library" in the Reference.

To test the function:

1 Confirm that the new function appears in the Function List.

If the new function does not appear in the Function List, check to be sure that an appropriate call was made inside add_user_c_funcs(). The system calls add_user_c_funcs() once at startup time to add user-written C functions to IC-CAP's Function List.

2 Create a transform that uses the new function.

3 If you specified input labels for transforms that use the function, verify that the transform editor associated with the new function displays the expected labels.