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:

• Open File Menu
  This is the usual way to load a source code file, with the Open File menu option in the IDE. More than one file can be opened at one time but only the current source code file (where the caret is located) will be compiled. Alternately, one of the open files may be designated at the Primary Source File, in which case only the primary source file will be compiled, regardless of which file has the focus.

• Insert File Menu
  The Insert File menu option reads a file and places the content into the IDE. The selected file is not opened - its contents are simply placed into the editor within the currently selected document are the current caret position.

• #INCLUDE Compiler Directive
  Source code files, including .INC files, can contain instructions to the compiler to include other files (opened or not) into an application - compiling the code from other files as though the code were actually in the current file. For longer programs, such as those with 100+ lines, this is a very common technique.

  Simply place a line of code into a source code file to pull in source code from other files, as in one of the following examples. More than one #INCLUDE line can be used in a source code file.

      #INCLUDE  "extracode.bas"
      #INCLUDE  "extracode.inc"
      

  The .INC extension is recommended for secondary files, but many programmers prefer .BAS. PowerBASIC allows any extension to be used.

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.

• .BAS - source code (text).
• .INC - source code, include file (text)
• .PBP - project file, list of source code files (binary)

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.

• Compiler directives - non-executable instructions for the compiler
• GLOBAL statements - globally dimensioned variables
• Equates - numeric and string constant assignments

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().

    FUNCTION WINMAIN(BYVAL hInstance AS DWORD, _
                     BYVAL hPrevInst AS DWORD, _
                     BYVAL lpszCmdLine AS ASCIIZ PTR, _
                     BYVAL nCmdShow AS LONG) AS LONG

    FUNCTION PBMAIN() 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.

• hInstance - application handle (each instance gets a unique handle)
• hPrevInst - not used
• lpszCmdLine - ASCIIZ string containing the command line arguments
• nCmdShow - requested main window display status (%SW_NORMAL, %SW_MINIMIZE, ...)

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.

• Modal Window
  If the first program window (dialog) is opened modally then the PowerBASIC application will not end until the window is closed. Until the window is closed, the applicaton can respond to Windows messages (events). Once closed, the PowerBASIC application completes all remaining lines of code in the PBMain/WinMain function and then terminates.

• Endless Do Loop
  A simple Do/Loop source code loop can be used to loop endlessly, while watching for a command to exit the loop and then to exit the PowerBASIC application. The following code is an example of an endless Do loop which is placed after the code that creates the startup window(s).

          Do Until iExit = 1
              'Callback Function sets iExit when %WM_QUIT is received
          Loop
      

  This approach allows the use of nonmodal windows.

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.

PBLIBMain, LIBMain
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().

    FUNCTION LIBMAIN (BYVAL hInstance AS DWORD, _
                      BYVAL lReason AS LONG, _
                      BYVAL lReserved AS LONG ) AS LONG

    FUNCTION PBLIBMAIN() 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.

• hInstance - application handle (each instance gets a unique handle)
• lReason - reason why DLL is called. allowed values are %DLL_process_attach, %DLL_process_detach, %DLL_threat_attach, %DLL_thread_detach
• lReserved - clarifies lReason. 0 for dynamic loads, <>0 for implicit loads.

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.

• .RC - resource script, standard (text).
• .DLG - resource script, dialog (text)
• .h - resource include file (text)
• .RES - resource file, compiled, MS format (binary)
• .PBR - resource file, compiled, PowerBASIC format (binary)

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.