PowerBASIC Gazette

Number 111 www.powerbasic.com



July
Ninth
2012

From: Bob Zale, President
           PowerBASIC, Inc.

PowerBASIC Gazette #111

Subject: An Introduction to the Windows API

Dear PowerCODER,

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)
END FUNCTION

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.

Library files
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 directory:

#COMPILE EXE
#INCLUDE "WIN32API.INC"
FUNCTION PBMAIN
   LOCAL szPath AS ASCIIZ * %MAX_PATH
   LOCAL Result AS DWORD
   Result = GetWindowsDirectory(szPath, SIZEOF(szPath))
   IF ISTRUE Result THEN
      MSGBOX szPath
   ELSE
      MSGBOX "The API function returned an 'error' result"
   END IF
END FUNCTION

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:

UINT GetWindowsDirectory(
   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. Happy API'ing!

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.

Transparent Unicode

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?"

GOTO http://www.powerbasic.com/products/whyupcc.asp
GOTO http://www.powerbasic.com/products/whyupwin10.asp

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 documentation:

          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.


Regards,

Bob Zale, President
PowerBASIC Inc.


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


Shipping/Handling:

Any SoftwareSoftware
& 1 book
Each
Addl Book
Email/Download$6N/AN/A
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
Express Canada/Mex$30$40$34
Air Mail Intl$14$28$28
Express Intl$36$46$40


Order online at shop.powerbasic.com/ or just send an email with all pertinent information to: sales@powerbasic.com

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@powerbasic.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 sales@powerbasic.com

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 support@powerbasic.com with your name and zip/postal code.