Older Version
Newer Version
Alyce
Mar 28, 2007
- "First draft"
The ABCs of APIs Lesson 3
Using numeric types in API calls.
In Lesson 2 we used the MoveWindow API call to change the size and location of a window. Have a look at the "as type" statements below.
hWindow is passed as type ulong while the x location of the window is passed as type long . Why is there a difference, and why is it important?
The helpfile shows us that Liberty BASIC uses the following numeric types in CALLDLL and STRUCTs.
double (8 bytes, a double floating point)
ulong (4 bytes, unsigned long integer)
long (4 bytes, signed long integer)
short (2 bytes, signed short integer)
ushort, word (2 bytes, unsigned short integer)
boolean (2 bytes, true/false expression)
char[n] (n bytes, available in structs only)
"Bit" is short for BI nary digi T . Binary digits are a basic unit of information storage and communication in digital computing. A bit has a value of either 0 or 1. For example, the number 10010111 is 8 bits long.
A byte is a unit of information storage that contains eight bits. A byte can represent 256 integer values, in the range of 0-255. In Liberty BASIC, bytes can be used in structs only and are represented by char[n] where 'n' is the number of bytes.
A word or ushort consists of two bytes, which is 16 bits. It can represent 65536 integer values in the range 0-65535.
In Liberty BASIC, a boolean type also consists of 2 bytes, but it represents a true/false expression. A value of 0 is false and any other value is true.
A short also consists of two bytes. It can represent 65536 integer values in the range of -32,768 - 32,767.
A long consists of four bytes, or 32 bits. It can contain integer values in the range of –2,147,483,648 to 2,147,483,647.
A dword or ulong also consists of four bytes. It can contain integer values in the range of 0 to 4,294,967,295.
A double consists of eight 8 bytes. It can contain decimal values in the range of 1E-307 to 1E+308 (15 decimal digits).
Did you notice that some types can hold negative numbers, while other types cannot? For instance, a short can hold -32,768 - 32,767, while a ushort which is also two bytes in size can hold 0 - 65535. This happens because each of the bits in these 16 biy types can hold one piece of information. In the case of a short type, one of the bits is reserved for the sign. The sign can either be positive or negative. Since that bit is reserved for the sign, there are only 15 bits left to determine the size of the number. In type ushort , all 16 bits can be used to determine the size of the number, so it can hold a larger number. That number must be positive, though. The u in types ushort and ulong stands for unsigned .
A double type is the only Liberty BASIC type that can contain decimal values. Double is short for double floating point number .
Look again at the code from Lesson 2 .
The hWindow argument is the handle of a window or control. Windows handles are unsigned 32 bit integers, so we pass that argument as type ulong .
The x and y locations of the window or control to be moved can be negative numbers, so we need to pass them as signed 32 bit integers, or type long .
Try it yourself! Copy the code from Lesson 2 into Liberty BASIC and try using negative numbers for the x and y locations.
Using numeric types in API calls.
In Lesson 2 we used the MoveWindow API call to change the size and location of a window. Have a look at the "as type" statements below.
calldll #user32, "MoveWindow",_
hWindow as ulong,_ 'handle of window
10 as long,_ 'x location of window
10 as long,_ 'y location of window
550 as long,_ 'width of window
350 as long,_ 'height of window
1 as boolean,_ 'repaint flag, 1=yes,0=no
result as boolean 'nonzero = success
hWindow is passed as type ulong while the x location of the window is passed as type long . Why is there a difference, and why is it important?
Numeric Types in Liberty BASIC
The helpfile shows us that Liberty BASIC uses the following numeric types in CALLDLL and STRUCTs.
double (8 bytes, a double floating point)
ulong (4 bytes, unsigned long integer)
long (4 bytes, signed long integer)
short (2 bytes, signed short integer)
ushort, word (2 bytes, unsigned short integer)
boolean (2 bytes, true/false expression)
char[n] (n bytes, available in structs only)
BITS
An understanding of numeric types begins with an understanding of the basic unit of information understood by a computer, the bit ."Bit" is short for BI nary digi T . Binary digits are a basic unit of information storage and communication in digital computing. A bit has a value of either 0 or 1. For example, the number 10010111 is 8 bits long.
A byte is a unit of information storage that contains eight bits. A byte can represent 256 integer values, in the range of 0-255. In Liberty BASIC, bytes can be used in structs only and are represented by char[n] where 'n' is the number of bytes.
A word or ushort consists of two bytes, which is 16 bits. It can represent 65536 integer values in the range 0-65535.
In Liberty BASIC, a boolean type also consists of 2 bytes, but it represents a true/false expression. A value of 0 is false and any other value is true.
A short also consists of two bytes. It can represent 65536 integer values in the range of -32,768 - 32,767.
A long consists of four bytes, or 32 bits. It can contain integer values in the range of –2,147,483,648 to 2,147,483,647.
A dword or ulong also consists of four bytes. It can contain integer values in the range of 0 to 4,294,967,295.
A double consists of eight 8 bytes. It can contain decimal values in the range of 1E-307 to 1E+308 (15 decimal digits).
Did you notice that some types can hold negative numbers, while other types cannot? For instance, a short can hold -32,768 - 32,767, while a ushort which is also two bytes in size can hold 0 - 65535. This happens because each of the bits in these 16 biy types can hold one piece of information. In the case of a short type, one of the bits is reserved for the sign. The sign can either be positive or negative. Since that bit is reserved for the sign, there are only 15 bits left to determine the size of the number. In type ushort , all 16 bits can be used to determine the size of the number, so it can hold a larger number. That number must be positive, though. The u in types ushort and ulong stands for unsigned .
A double type is the only Liberty BASIC type that can contain decimal values. Double is short for double floating point number .
Types in API Functions
We send numeric arguments into API functions "as type" because they need to know the type information to know how to interpret the number. Failure to use the correct type in an API call can cause a function to work incorrectly or even to fail.Look again at the code from Lesson 2 .
calldll #user32, "MoveWindow",_
hWindow as ulong,_ 'handle of window
10 as long,_ 'x location of window
10 as long,_ 'y location of window
550 as long,_ 'width of window
350 as long,_ 'height of window
1 as boolean,_ 'repaint flag, 1=yes,0=no
result as boolean 'nonzero = success
The hWindow argument is the handle of a window or control. Windows handles are unsigned 32 bit integers, so we pass that argument as type ulong .
The x and y locations of the window or control to be moved can be negative numbers, so we need to pass them as signed 32 bit integers, or type long .
Try it yourself! Copy the code from Lesson 2 into Liberty BASIC and try using negative numbers for the x and y locations.