Using LINKNLOAD to Call External Programs

Application Developer Guide > Interapplication Communication for Windows > Using LINKNLOAD to Call External Programs

The LINKNLOAD function provides simplified access to external routines in Dynamic Link Libraries (DLLs). LINKNLOAD calls a function in a DLL and returns a scalar value. Parameters are passed through PV-WAVE to the specified external function by reference, thus allowing the external function to alter values of PV-WAVE variables. It is the simplest method for attaching your own C code to PV-WAVE.

Usage

result = LINKNLOAD(object, symbol[, param1, ..., paramn])

Parameters

object—A string specifying the filename, optionally including file path, of the DLL to be linked and loaded.

symbol—A string specifying the function name (symbol entry point) to be invoked in the DLL file.

parami—The data to be passed as a parameter to the function.

For more information on the LINKNLOAD parameters and optional keywords see the discussion of LINKNLOAD in the PV‑WAVE Reference.

Discussion

LINKNLOAD lets you call a C function (or a FORTRAN function) from PV‑WAVE almost as if you were calling a PV‑WAVE function. The called function can obtain information from PV‑WAVE through passed parameters or by accessing PV‑WAVE’s variables directly (see "Accessing Data in PV‑WAVE Variables").

Any simple PV‑WAVE data type can be passed as a parameter to a C or FORTRAN routine. By default, parameters are passed by reference (not by value), and thus it is up to the programmer whether or not the C or FORTRAN function alters the parameter’s value. Use the Value keyword to pass parameters by value. Parameters are passed in the traditional C fashion of argc and argv. The C function must know the type to expect for each parameter and must cast it to a C variable of the correct type.

For FORTRAN, since the parameters are passed as pointers, functions are provided to access their values. These functions are:

WLNL_GETBYTE

WLNL_GETSHORT

WLNL_GETINT32

WLNL_GETLONG

WLNL_GETFLOAT

WLNL_GETDOUBLE

WLNL_GETCOMPLEX

WLNL_GETSTRING

WLNL_GETBYTE_ARRAY

WLNL_GETSHORT_ARRAY

WLNL_GETINT32_ARRAY

WLNL_GETLONG_ARRAY

WLNL_GETFLOAT_ARRAY

WLNL_GETDOUBLE_ARRAY

WLNL_GETCOMPLEX_ARRAY

WLNL_GETSTRING_ARRAY

For detailed information on these functions, see the file:

(WIN) %WAVE_DIR%\util\variables\README

note

Make sure the number, type, and dimension of the parameters passed to the external function match what the external function expects (this can most easily be done from within PV‑WAVE before calling LINKNLOAD). Furthermore, the length of string parameters must not be altered and multi-dimensional arrays are flattened to one-dimensional arrays.

Because PV-WAVE LONG variables use 8 bytes on 64-bit platforms, passing them between PV-WAVE, C, and FORTRAN applications requires the use of the OPI_long and INTEGER*8 data types, respectively.

Note that with LINKNLOAD, pointers are used to get the value of a variable. For example:

B = WLNL_GETBYTE(VAL(ARGP(1)))

Here, the value of ARGP represents a pointer, which is the same size as a long integer. Thus, ARGP needs to be declared as an INTEGER*8 variable.

Accessing the Data in PV‑WAVE Variables

The wavevars function can be used to access the results generated by PV-WAVE in a user-written application called with LINKNLOAD. wavevars is a C function that can be invoked from code that is dynamically linked to PV-WAVE to obtain data from PV-WAVE’s data variable space.

The wavevars calling sequence is:

result = wavevars(&argc, &argv, &argp);

For detailed information on wavevars, see "Accessing Data in PV‑WAVE Variables".

note	See also the section "Using the Option Programming Interface". The Option Programming Interface (OPI) functions allow user-written C code to access PV‑WAVE variables and use other PV‑WAVE functionality. OPI provides greater flexibility and control than wavevars.

Example 1: Calling a C Program

The C code referred to in this example can be found online. You can print the program or view it using a text editor. The example is in the file:

