The DLL file that the HTBasic program calls must be located in a directory where the operating system knows to look for DLLs. The two most common places for the DLL to reside are: the current directory (MSI) in which HTBasic is executing, and the windows\system or system32 directory.

It is necessary to know what is inside the DLL, particularly which labels have been exported and the calling protocol for subprograms and functions. Hopefully there will be some documentation for the DLL.

Here is some sample documentation. It lists the four labels that have been exported from SimpleDLLSample.dll, and their definitions. BasicMultiplier is a variable, BasicMult is a function, MultValue and SeeMultiplier are subprograms. This also lists the needed parameters for each function and subprogram, and gives a brief explanation of what each one does.

The HTBasic commands for using a DLL are:

DLL LOAD
DLL UNLOAD
DLL GET
DLL READ
DLL WRITE

There is also the LIST DLL command that will show a list of all the DLLs currently loaded.

The syntax for the load command is:

DLL LOAD “dllname”

where dllname is the name of the DLL to load. Note that the extension .dll should not be added to on the end of dllname. Again make sure that the DLL file is located in a directory where the operating system knows to look for DLLs.

The syntax for the unload command is:

DLL UNLOAD “dllname”
DLL UNLOAD ALL

If dllname is specified, that DLL is taken out of memory and HTBasic’s access to it is lost. If ALL is specified, all DLLs are removed from memory.

The syntax for the get command is:

DLL GET “returntype dllname:label” AS “alias”

The AS “alias” part is optional if the label in the DLL conforms to HTBasic’s case sensitive naming convention.

dllname is the name of the DLL that was loaded by the DLL LOAD command

label is one of the labels exported by the DLL. This is case sensitive; the label must be specified exactly as it is defined in the DLL.

Valid returntypes are:

VARIABLE - This means that this label is not a function or a subprogram. It is a variable that can be used with the DLL READ or DLL WRITE commands. It is up to the programmer to make sure that the size of the variable as it is used in HTBasic is the same size as the variable as it is used in the DLL.

VOID - This means that this label is a subprogram. No return value is expected. It is up to the programmer to know the number and sizes of the parameters expected by this subprogram.

SHORT - This means that this label is a function that returns a 16-bit integer. This corresponds to an INTEGER variable in HTBasic.

LONG - This means that this label is a function that returns a 32-bit integer. This corresponds to a LONG variable in HTBasic.

DOUBLE - This means that this label is a function that returns an 8-byte floating point number. This corresponds to a REAL variable in HTBasic.

CHAR - This means that this label is a function that returns a single ASCII character. This corresponds to a single letter in a string in HTBasic.

CHARPTR - This means that this label is a function that returns an array of characters. This corresponds to a string variable in HTBasic.

Remember that when calling a function, you must put an “FN” at the beginning of the function name. Also, when calling a string function (CHAR or CHARPTR) a “$” must be added at the end of the function name.

Note that all return types must be all capital letters.

The syntax for the read and write commands are:

DLL READ “varname”;basicvariable
DLL WRITE “varname”;basicvariable
DLL WRITE “varname”;value

varname is the name of the variable or alias specified in the DLL GET command, and basicvariable is the name of another variable declared in basic.

Make sure that the variables specified by varname and basicvariable are the same size or memory could get corrupted.

value is a numeric value that can properly fit into the specified value.

To make sure that variables are the same size, here is a comparison between HTBasic and standard C/C++ variable types.

Use caution when using variables declared as int in C/C++. Depending on the compiler being used and its settings, int can be either 2 bytes or 4 bytes. It’s safer to specify short or long in the DLL.

Once the DLL has been created and some of its workings are understood, we are ready to use it in an HTBasic program.

Some commentary about this sample program:

Line 20 - IF NOT INMEM will be true if DLL “SimpleDLLSample” is not currently loaded. This is a good way to ensure that a loaded DLL is not loaded again.

Line 30 - Loads the DLL “SimpleDLLSample.dll” into HTBasic’s memory.

Line 50 - This gets access to the variable “BasicMultiplier” located in the DLL “SimpleDLLSample”. It designates that in HTBasic, that variable is referred to as “Bmultvar”. Note that it does not specify the type or the size of the variable. From the documentation that came with the DLL, it can be determined that it is a long integer. It will have to be treated as such.

