From: Bob Zale, President
PowerBASIC Gazette #111
Subject: An Introduction to the Windows API
This article is intended as an introduction to calling Windows
API functions. However, even the best programmers can use a
"refresher" here and there...
First, understanding how to call API functions is an essential
prerequisite to writing professional Windows GUI applications.
DOS programmers who have already made the transition across to
Windows programming will often mention that their first steps
were the most daunting, but then it got a lot easier, once some
of the key concepts were used a few times.
In addition, a basic understanding of how to make Windows API
calls can even benefit the programmers who rely heavily on visual
design tools. The extent and power of the Windows API can stretch
the horizons of every Windows programmer.
Just take it "Step by step", and "Don't give up!" - you'll get
there if you persist - and you'll be glad you did!
What is an "API"?
The often heard term "API" is an acronym for the collective phrase
"Application Programming Interface". Following on, the term
"Windows API" is used to describe a collection of Functions and
Subs that Microsoft Windows provides for Windows application
programmers to exploit.
Simply put, the Windows API can be visualized as nothing more than
a large set of programmer's libraries. In reality, Windows offers
an almost unbelievable number of API Sub/Functions that can be
used to do everything from setting the clock, sending email,
printing, playing WAV and MP3 files, to drawing graphical windows
on the screen, etc.
Subs, Functions and APIs
Calling an API function is absolutely no different than calling a
PowerBASIC Sub or Function using regular BASIC code. For example,
consider the PB function:
FUNCTION ABC(X AS STRING) AS LONG
FUNCTION = VAL(x)
You would call this with normal PB code, something like this:
a$ = "12345"
result& = ABC(a$)
Simple, right? As far as the programmer is concerned, calling an
API is no different! Lets discuss a little theory, then move along
to some of the more interesting aspects.
From a programming perspective, API Subs and Functions are no
different than the regular Subs and Functions you have probably
written in your own BASIC programs hundreds of times before. The
key difference is that API Subs and Functions are not actually
built into your program file (EXE file). Rather, Windows API
Subs and Functions reside in a set of modules or library files
with curious names like KERNEL32, USER32, etc.
To call an API, a program simply calls the required Sub/Function
that is stored in a library file.
To make it even easier, Windows transparently handles much of the
library file management for us!
So how does PowerBASIC know which library files to use?
When PowerBASIC compiles programs that make API calls, PowerBASIC
automatically builds an "import table" directly into the compiled
program file. The import table contains the names of the API
functions that the program will use, along with the name of the
library file that contains the API. Simply put, whenever a
program is launched, Windows examines the program's import table
and uses that information so it can load all of the required
libraries files into memory, right along with the program itself.
Windows then "links" the library files and the program code
together, before allowing the program to finally start running.
This process of loading libraries with applications is known as
"load-time" or "dynamic" linking. The library files that contain
the API Subs/Functions are referred to as "Dynamic Link Libraries",
or DLLs for short.
Ok, so what about calling some API functions?
To make use of an API function, all you have to do is pass the
correct parameters, and retrieve the return value correctly. For
example, the following piece of BASIC code defines a variable, and
makes an API call to retrieve the number of milliseconds (1/1000th
seconds) since the last reboot occurred:
DIM MillisecondsSinceLastBoot AS DWORD
MillisecondsSinceLastBoot = GetTickCount()
But how does PowerBASIC know that the GetTickCount() function is
an API call, and not another variable or Function in the BASIC
code, or is the name of a function that is simply missing from
the program code?
The answer is simple: In order to call an API Sub/Function, you
must first provide a declaration (DECLARE statement) to describe
the target API Sub/Function for PowerBASIC. The DECLARE acts as
a template so that PowerBASIC can validate the return data type
and API parameter types, etc. Further, the DECLARE statement
indentifies the name of the library file, so PowerBASIC can build
the import table correctly.
Do I write them myself?
You can, but a HUGE number of the most common Windows API functions
have already been translated to PowerBASIC for you, ready for use.
These declarations, along with various equates and UDT definitions,
can be found in the Win32API.INC file located in your WINAPI folder.
Therefore, a Windows program simply needs to #INCLUDE the file
WIN32API.INC in order to make good use of the multitude of API's
declared in WIN32API.INC. For example, the following is a fully
functional Windows application that uses an API Function to ask
Windows to provide the folder/path name of the "root" Windows
LOCAL szPath AS ASCIIZ * %MAX_PATH
LOCAL Result AS DWORD
Result = GetWindowsDirectory(szPath, SIZEOF(szPath))
IF ISTRUE Result THEN
MSGBOX "The API function returned an 'error' result"
The central part of this code is the call to the API Function
GetWindowsDirectory(). How did I know what that specific API
function needs for its parameters, and how did I know what the
return value signifies? Actually, this is pretty straightforward.
First, look up the API function name in the WIN32 Help File,
which shows that GetWindowsDirectory is defined by Microsoft
with C code syntax:
LPTSTR lpBuffer, // address of buffer for directory
UINT uSize // size of directory buffer
Yes, pretty cryptic! But a quick look finds the equivalent PB DECLARE
in the WIN32API folder:
DECLARE FUNCTION GetWindowsDirectory LIB "KERNEL32.DLL" _
ALIAS "GetWindowsDirectoryA" (lpBuffer AS ASCIIZ, _
BYVAL nSize AS DWORD) AS DWORD
Starting at the left of the C code definition, the UINT keyword
tells us that the function returns a UINT data type. In C, a UINT
is an unsigned 32-bit integer, which corresponds to a DWORD in PB.
Therefore, we can readily tell that the GetWindowsDirectory() API
will return a DWORD value to the calling code.
The 1st API parameter, an LPTSTR data type, tells us the parameter
is expected to be "long pointer" to a zero-terminated string buffer
-- in PowerBASIC, that's a pointer to an ASCIIZ string, or just a
BYREF ASCIIZ string.
The 2nd parameter, a UINT data type, is a DWORD parameter. The WIN32
Help File says this parameter is used to tell how many bytes are
available in the ASCIIZ string buffer. This parameter is not passed
as a pointer (or it would show the parameter as LPUINT -- therefore
we pass the actual value directly, using BYVAL.
The additional LIB and ALIAS clauses in the PowerBASIC DECLARE
statement simply tells the compiler which DLL contains this API
function, along with the API's "internal function name". For the
most part, these LIB and ALIAS clauses can be largely ignored since
most API functions you want to use will already have a suitable
DECLARE statement. They're located in WIN32API.INC or one of the
various .INC files included with PowerBASIC.
Finally, the return value of GetWindowsDirectory() is shown in the
WIN32 Help File to return zero if an error occurs, so we can
use that value to determine the success/failure of the API call.
As you can see, calling API functions means the simple act of calling
a Sub or Function, just like you do in normal BASIC programming.
The hardest part is learning "when" to call API functions and "what"
parameters to pass. To this end, the WIN32 Help File provides a wealth
of useful background info on API functions, their parameter lists, and
exactly what they do.
Where else can I find API information
One useful reference is the "Comparative Data Types" table in the
PowerBASIC help files. This can be used to assist with
syntax and parameter translations.
PowerBASIC, Inc. does its best to provide a comprehensive set of
API Sub/Function, equate, and structure declarations, via the
Win32API.INC and related .INC files. These files are updated and
expanded on a regular basis, and the most recent version can always
be downloaded from the PowerBASIC Web Site: www.powerbasic.com
Additionally, you can quickly get to grips with what parameters
and data types to pass to an API Sub/Function by looking at the
declaration for the API in the WIN32API.INC file.
You'll find that thousands of API functions have been discussed on
the PowerBASIC Forums, so searching for the name of an API function
will often yield good information and very often some example code.
THE POWER Changes Everything
Just in case you're one of the few... who hasn't yet upgraded to the
latest compilers -- Stay with me for a minute?
Now is the time to move. Full product purchases are just $199 and $169.
Pretty refreshing compared to some of the $2,000-$5,000 prices from the
competition! If you qualify for an upgrade, you can still take advantage
of special pricing. Upgrade PB/WIN 9 to PowerBASIC 10.0 for just $99 --
upgrade PB/CC 5 to PB/CC 6.0 for just $89! There is no reason to wait...
today is the day to upgrade.
Of course, PB/CC is our Console Compiler -- creates programs with a
text mode user interface. Easy to use. Easy to port from DOS. It's
the perfect solution for CGI Internet applications. Any time you want
pure performance and nothing more! PowerBASIC 10 for Windows gives you
the "look and feel" of a graphical user interface (GUI), the essence
of Windows. Frankly, they've both taken a big leap forward.
You know, a good compiler offers you ANSI strings. This has been the
standard for many years. A better compiler lets you choose between
ANSI and UNICODE in each program. But only one of them per program.
If you want Unicode, you can't keep binary bytes in a string. It
simply won't work. If you want ANSI, you can't have Unicode without
exhaustive conversions. Not so good.
A great compiler, like PowerBASIC, supports all of them in the same
program. And it's totally transparent. With PowerBASIC 10.0 for
Windows (or PowerBASIC Console Compiler 6.0), you can have it all.
One variable with ANSI. Another with UNICODE. Mix and match any
way you choose with PowerStrings. All the messy details, and even
the needed translations, are handled automatically by the compiler.
You can finally display a Euro symbol. Unicode text in a GUI or a
Console. Read and write a Unicode file. Even print Unicode text on
a Windows printer!
Static Link Libraries
Compile all your general purpose code into static units. Then, when
it's needed, just $LINK it into your EXE or DLL and you're on your way.
It's pre-compiled, so it's perfect for team programming. What will it
do for third-party tools? Plenty. PerfectSync has already released
SQL Tools 3. It links right into your EXE, so there's no need to drag
a DLL around. Just $LINK and go. Lots more tools are sure to follow.
And, if that's not enough, you'll get a librarian, too. Combine any
number of units to a single library, and just use one single $LINK.
PowerBASIC just discards those which aren't necessary. SLL's can
contain Subs, Functions, and Object Classes. How easy can it get?
Automatic Dead Code Removal
Fight the war on BloatWare. Now, you can include big libraries of
useful code -- PowerBASIC cleans it up for you. Any Sub/Function not
used is automatically ignored when compiled. In fact, even Classes
are pared down by similar Method and Property removal.
Order Now? GOTO https://shop.powerbasic.com/
There's more. Lots, lots more. A completely new IDE based on Tabs,
with syntax display as you type! Transparent Unicode. Print Preview.
Thread Objects. A built in Resource Compiler. A StringBuilder Class.
PowerArray class encapsulates SafeArray structures. A DEC$ function
formats decimal numbers. Graphic Windows with scroll bars and scroll
keys, user drag to resize, clip areas, and wrap by whole word. ENUM
blocks, PREFIX blocks, ASMDATA blocks. THREADSAFE option for functions
and methods. TEXT windows, Text Split, and the new FASTPROC procedures.
There's more, but it's easy to see this is a very important upgrade.
SQL Tools version 3
You can use the power of SQL to access relational databases from
Microsoft Access, SQL Server, Oracle, FoxPro, dBase, Btrieve, and 50
other popular formats. Open a database with a single line of code,
and use standard SQL statements to build powerful, sophisticated,
multi-user database programs! This is a total database solution.
This product has earned accolades from virtually all of its users.
Version 3 is certainly no exception. With both a DLL and an SLL,
you'll have the option to just $LINK units and libraries right into
your EXE. No more DLL's to drag around, unless you choose it.
Even better, PowerBASIC will only link the code that's necessary.
Version 3 is faster and leaner, even with all the new features.
Many functions have been simplified. You can retrieve all rows in
a single operation. You'll also get improved trace files, Quad
integers, Unicode, plus enhanced Memo and BLOB field support.
Then there's improved Microsoft Access database support, and much
more! Documentation is provided in CHM, HLP, and PDF formats.
You can order right now...
PB/WIN 10.0 is priced at $199, while PB Console Compiler is $169.
Upgrades from versions 9 and 5 are just $99 and $89 respectively.
SQL Tools Pro is $199.95, while SQL Tools Std is $99.95. Upgrades
from version 2 are $99.95 and $69.95 respectively.
Need more info?
We have a page created just for you. It's "Why should I upgrade?"
Need even more info?
The complete documentation for both PB/CC 6 and PB/WIN 10 can be
found right on the PowerBASIC Web Site! To see the 100% complete
GOTO www.powerbasic.com -- Then [click] HELP DESK
You'll find everything you need to know to make an informed decision.
You can order right now by replying to this email. You can call us
today at (888)659-8000 or (941)473-7300, or fax us at (941)681-3100.
You can visit https://shop.powerbasic.com/ to place an e/order on
our secure web site, or even mail an order to our offices. But no
matter what method you choose, do it today and do it with confidence.
Every product PowerBASIC ships for physical delivery is offered with a
money-back guarantee for a full 30 days from the transaction date.
Bob Zale, President
PowerBASIC Price List
| PB/CC Console Compiler 6.0 - Full Product|| $169.00|
| PB/CC Console Compiler 6.0 - Upgrade from ver 5|| $89.00|
| PB/CC Console Compiler 6.0 - Upgrade from prior versions|| $119.00|
|    Add Printed Documentation|| $49.00|
| PowerBASIC for Windows 10.0 (GUI) - Full Product|| $199.00|
| PowerBASIC for Windows 10.0 - Upgrade from ver 9|| $99.00|
| PowerBASIC for Windows 10.0 - Upgrade from prior versions   || $129.00|
|    Add Printed Documentation|| $49.00|
| PowerBASIC for DOS 3.5 - Full Product|| $99.00|
| PowerBASIC for DOS 3.5 - Upgrade from prior versions|| $49.00|
|    Add Printed Documentation (2 book set)|| $29.00|
| PowerTree BTree Manager for DOS and Windows|| $99.00|
| PowerBASIC Forms Visual Designer ver 2.0|| $99.00|
| SQL Tools Standard Version 3.0:|| $ 99.95|
|    Upgrade from ver 2 (Std)|| $69.95|
| SQL Tools Professional Version 3.0:|| $199.95|
|    Upgrade from ver 2 (Pro)|| $99.95|
|    Upgrade from ver 2 (Std)|| $129.95|
| Graphics Tools Standard ver 2 for PB/CC & PB/WIN|| $69.95|
| Graphics Tools Professional ver 2 for PB/CC & PB/WIN|| $139.95|
| Graphics Tools Standard ver 2 Upgrade from ver 1|| $44.95|
| Graphics Tools Professional ver 2 Upgrade from ver 1|| $114.95|
| Graphics Tools Professional ver 2 Upgrade from ver 2 Std|| $79.95|
| Console Tools Standard:|| $49.95|
| Console Tools Professional:|| $99.95|
|Any Software||Software |
& 1 book
|UPS Ground/Mail US||$10||$10||$ 8|
|Express 2-day US||$18||$18||$14|
|Express 1-day US||$28||$35||$30|
|Air Mail Canada/Mex    ||$10||$18||$18|
|Air Mail Intl||$14||$28||$28|
Order online at shop.powerbasic.com/ or just send an email with all pertinent information to:
We'll take it from there!
Most PowerBASIC products (those without printed books) can now be delivered by electronic mail. No wait for a package to arrive... No high shipping costs... For just $6 per order, no matter how many products, we'll deliver directly to your computer. If you're outside the U.S., savings might be greater. You won't pay taxes or duties to a freight company or postal service, because they aren't involved in the delivery. Check your tax code to be sure, but some countries charge no tax at all on transactions of this type. It could just be your lucky day!
Send your subscription request to email@example.com and please include your name and all email addresses you'd like to add, as well as your Zip or Postal Code.
If you know someone else who would enjoy this newsletter please forward a copy to them so they can subscribe.
All contents Copyright (c) 2012 PowerBASIC Inc All Rights Reserved. PowerBASIC, PB/CC, PowerBASIC Forms, and PowerTREE are trademarks of PowerBASIC Inc. Other names are trademarks or registered trademarks of their respective owners.
PowerBASIC Gazette - Electronic Edition|
Volume 1 - Issue 111
|PowerBASIC, Inc.|| (888) 659-8000 Sales|
|2061 Englewood Road|| (941) 473-7300 Voice|
|Englewood, FL 34223    || (941) 681-3100 Fax|
Visit us on the Net at www.powerbasic.com
Email Sales at firstname.lastname@example.org
This newsletter is only sent to email addresses in our subscription list. If you have received this newsletter by mistake or no longer wish to receive it, please forward this newsletter, with "unsubscribe" in the message to email@example.com with your name and zip/postal code.