PowerBASIC Application Files
A typical PowerBASIC application requires only a single file - the text file that contains the source code for the application. Source code is generally kept in a file with the extension .BAS, although the only real requirement is that the source code be kept in a text file. There is no required extension.

However, if you want to be able to double-click on a PowerBASIC source code file and have it opened in the PowerBASIC IDE then you have to register the extension with Windows. The PowerBASIC IDE Options dialog, shown in the following image, can do this for you.

Just check the "Register File Extensions with Windows" box to have Windows open files (with the listed extensions) in PowerBASIC. Even with this box checked, you can still manually open any source code text file in PowerBASIC. Registering extensions is simply a matter of convenience for the programmer.

A PowerBASIC program can consist of more than source code file. This is usually done for the convenience of the programmer, allowing code to be broken into smaller, more manageable sizes or to organize code by having similar function contained in a single file.

Loading Source Code Files
Multiple source code files can be loaded into the PowerBASIC IDE in several ways:

These three methods allow loading of only one source code file at a time. The next section discusses project files (*.pbp), which allow loading of several source code files at one time.

Project Files
Finally, to make it easier to load all of the files needed for a program, PowerBASIC supports a project file with an extension of .PBP. It is a binary file that contains the full pathname of all files used in the project.

To create a project file, simply open all needed source code files and use the "Save Project ..." menu option from the PowerBASIC IDE. The file is binary so you cannot simply open up Notepad and create a project file.

To use an existing project file simply use the PowerBASIC "Open Project ..." menu option to load the project (all of the source code files listed within the project file) into the IDE. Opening all source code files is a common practice with programmers. Double-clicking on a .PBP file will not open the project unless you have registered the .PBP extension using the method described above.

In summary, here are the files and the default extensions typically used in a PowerBASIC application.

Source Code File Content
A PowerBASIC source code file consists of a series of procedures (Sub/Function) and begins execution with the code found in the PBMAIN() function. PowerBASIC also allows the insertion of code outside those procedures, usually as lines of code at the top of the file. These non-procedure lines of source code can contain several types of statements.

PBMain, WinMain
When a PowerBASIC program starts it first runs the PBMain or WinMain functions. One must be included in a PowerBASIC application, but both are not allowed. The PowerBASIC compiler will allow only one of the two to be compiled into an application, so there is no question of having two conflicting startup functions.

The syntax of both functions is shown next. Windows allows the WinMain function the be named simply Main().

                     BYVAL hPrevInst AS DWORD, _
                     BYVAL lpszCmdLine AS ASCIIZ PTR, _
                     BYVAL nCmdShow AS LONG) AS LONG


If the WinMain is included in a PowerBASIC program, Windows calls the function and provides the four WinMain arguments to the PowerBASIC program.

The WinMain arguments are not used all that often within a PowerBASIC program, making the PBMain function a viable, somewhat simpler option. If the command line is needed, the PowerBASIC COMMAND$ function can supply it. Also, if the applicaton instance handle is needed, the GetModuleHandle API function can provide it. These options essentially eliminate the need to use the WinMain startup function.

Message Loop
Regardless of which function (PBMain or WinMain) is included in a PowerBASIC application, a PowerBASIC program executes all the lines of that function and then terminates. While that may be a useful technique for some applications, most Windows applications expect a GUI application window to appear and stay visible until the user ends the program.

So in a typically PowerBASIC application, the startup function (PBMain or WinMain) is used to create the initial GUI application window and then the code goes into an endless loop, waiting for receipt of a %WM_QUIT message from Windows.

An endless loop can be achieved in several ways.

By convention, if a WinMain function is used the wParam& parameter of the %WM_QUIT message should be passed on as the return value for WinMain. Likewise, if WinMain terminates before entering the message loop, WinMain should return zero.

Just as an executable has a startup function, so does a DLL, except that the DLL startup function is optional. The startup function is called LIBMain (or DLLMain). PowerBASIC supports an alternative DLL startup function called PBLIBMain.

The syntax of both functions is shown next. Windows allows the WinMain function the be named simply Main().

                      BYVAL lReason AS LONG, _
                      BYVAL lReserved AS LONG ) AS LONG


If the LibMain is included in a PowerBASIC DLL, Windows calls the function and provides the three LibMain arguments to the PowerBASIC program.

A programmer may choose not to use the LibMain arguments, so the PowerBASIC PBLibMain is provided as a slightly simpler alternative.

Resource Files
Resource files are binary files which contain binary and/or text information, from which applications can read the information as needed at run time. The information in the file can be images, databases, text strings - any information the programmer decides is necessary to support the application. These binary files use a format developed by Microsoft and typically have an extension of .RES.

The primary reason to use resource files is so that only one data file is distributed, rather than several files containing all the various types of information a project might need. It also helps ensure that the individual data files are not changed by the user.

To create a binary resource file, most resource file editors start with a text file that describes the resources that are to be compiled (combined) into the resource file. The text files are called resource scripts. The most common resource script file extension is .RC, although the Microsoft Dialog Resource file extension of .DLG is also common.

Resource file compilers also allow the use of #INCLUDE compiler directives, just as the PowerBASIC compiler allows the same directive. A typical include file for resources uses a .h extension. All of these file types (.RC, .DLG, and .h) are industry standard files and can be used by the PowerBASIC IDE to create .RES resource files.

PowerBASIC also offers the ability to embed a resource file directly into an EXE/DLL so that only one file has to be distributed to the user. The embedded file can be accessed by the EXE/DLL just as though a separate resource file was provided. Not only does it simplify the distribution process, but it also ensures that integrity of the data because the user does not have access to the resource file (tools are readily available to modify resource file content). In order to embed the resource file, however, PowerBASIC must reformat the resource file. A reformatted PowerBASIC resource file has an extension of .PBR and it is the reformatted file that is embedded within a PowerBASIC EXE/DLL.

Here's a summary of the resource-related files and their file extensions.

My tutorials do not currently cover resource script file creation. The PowerBASIC Help file has more information but the definitive information comes from Microsoft at MSDN.

If you have any suggestions or corrections, please let me know.