Line 60 - This gets access to the function “BasicMult” located in the DLL “SimpleDLLSample”. It specifies that this function returns a long integer and that HTBasic will refer to it as “Multfunc”. Note that it does not specify the type, size, or number of parameters for this function. This information can be determined from the documentation for the DLL. In this case the documentation indicates this function takes one long integer as a parameter.

Line 70 - These lines get access to the subprograms “MultValue”

Line 80 - and “SeeMultiplier” located in the DLL “SimpleDLLSample”. They specify that HTBasic will refer to them as “Multval” and “Seemult”. As with the function, the information about their parameters has to be obtained from the documentation. In these cases, “MultValue” takes the address of a long integer as its parameter, and “SeeMultiplier” takes the address of a string as its.

Line 120 - Declares some normal variables for working with the

Line 150 - sample program. The documentation for “SeeMultiplier” indicates any string passed to it must be big enough to hold 26 letters, plus the number of digits in “BasicMultiplier”. One extra character space for the DLL to append a NULL must also be reserved. If it is assumed that “BasicMultiplier” will never be more than 5 digits long, the string must be dimensioned 26+5+1 characters long.

Line 170 - Read a value from the DLL variable “Bmultvar” and assign it into the HTBasic variable “Mbase”. Since “Mbase” is declared as a LONG INTEGER, the DLL READ command will read enough memory (4 bytes) to fill a LONG INTEGER. From line 50, it is known that “Bmultvar” is HTBasic’s name for the variable “BasicMultiplier” in the DLL “SimpleDLLSample”. The documentation indicates that “BasicMultiplier” has been declared as a long (also 4 bytes), so the variable sizes are the same, so this is a safe read.

Line 200 - This writes a value of 3 into the variable “Bmultvar” which is really the variable “BasicMultiplier” in the DLL “SimpleDLLSample”. Actually this action is not quite as safe as the previous read. Since 3 is less than 32767 and greater than –32768, HTBasic treats it as a regular INTEGER which is only two bytes. Since we are writing into a variable that is 4 bytes, we can get away with it, but be aware that this could cause problems if you are not careful. It is actually preferable to put the value into a variable of the right size and use it instead of the numerical constant.

Line 230 - This is a call into the function “Multfunc” which puts the return value into the HTBasic variable “Work2”. “Multfunc” is really the function “BasicMult” located in the DLL “SimpleDLLSample”. According to the GET command in line 60 this function returns a LONG. “Work2” is declared as a LONG INTEGER so this is correct.

Since this is a function call, HTBasic requires an “FN” at the beginning of the function name. If this function returned a string, it would also require a “$” at the end of the function name.

By default, HTBasic passes the address of a variable as a parameter, but according to the documentation, the function “BasicMult” is expecting a long value, not an address. The extra set of parenthesis around the parameter “Work1” tell HTBasic to pass the value contained in the variable, rather than the address of the variable.

Line 280 - Writes the value in the variable “Mbase” into the variable “Bmultvar”, which is really the variable “BasicMultiplier” in the DLL “SimpleDLLSample”. Unlike the write in line 200, this will correctly write 4 bytes into the variable since “Mbase” was declared as a LONG INTEGER.

Line 300 - This is a call to the subprogram “Multval” which is really “MultValue” in the DLL “SimpleDLLSample”. Note that the documentation states that this subprogram is expecting the address of a long, not the value of a long. By default HTBasic passes addresses instead of values. The parameter can just be listed in the normal way, unlike the call in line 230 which required an extra set of parenthesis.

Line 360 - This is a call to the subprogram “Seemult” which is really “SeeMultiplier” in the DLL “SimpleDLLSample”. This subprogram takes the address of a string as its parameter. Since this subprogram actually writes into the string which it receives, make sure that the string was dimensioned large enough to handle the longest string that the subprogram will write. In line 150 it was dimensioned as 32 bytes, which should be large enough for our subprogram.

Line 390 - This unloads the DLL from memory. If the DLL will no longer be needed, it is good programming practice to unload it. If the functions and subprograms from the DLL will be needed again soon, it is more efficient to leave it in memory.

The output of the sample program should look like this:

Problem Report | Tutorials | DLL Toolkit | Downloads | Faq