%WAVE_DIR%\demo\interapp\win32\linknload\example.c

In this example, parameters are passed using the conventional argc, argv strategy. argc indicates the number of data pointers which are passed from PV-WAVE within the array of pointers called argv. The pointers in argv can be cast to the desired type as the example program demonstrates.

Building the DLL File

The makefile (called makefile) creates the DLL file used by LINKNLOAD to link the C function to PV-WAVE at runtime. This makefile is in the same directory as the source file example.c. In a Command Prompt window, enter the following command to build the DLL:

nmake

note	You must have a supported Windows C compiler on your system for this makefile to execute properly.

Accessing the External Function with LINKNLOAD

The following PV-WAVE code demonstrates how the C function defined in this example could be invoked.

ln = LINKNLOAD('example.dll', 'WaveParams', BYTE(1), 2, 23i, $
LONG(3), FLOAT(4), DOUBLE(5), COMPLEX(6,7), 'eight')

The resulting output is:

1 2 23 3 4.000000 5.000000 <6.000000,7.000000i> 'eight'

Using the INFO command, you can see that LINKNLOAD returns the scalar value 1.

INFO, ln LN     LONG     =     1

The example program works with both scalars and arrays since the actual C program above only looks at the first element in the array and since PV‑WAVE collapses multi-dimensional arrays to one-dimensional arrays:

ln = LINKNLOAD('example.dll', 'WaveParams', [BYTE(1)], $
[[2,3],[4,5]], [[22i,33],[44,55]], [LONG(3)],  [FLOAT(4)], $
[DOUBLE(5)], [COMPLEX(6,7)], ['eight'])

The resulting output is:

 1 2 22 3 4.000000 5.000000 <6.000000,7.000000i> 'eight'

Example 2: Calling a FORTRAN Program

In this example, parameters are passed from PV‑WAVE to the FORTRAN external function. Variables from PV‑WAVE are passed as pointers to the FORTRAN function. In the FORTRAN function, the WLNL_GET* functions are used to retrieve the values of the variables. See "Discussion" for more information on these functions.

note	The example Visual Studio projects/solutions supplied were created using Visual Studio 2005 and the Intel FORTRAN compiler version 11.1. Both are required to build the FORTRAN examples.

You can find the following listed file in:

%WAVE_DIR%\demo\interapp\win32\linknload\examplefor.f

INTEGER*4 FUNCTION WAVEPARAMS(ARGC, ARGP)

INTEGER*4 ARGC, ARGP(*)

BYTE                     B

INTEGER*2                S

INTEGER*4                I

INTEGER*4                L

REAL*4                   F

DOUBLE PRECISION         D

STRUCTURE /CMPLX/
REAL R,I

END STRUCTURE

RECORD /CMPLX/	 C

INTEGER*4                RET

CHARACTER*80             STR

INTEGER*4                NCHAR

INTEGER*4            WLNL_GETLONG

INTEGER*4            WLNL_GETINT32

INTEGER*4         WLNL_GETSTRING

INTEGER*4         WLNL_GETCOMPLEX

INTEGER*2            WLNL_GETSHORT

BYTE                 WLNL_GETBYTE

REAL                 WLNL_GETFLOAT

DOUBLE PRECISION     WLNL_GETDOUBLE

IF (LOC(ARGC) .NE. 8) THEN
PRINT *,'Wrong # of parameters',LOC(ARGC)
WAVEPARAMS = 0
RETURN

ENDIF

B   = WLNL_GETBYTE(%VAL(ARGP(1)))

S   = WLNL_GETSHORT(%VAL(ARGP(2)))

I   = WLNL_GETINT32(%VAL(ARGP(3)))

L   = WLNL_GETLONG(%VAL(ARGP(4)))

F   = WLNL_GETFLOAT(%VAL(ARGP(5)))

D   = WLNL_GETDOUBLE(%VAL(ARGP(6)))

RET = WLNL_GETCOMPLEX(%VAL(ARGP(7)),C.R,C.I)

