|Homepage Products News Ordering Download Support Contact|
|To use subprograms defined in a DLL one must
make proper calls from HTBasic into the DLL. Also, it is necessary to have
access to and knowledge of the DLLs contents.
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:
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:
If dllname is specified, that DLL is taken out of memory and HTBasics 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 HTBasics 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.
that all return types must be all capital letters.
The syntax for the read and write commands are:
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. Its 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 HTBasics 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 HTBasics 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:
© Copyright 1997-2005 Tech Soft GmbH. All rights reserved. HTBasic is a trademark of TransEra Corporation.