Provides simplified accessto external routines in shareable images and Dynamic Link Libraries (DLLs).
A string specifying the filename, optionally including file path, of the DLL or shared object file to be linked and loaded. symbol
A string specifying the function name symbol entry point to be invoked in the DLL or shared object file. parami
(optional) The data to be passed as a parameter to the function. Any data type except structure can be used.
A scalar whose default is assumed to be of type longword unless it is specified with one of the keywords described below.
(VMS only) Changes the default object file specification. On VMS, there are two ways to specify the object parameter. It may be a logical name (defined in the system logical table with the /EXEC attribute) including the full path to the file. Or the object parameter may be a filename, without any directory or extension. In the latter case, the default file specification of SYS$SHARE:.EXE is applied to the object file name. You may use the Default keyword to change this. For example:
result = LINKNLOAD('EXAMPLE', $
Default = 'SYS$LOGIN:[LIBS].EXE', symbol, ...)
Specifies that the returned scalar is of type double-precision floating point. F_Value
Specifies that the returned scalar is of type single-precision floating point. Nocall
(UNIX, Windows only) If present and nonzero, LINKNLOAD will not call the function defined by the object and symbol parameters. LINKNLOAD will still try to find the object module and load it. Thus, you can use this keyword to do just the loading of the object module. If used with Unload, the object module is unloaded without calling the function. This is useful because you can recompile the object module, unload the old object module, and reload the new one without exiting the PV-WAVE session.S_Value
Specifies that the returned scalar is of type string.Unload
(UNIX, Windows only) If present and nonzero, LINKNLOAD unloads the object module immediately before returning from the LINKNLOAD command.Value
(byte array) Allows you to specify which parameters should be passed by value, instead of by reference, which is the default. Value must be a byte array with one element for each parameter in the call. A parameter is passed by value if the corresponding byte in the Value array is non-zero. Array parameters must always be passed by reference.Verbose
(UNIX, Windows only) If present and nonzero, LINKNLOAD prints status information when an object module is being loaded or unloaded.Vmscall
When present and nonzero, tells PV-WAVE to use the LIB$CALLG system routine to call the object. This makes parameter passing significantly more convenient for FORTRAN programmers working in an OpenVMS environment. This keyword is ignored on UNIX platforms.Vmsstrdesc
When present and nonzero, tells PV-WAVE to pass string parameters as OpenVMS FORTRAN string descriptors. This keyword is ignored on UNIX platforms.
NOTE: In general, LINKNLOAD cannot know what language an object module being called was created from. The Vmsstrdesc keyword tells LINKNLOAD that your object module was created from FORTRAN code and that it is expecting string descriptors.
For more information on the keywords Unload, Nocall, and Verbose, refer to the following file:
$VNI_DIR/wave/demo/interapp/linknload/ lnl_newkeywords.doc
VNI_DIR:[WAVE.DEMO.INTERAPP.LINKNLOAD] LNL_NEWKEYWORDS.DOC
Windows Users: 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.
UNIX and OpenVMS Users: LINKNLOAD calls a function in an external sharable object and returns a scalar value. It is the simplest method for attaching your own C code to PV-WAVE.
CAUTION: Be careful to ensure that the number, type, and dimension of the parameters passed to the external function match what it 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.
One of these methods is to use the
wavevars function and the other is to use the C-callable or FORTRAN-callable programming interface.
.
NOTE: For for detailed information on these methods, see the PV-WAVE GUI Application Developer's Guide
UNIX Users: For AIX, the symbol entry point must be specified when the external shareable object is built, by using the -e flag, and thus the function symbol parameter to LINKNLOAD has no effect on AIX.
Variables that are shared between PV-WAVE and a C function must be created by PV-WAVE and their size can not be modified by the C function.
It is possible to pass a constant as a parameter to a C function from PV-WAVE via LINKNLOAD, but of course the C function can not pass a value back via that parameter.
Although wavevars returns pointers to the data associated with PV-WAVE's variables, it should be kept in mind that these addresses must be treated as "snapshots" because the data pointer associated with a particular PV-WAVE variable may change after execution of certain PV-WAVE system commands.
Using LINKNLOAD, care must be taken to ensure that the number, type, and dimension of the parameters passed to the function match what the 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.
In this example, parameters are passed to the C external function using the conventional (argc, argv) UNIX 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 following program demonstrates.
$WAVE_DIR/util/linknload/example.c#includestdio.h
typedef struct complex { float r, i; } complex; long WaveParams(argc,argv) int argc; char *argv[]; { char *b; short *s; long *l; float *f; double *d; complex *c; char **str; if (argc != 7) { fprintf(stderr,"wrong # of parameters\n"); return(0); } b = ((char **)argv)[0]; s = ((short **)argv)[1]; l = ((long **)argv)[2]; f = ((float **)argv)[3]; d = ((double **)argv)[4]; c = ((complex **)argv)[5]; str = ((char ***)argv)[6]; fprintf(stderr,"%d %d %ld %g %g
ln = LINKNLOAD('example.so','WaveParams', $
byte(1),2,long(3), float(4),double(5), $
complex(6,7),'eight')
1 2 3 4 5
INFO, ln
LN LONG = 12345
ln = LINKNLOAD('example.so','WaveParams', $
[byte(1)],[[2,3],[4,5]], [long(3)], $
[float(4)],[double(5)],[complex(6,7)], $
['eight'])
1 2 3 4 5
wavedir\demo\interapp\win32\linknloadwavedir is the main PV-WAVE directory.This directory contains an example C program, a PV-WAVE procedure file, a makefile, and a README file. See the README file for details on running the example.
For more information on the example and on LINKNLOAD, see the PV-WAVE GUI Application Developer's Guide.
wavedir\demo\interapp\win32\linknload\call*wavedir is the main PV-WAVE directory.
