Calling Procedures Written in Other Languages

Sheerpower can call procedures written in other programming languages as long as they are contained in a DLL as a global routine. An example of this is calling routines in the Microsoft provided msvcrt.dll library. The call statement is used to call and execute library routines. These routines can perform procedures so the developer does not have to write the code from scratch.

Note: When calling a routine, you must enclose its name in quotes. For example: "strlen"(). This ensures the routine's upper and lower case formatting is preserved.

The library to which the routine belongs must have been specified in a library statement.

Routines within a DLL are called using the call statement, followed by a quoted string which contains the name of the routine to be called:
Some routines take arguments. An integer variable (count%) is passed by its value. A string is passed by reference (a pointer to its text). Every other number is a REAL, and a REAL reaches the routine as a C double: by reference by default — a pointer to a double holding the value, and whatever the routine writes there comes back into the variable — or, written by value, the double itself (see the example below). A C int parameter takes an integer variable: 34 written plainly is a REAL. To pass an integer by reference (the pointer to it, so the routine can write into it), use the by ref option:

library 'msvcrt.dll' code% = 34 call '_set_errno' (code%) // an integer variable goes by its value err_code% = 0 call '_get_errno' (err_code% by ref) // by ref: the routine writes into err_code% print err_code% // 34

An array cannot be passed to a DLL routine. An array name, array name, name() and an array element such as codes%(2) are all compile-time errors. To hand a routine one element, copy it into a variable of the same type, pass the variable, and copy it back if the routine writes to it:

library 'msvcrt.dll' dim stamps%(3) one% = stamps%(2) // copy the element into a variable of its type call '_time32' (one% by ref) // _time32 writes the time there, and returns it too stamps%(2) = one% // copy it back print stamps%(2) = _integer // 1 -- the value it wrote is the value it returned

When a routine is called, it may also return a value. The variable _integer will hold this value if the routine returns an integer. If the routine returns a pointer to a null-terminated character string (char*), you can call the routine with the prefix char*. After the routine completes, _string$ will contain a copy of the returned string.

For example:

myvar% = 45 call "char* my_routine" (myvar% by ref) print 'Returned string was: '; _string$

This demonstrates how _string$ automatically holds the returned string when the routine is called with the char* prefix.

A routine that returns a double is called with the prefix double in the same way: afterwards _real holds the result, to the 15 significant digits a double carries. C's math routines take their doubles by value, so those REALs are written by value; a routine that writes a double through a pointer (a double * parameter) gets a REAL passed the default way:

library 'msvcrt.dll' x = 2 call 'double sqrt' (x by value) // a double in, a double out print _real // 1.4142135623731 base = 2 power = 10 call 'double pow' (base by value, power by value) print _real // 1024 call 'sscanf' ('3.25', '%lf', z by ref) // %lf writes a double through the pointer print z // 3.25

CSTRING$ is the other way to the same text: after a call made WITHOUT the char* prefix, _integer holds the returned pointer as a number, and cstring$ (no arguments) returns the null-terminated string at that address. Use it when you want the address as well as the text, or decided on the prefix too late. A null pointer (0) gives an empty string; a value that is not the address of readable memory -- _integer after strlen, say -- raises the catchable exception Bad CHAR* pointer (4011) rather than reading garbage.

library 'msvcrt.dll' call 'getenv' ('SystemRoot') print 'the address: '; _integer > 0; ' the text: '; cstring$ call 'char* getenv' ('SystemRoot') print 'the same through the prefix: '; _string$ // the address: 1 the text: C:\WINDOWS // the same through the prefix: C:\WINDOWS

The examples below use the Microsoft-provided msvcrt.dll library and calls the strlen and _getcwd functions/routines.

library 'msvcrt.dll' text$ = 'Hello there!' call 'strlen' (text$) print 'The length of text$ is: '; _integer call 'char* _getcwd'() print 'The current working directory is: '; _string$

While Sheerpower prevents common failure modes such as stack overflows and memory corruption within your business logic, DLL routines execute as native code and can still fail or crash if implemented incorrectly. Use only well-tested system libraries (like msvcrt.dll) or thoroughly validated custom DLLs.

(Show/Hide Sheerpower External Calls Takeaways)

Calling Procedures Written in Other Languages

Sheerpower External Calls Takeaways

Enter or modify the code below, and then click on RUN