XCALL

Call External Programs

This directive enables Thoroughbred Basic programs to directly interact with system and user-defined libraries through the Dynamic Link Library (DLL) interface. After the interface is set up and initialized Thoroughbred Basic programs can call library functions, pass data to these functions, and receive data from these functions.

Syntax

XCALL function-name [,ERR=line-ref|,ERC=error-code]
[, format-string, arg1 [, arg2] . . .]

function-name: is the name of the DLL function you plan to call. Valid values are the names of functions, but not the ordinal numbers associated with DLL functions.
line-ref: is the program line number or label to branch to if this directive produces an error.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.
format-string: specifies how Thoroughbred Basic will pass each of the following arguments to the called library function. You can use the following valid values:

D specifies that the argument will be passed by an OPEN VMS descriptor.

R specifies that the argument will be passed by reference.

V specifies that the argument will be passed by value.

You must specify one of these values for each argument. For more information on operating system requirements for passing arguments please refer to the Thoroughbred Basic Technical Appendices manual.

arg1, arg2, . . . are the Thoroughbred Basic variables that will be passed to the called library

function.

Remarks

This directive is available starting with Thoroughbred Basic 8.3.0.

Your operating system must support DLL calls:

Under UNIX systems this feature is usually implemented by the DLOPEN, DLCLOSE, and DLSYM library routines, which are available in UNIX 5.4 and OSF systems.
Under Microsoft Windows operating systems this feature is standard.
Under OPEN VMS operating systems this feature is available through the LIB$FIND_IMAGE_SYMBOL library interface.

You must create references to libraries you plan to call before you execute Thoroughbred Basic. To create the references, you must define the external symbol TBRED_EXTERNAL as a UNIX shell environment variable, a Microsoft Windows environment variable or as an OPEN VMS logical definition. The TBRED_EXTERNAL definition is a list of DLLs that Thoroughbred Basic can call through the XCALL directive. Your operating system may require additional definitions or symbols.

You can use option 3 of the TCB function to retrieve the return value from the function called by the XCALL directive. Returned values are 32 bits long. DFLOAT values will be truncated.

Under UNIX you can pass up to 4096 bytes to the function called by XCALL. Under OPEN VMS there is no upper limit to the number of bytes you can pass.

For now, XCALL only passes strings and signed integers. Strings can be any length but signed integers can only occupy up to 32 bits. If the passed number is too large Thoroughbred Basic will generate an error. To pass numbers that occupy more than 32 bits, or numbers that contain a decimal point, convert the number to a string. Make sure that the function called by XCALL expects such a number to be received as a string.

For more information on operating system requirements and how they affect your use of the XCALL directive please refer to the External Call (XCALL) Technical Specifications section of the Thoroughbred Basic Technical Appendices manual.

Examples

XCALL "mean_sqr_root", ERR=ERROR-ROUTINE, "R,R,R", A$, B, C

searches through the DLLs specified in TBRED_EXTERNAL for the “mean_sqr_root” function. If the libraries do not exist, or if the function does not exist in one of the libraries, ERROR-ROUTINE will execute and the ERR system variable will be set to 12.

If the libraries exist and the “mean_sqr_root” function exists the format-string “R,R,R” will be passed by value and the Thoroughbred Basic variables A$, B, and C will be passed by reference. If the “mean_sqr_root” function changes the values contained in these variables, the new values will be returned to your program.

XCALL

Syntax

Remarks

Examples

See also