NCHAR = WLNL_GETSTRING(%VAL(ARGP(8)),STR,%VAL(80))

     PRINT 100,B,S,I,L,F

100  FORMAT(' BYTE=',I3,',SHORT=',I6,',INT32=',I8,',LONG=',I8,

     +           ',REAL=',F10.5)

     PRINT 200,D,C.R,C.I

200  FORMAT(' DOUBLE=',D15.5,',COMPLEX=[',F10.5,',',F10.5,']')

     PRINT 300,STR,NCHAR

300    FORMAT(' STRING=',A80,',NCHAR=',I6)

WAVEPARAMS = 1

RETURN

END

Compiling the Example FORTRAN Routine

Instructions for building and running this example are in the file:

%WAVE_DIR%\demo\interapp\win32\linknload\README

Accessing the External Function with LINKNLOAD

The following PV‑WAVE code demonstrates how the FORTRAN function defined in this example could be invoked. This code is located in the file:

%WAVE_DIR%\demo\interapp\win32\linknload\examplefor.pro'

ln = LINKNLOAD('examplefor.dll','waveparams', BYTE(1), 2, $
23i, LONG(3), FLOAT(4), DOUBLE(5), COMPLEX(6,7), 'eight')

The resulting output is:

BYTE=  1,SHORT=     2,INT32=      23,LONG=       3,REAL= 4.00000

 DOUBLE=    0.50000D+01,COMPLEX=[   6.00000,   7.00000]

 STRING=eight  ,NCHAR=     5

Using the INFO command, you can see that LINKNLOAD returns the scalar value 12345 as expected.

INFO, ln

; PV-WAVE prints: LN     LONG     =     12345

The example program works with both scalars and arrays since the actual FORTRAN program above only looks at the first element in the array and since PV‑WAVE collapses multi-dimensional arrays to one-dimensional arrays:

ln = LINKNLOAD('examplefor.dll','waveparams', [BYTE(1)], $
[[2,3],[4,5]], [[2i,3],[4,5]],  [LONG(3)], [FLOAT(4)], $
[DOUBLE(5)], [COMPLEX(6,7)], ['eight'])

The resulting output is:

BYTE=  1,SHORT=     2,INT32=       2,LONG=       3,REAL= 4.00000

 DOUBLE=    0.50000D+01,COMPLEX=[   6.00000,   7.00000]

 STRING=eight  ,NCHAR=     5

Example 3

In this example, the PV‑WAVE program calls a C wrapper function, passing it PV‑WAVE variables as parameters. The C wrapper calls the FORTRAN function, passing along the same parameters. The FORTRAN function modifies the values of the PV‑WAVE variables it receives as parameters. The FORTRAN function then returns control to PV‑WAVE, passing to PV‑WAVE the result of the function. The new values, assigned to the PV‑WAVE variables by the FORTRAN program, are accessible within PV‑WAVE upon return from the FORTRAN program.

This example contains three programs:

wave_to_fort_main.pro—A PV‑WAVE main program that uses LINKNLOAD to call a FORTRAN function. The PV‑WAVE program passes parameters to a C wrapper, which in turn calls the desired FORTRAN function to modify the PV‑WAVE parameters. When control is returned to PV‑WAVE, the values of the PV‑WAVE variables which were passed as parameters are changed.

wave_to_fort_w.c—A C function that is called by PV‑WAVE, via LINKNLOAD. This routine is a C wrapper that allows a PV‑WAVE program to pass parameters to and invoke a FORTRAN function. The FORTRAN function can modify the values of the PV‑WAVE variables passed as parameters and the modified values will be accurately reflected upon return to PV‑WAVE.

fort_from_wave.f—The FORTRAN function to be called by the C wrapper.

The C and PV-WAVE code used for this example can be found in the directory

%WAVE_DIR%\demo\interapp\win32\linknload

Compiling and Linking the Programs

Instructions for building and running this example are in the file:

%WAVE_DIR%\demo\interapp\win32\linknload\README

Version 2017.1