Compiling Applications

Once you have created a program source-code file, you must compile it into executable form for the Visual DataFlex virtual machine to execute. This executable file is created by the Visual DataFlex Compiler.

The compiler reads the source file and produces 2 files with the same rootname as the source file, in the Programs directory of the workspace:

  • An executable file with the extension .EXE

  • A file with debug information with the extension .DBG

If errors occur during compilation, the compiler creates a third file with the same rootname as the source file, in the AppSrc directory:

  • An error listing file with extension .ERR

Compiling from within the Studio

The Studio includes an integrated compiler. You can compile the current project by selecting Project -> Compile from the menu, or click the compile toolbar button. The Studio also automatically compiles the project if changes are detected when you select Debug -> Run from the menu or click the Run toolbar button.

The compiler progress and output is displayed in the Output Window. If errors occur during compilation, the error will also be displayed in the Output Window. Double-clicking on an error listed in the Output Window will automatically open the specified source file and locate the line of error.

Compiling from outside the Studio

If you launch the compiler from the Start Menu (Visual DataFlex 12.0 | Development Tools | Compiler), it will function differently from the integrated compiler.

Please see Launching the Compiler Outside the Studio for details.

Handling Compiler Errors

To learn how to resolve compiler errors, see Handling Compiler Errors.

For a listing of compiler errors and solutions, see Compiler Errors.

Topics in this book:

  • Compiler Options

  • Launching the Compiler from the Command Line

  • The Compiler Interface

  • Precompiling

  • Compiler Directives


Compiler Options

When compiling in the Studio, the compiler options configured in the Configure Environment dialog on the Tools menu are always used. If you wish to change the compiler options used when compiling in the Studio, use this dialog to do so.

The samples below show how to use the compiler options when launching the compiler outside the Studio.

C – Force Recompile

Tells the compiler to recompile the program even if no changes are detected. Normally the compiler looks for the compile dependency file (.dep or .pdp) and only recompiles if the compiled program is out of date with the source code. This compiler option skips the compile dependency checking and forces it to recompile the program.

E# - Error Notification Level

The compiler will report errors in the following modes: Quiet (E0), At End (E1=default), or On Each (E2).

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject -e2 MyApplication.src

will compile MyApplication.src in the AceCorpProject workspace and stop execution on each compiler error encountered.

F & V# - Create List File & List File Verbosity

F tells the compiler to create an intermediate code listing (.PRN) file, and V# tells the compiler at what verbosity, where # is a number from 0 to 99 (the default setting in the Studio is V1). The .PRN file is created in the AppSrc folder of your workspace.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject -e1fv3 MyApplication.src

will compile MyApplication.src in the AceCorpProject workspace and stop execution at the end if any compiler error encountered. A list (.PRN) file will be created with verbosity level 3.

I - Interface Level

The compiler handles the following interface modes, which can only be entered on the command line. Like other compiler options, these are made up of a letter (I) followed by a number.

Interface Mode | Description
I0 Hidden | No interface or prompt is ever given and the compilation is completely in the background. The Error Notification Level options have no effect at this level. The only way to determine compile errors is through an Error (.ERR) or List (.PRN/.PRP) file. In this mode, there is no way to halt a compilation.
I1 Prompt at End | No interface is given and the compilation runs in the background. When done, a prompt is given displaying if successful or the number of errors. The Error Notifications options have no effect at this level. The only way to determine compile errors is through an Error (.ERR) or List (.PRN/.PRP) file. In this mode, there is no way to halt a compilation.
I2 Display Interface then Exit | An interface is shown and all compiler options apply as normal. If a source is passed, compiling begins immediately and the compiler exits if successful. If errors do occur, the interface remains. This is the default mode if a source file is passed.
I3 Always Display Interface | The interface is always shown and all compiler options apply as normal. Compiling does not start until initiated through the interface. The interface remains whether the compilation is successful or not. This is the default mode if no source file is passed.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject -e1fv3i1 MyApplication.src

will compile MyApplication.src in the AceCorpProject workspace and stop execution at the end if any compiler error encountered. A list (.PRN) file will be created with verbosity level 3. The interface will be hidden but prompt the user at the end of compilation whether it was successful or how many compiler errors occurred.

P - Precompile

Creates precompiled program modules.

Precompiles a part of the program code or a package (e.g., DFAllEnt.pkg) and speeds up the development cycle. The code to be precompiled is considered to be static while the other program code is more dynamic.

When the P option is used, the compiler stops compilation either at the end of the source code (when for example DFAllEnt.pkg is precompiled) or when it detects the #ENDHEADER statement. The compiler will generate files named ProgramName.FLD, ProgramName.PBG, ProgramName.PKD and ProgramName.PRP.

See the Precompiling section for more details about precompiling.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject CustomGrid.pkg -p

will precompile CustomGrid.pkg in workspace AceCorpProject.

R - Run After Compile

Tells the compiler to execute the program after a successful compile.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject -e1fv3r MyApplication.src

will compile MyApplication.src in the AceCorpProject workspace and stop execution at the end if any compiler error encountered. A list (.PRN) file will be created with verbosity level 3. If the program compiles successfully, it will launch after compilation completes.

W - Write Error File

Will create an .ERR file listing of the compiler errors with the same rootname as the source file, in the AppSrc directory of the workspace.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject -fv3w MyApplication.src

will compile MyApplication.src in the AceCorpProject workspace and create an error listing (.ERR) file if any compiler error encountered. A list (.PRN) file will be created with verbosity level 3.

X - Use Workspace

If this option is used with no argument, it indicates that the current workspace is to be used for compilation. If used with an argument, the argument is the name of the workspace to use.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -x MyApplication.src

will compile MyApplication.src in the current workspace.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xAceCorpProject MyApplication.src

will compile MyApplication.src in the AceCorpProject workspace.

To disable the use of any workspace, place a - after the X option. When doing so, the program is not compiled using a workspace registry key. Instead, it uses the [Default] key, which is defined in the Windows Registry under HKey_Local_Machine\Software\Data Access Worldwide\Visual DataFlex 12.0\Defaults. The compiler should find all source components in the MakePaths entry of the Dfcomp key.

This will also cause all files created by the compiler to be placed in the same directory as the source code file that is being compiled, instead of being placed in the appropriate workspace subdirectories.

Example

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -x- MyApplication.src

will compile MyApplication.src using the [Defaults] key instead of a workspace. You may have to use the full path to the source code file you want to compile:

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -x- C:\MyProject\MyApplication.src

Notes

  • Compiler options are not case sensitive.

  • The options string may begin with either a "-" or "/" and can consist of multiple options in a row, with the exception of "-x". "-x" must be written separately from the other options.

  • When configuring these options in the Studio's Configure Environment dialog, you only need to place the options in a string and do not need to precede it with a "-" or "/". For example: "fwv1e0".

  • The default compiler options are "-fwv1e0".


Launching the Compiler Outside the Studio

You can launch the compiler outside of the Studio (using Start | Run or from a command prompt). You can also add the Compiler to the Studio's Utilities menu using the Configure Utilities menu option.

When launching the compiler outside the Studio, you must pass the appropriate command line parameters for compilation.

dfcomp {Source} {-x} { options{ } . . . } Start compiler with current workspace

dfcomp {Source} -xWorkspace { options{ } . . . } Start compiler with Workspace

dfcomp {Source} -x- { options{ } . . . } Start compiler with default settings.

Argument | Explanation
source | Is the program area or file containing the source code to be compiled.
options | Is a string of compiler options.

Notes

  • Unless the path to the compiler is part of the PATH environment variable, you will have to use the full path to the compiler:

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -x MyApplication.src

  • When starting the compiler with default settings, the [Defaults] section in the registry will be used instead of a workspace.

  • You can turn off any option by placing a "-" after end of any individual option.

  • "-" and "/" are interchangeable.

  • The order in which parameters are passed does not matter.

  • This string may begin with either a "-" or "/" and can consist of multiple options in a row, with the exception of "-x". "-x" must be written separately from the other options.

    For example, "-v1f -x" is correct, while "-v1fx" is not.

  • The default compiler options are "-fwv1e0".

  • See Compiler Options for details about these options and examples.


The Compiler Interface

This section discusses the user interface of the Visual DataFlex compiler.

If you launch the compiler from the Studio, you will rarely spend a lot of time with the compiler interface, but rather let the Studio handle all compiler-related tasks.

Topics in this book:

  • Workspace Combo Box

  • File Name

  • Halting During Compilation

  • Options Tab page

  • Paths Tab Page


Workspace Combo Box

The Workspace combo box is provided for you to instruct the compiler which workspace to use when compiling. The compiler starts up in the most recently used workspace in the Studio. You can scroll and select earlier entries to this box from a list that drops down when you click the arrow box on the right of this box.

You may select one of the recent workspaces or [Defaults], or you can click the prompt button to the right, which will allow you to browse to the workspace file. What you select will adjust the contents of Paths and Options tab pages according to values recorded in the workspace you select.

See Also

The Compiler Interface


File Name Form

The File Name form is provided for you to instruct the compiler which source-code file to compile. If you selected a workspace, you will be expected to enter the name of a source-code file that is associated with that workspace. The prompt […] button to the right of the edit box will allow you to browse files starting with the AppSrcPath directory of the selected workspace.

If you selected [Defaults], you will be expected to enter the name of a source-code file from the working directory. The prompt button will allow you to browse files starting with the working directory. Of course, you may enter a full path in the case of a workspace or [Defaults] and in that way, compile any file.

Pressing Enter in this box launches the compilation, as does pressing the Compile button.

Here is how the compiler determines what information to use.

 | [Defaults] (no Workspace) | Workspace
Source-code file | Source | Source if it includes a path, AppSrcPath/Source, otherwise.
Output (exe) filename | SrcRoot (rootname of Source) | Source if it includes a path, ProgramPath/SrcRoot, otherwise
Output directory | Same as Source | AppSrcPath
Used/included files | MakePath in [DFCOMP] | AppSrcPath; ProgramPath; …
Data and data-dictionary files | Directory started in. | DataPath
Compile options | BuildOptions in [DFCOMP] | BuildOptions in [Workspace], then in [DFCOMP]

Source refers to the source file/pathname passed from the command line or selected. SrcRoot is source without its extension.

Except in the case of used/included files, only the first directory listed in AppSrcPath, ProgramPath, and DataPath is used.

File

In compilation, if workspace or key is used, the workspace will be used for finding package files, data dictionaries, compiler options, and anything else required by the compilation.

The filename may be entered with or without a directory path. The presence or absence of a directory path affects where files are found and written, as follows.

With Path

The compiler will look for the source-code file only in the entered directory. If OutputDirectory is set in the program area or the DFComp key, it will be used to place the output files. Otherwise, the output files will be placed in the directory in which the source-code file was found.

Without Path

The compiler will search for the source-code file in the directories listed in MakePath. If OutputDirectory is set in the DFComp key or the program area, the output files will be written to that directory. Otherwise, the compiler will overwrite the first existing compiled program file with the name matching that of the file the compiler will write found in the directories listed in MakePath. If no such file is found, the new file will be placed in the first directory listed in MakePath.

See Also

The Compiler Interface


Halting during Compilation

Once compilation begins, the Compile button changes to the Halt button. Compilation may be halted by pressing this button. If you halt a compilation, you will not be able to resume it; you will have to restart it from the beginning.

If you halt compilation whose output is directed to the directory and filename of an existing compiled program, that program will be erased at the start of compilation; after halting, there will be no compiled program file at all. A halted compilation will appear to end normally, with a block of summary data that will report an error total of two more errors than will actually have been reported up to that point.


Options Tab Page

Editing the compiler Options tab page does not change the values in the registry, which are read from the BuildOptions key value of the DFComp key.

Create List File Check Box

Errors reported at run time report the line number of the compiled program, which can be very different from the line number in the source code. A list file is an ASCII file created by the compiler that maps the source-code line number to the line number in the compiled program, helping you interpret and correct the causes of runtime errors.

The list file can also show expanded macros, constant replacements, Include files, and compile errors. Therefore, a list file is useful for dealing with compile-time errors as well.

Their rootnames are that of the source-code file with the extension .PRN (if of a Visual DataFlex program) or .PRP (if of a Visual DataFlex precompiled module).

Verbosity Level Spin Form

The higher you set the number in this box, the greater the detail that will be reported in the list file.

There are several ways to tell the compiler to create a list file and to specify the level of verbosity:

  • Check the Create List File box in the Options tab page. You will then be able to specify the verbosity level with a spin form.

  • Include f or fv# in the BuildOptions key value.

Precompile Check Box

You may precompile either a separate package or the uppermost portion (the "header") of your source code to save time in subsequent recompilations during development. The header is merely that contiguous part of your source-code file, beginning with the top that you do not change from one compilation to the next. The greater the portion of your source code that you precompile, the greater the time savings you can realize with each recompilation of a program whose header you have precompiled.

Of course, if you change any code in the precompiled section, you will have to either compile the whole program (which requires moving, renaming, or deleting the old precompiled-header files), or precompiling the new header section again before recompiling your program. If you fail to do this, the changes you make to the header section will not take effect on recompilation.with #ENDHEADER. #HEADER must be the first (non-comment) line in your source code.

You can designate the portion of your code to precompile by beginning it with the #HEADER compiler directive and ending it with #ENDHEADER. #HEADER must be the first (non-comment) line in your source code.

Precompilation is especially useful with package and other include files. If the first (non-comment) line of your source code is a use command, precompilation will create precompiled modules of the package named in that command. This usage does not require #HEADER and #ENDHEADER, which can be used to precompile multiple package files.

The rootname of each precompiled-header file is that of the source-code file, plus the extensions of .FLD, .PBG, .PKD, and .PRP. A .FLD, .PBG, .PKD, and .PRP file are created every time a header is compiled. Current versions of these files must be present in a directory listed in your MakePath when recompiling their host program. If they are not, the recompilation will not use the precompiled header.

There are several ways to tell the compiler to precompile:

  • Check the Precompile box in the Options tab page.

  • On the command line, pass p or /p.

  • Include p in the value of the BuildOptions key value.

See the Precompiling section for more details about precompiling.

Run after Compile Check Box

The compiler can be told to execute the new Visual DataFlex program automatically after a successful compilation. It will not execute the program automatically if any error occurred during compilation.

There are several ways to tell the compiler to run the compiled program automatically after compilation:

  • Check the Run After Compile box in the Options tab page.

  • On the command line, pass r or /r.

  • Include r in the BuildOptions key value.

Note: This option is defeated if any error occurred during compilation.

Write Error File Check Box

An error file is an ASCII file listing of the errors generated by the most-recent compilation (unlike a list file, which lists both errors and source code). Its rootname is that of the source-code file plus the extension of .ERR.

There are several ways to tell the compiler to create an error file:

  • Check the Write Error File box in the Options tab page.

  • On the command line, pass w or /w.

  • Include f or w in the value of the BuildOptions key value.

The error file will have the same name as the source but with the extension .ERR.

Error Notification Level Radio

The compiler will report errors at one of three levels. Following the name of each choice below is the option value in parentheses to use when launching compilation from the command line.

Quiet (E0) No prompt is ever given. You can only observe if an error has occurred by looking at the Error (.ERR) file, List (.PRN/.PRP) file, or progress display. This level is best if you are compiling in a batch process.

At End (E1=default) At the end of compilation, a prompt is given signifying"‘done" if successful or number of errors if not.

On Each (E2) If an error occurs, a prompt is given allowing the user three options.

There are several ways to set the compiler error-notification level:

  • Check the desired Error Notification Level radio box in the Options tab page.

  • On the command line, pass e# or /e# where # represents the desired level.

  • Include e# in the BuildOptions key value.

See Also

The Compiler Interface


Paths Tab Page

The Paths tab page displays the directories and paths the compiler is using.

You may edit the WorkingDir, OutputDir, and MakePath without fear of editing the registry values. Any edits you make will only be used for the current compiler session.

If you are concerned that you may overwrite a Visual DataFlex program being used in a live system, you can direct placement of the output file elsewhere by doing one or more of the following:

  • Entering the full (safe) path when compiling a named file.

  • Editing the value of OutputDir to a safe directory.

  • Compiling through a program area in which VDF File and OutputDir are specified to a safe name and/or output directory.

  • Make sure the directory containing the in-use program is not listed in your MakePath.

Src File:

The directory path and name (with extension) of the source-code file to be compiled.

VDF File:

The directory path and rootname (only) of the executable program file (.EXE) to be created by the compiler. This key does not affect the name or placement of the other files output by the compiler, such as compiler error (.ERR) files or compiler listing (.PRN) files.

Working Dir:

The directory to be searched for the application’s database files, which are used in compilation. The name of the registry key is WorkingDirectory.

Output Dir:

The directory where files other than VDF program files (list files, error files, precompiled modules) are placed. These files are always written with the rootname of the source-code file, regardless of whether VDF specifies a different rootname for the .EXE file. The name of the registry key is OutputDirectory.

Make Paths:

A list of directories used to search and find files both for input and output. The name of this key is MakePath. If it is not set under the program area, workspace, or DFComp key or the file sought is not found, the directories in DFPath are searched.

See Also

The Compiler Interface


Precompiling

The continual recompiling of large packages and programs can be time-consuming. To speed the use of packages at compile time, the precompile option is provided.

How Precompiling Works

When a package or program is compiled with the precompile option, the compiler outputs four files, with the same rootname as the source file, all of them in the AppSrc directory of the workspace:

  • A file which is exactly like a compiled program file with the extension .FLD.

  • A file containing debug information with the extension .PBG. This file is identical to a .DBG file created for a normally compiled program.

  • A debug package include file, which contains other information about the program just compiled with the extension .PKD.

  • A file that is the intermediate compiler listing of the precompile process with the extension .PRP. This file is identical to a .PRN file created for a normally compiled program using the F compiler option.

When another program uses that file, as the first statement of the program, the precompiled program will be read in from the .FLD, .PBG, .PKD and .PRP. files instead of fully recompiling. This saves the time of compiling the used file each time.

Example

If you frequently used a custom grid class in your non-database Windows applications, you could create a package made up of the 2 packages you use in all of your programs (for this example, we'll call it CustomGrid.pkg), then compile it like this:

"C:\Program Files\Visual DataFlex 12.0\bin\DFComp.exe" -xWorkspaceName CustomGrid.pkg -p

where

- WorkspaceName is the name of the workspace the package resides in.

Now you can compile any program that uses the packages that are used in CustomGrid.pkg without having to recompile the code in all of these packages each time you compile the program.

See Also

  • Grouping Packages

  • Incremental Compilation

  • The Rules of Precompiling


Grouping Packages

You may easily create your own precompiled package groups. For example, if you frequently used a custom grid class in your non-database Windows applications, you could create a package made up of the 2 packages you use in all of your programs, like this:

Code for CustomGrid.pkg:

Use Windows.pkg

Use cMyCustomGrid.pkg

If this file were saved as CustomGrid.pkg and compiled with the P option, a simple "use CustomGrid.pkg" command as the first line of your program would include both packages, precompiled. Any number of packages may be grouped like this.

Precompiling this package will produce the files CustomGrid.FLD, CustomGrid.PBG, CustomGrid.PKD and CustomGrid.PRP.

You must use the precompiled package as the first statement in the program that uses it, or the precompiled package will not be used and the entire program will be recompiled, including the packages used in the precompiled package.

Example

Code for MyWindowsApp.src:

Use SomeOtherPackage.pkg

Use CustomGrid.pkg

Object oMyCustomGrid1 is a cMyCustomGrid

:

End_Object

The above code is incorrect, since it uses another package prior to the precompiled package CustomGrid.pkg. Thus, the entire MyWindowsApp.src program will be recompiled, including all files included in CustomGrid.pkg.

The code below is a corrected version of this program, because it places "Use CustomGrid.pkg" as the first line of code in the program.

Code for MyWindowsApp.src:

Use CustomGrid.pkg

Use SomeOtherPackage.pkg

Object oMyCustomGrid1 is a cMyCustomGrid

:

End_Object

See Also

Precompiling


Incremental Compilation

Most programs during development are composed of a "static" part that does not usually change and a dynamic part that is recompiled often. Multiple use statements are a common example of the first part of a program that may be considered static. This static portion of your program is called the "header." You may define the header of your program and compile that portion only once. The header will be automatically included, precompiled, when you compile the dynamic portion of your program. This technique can significantly reduce the time it takes to recompile a large program. It can also be used to give access to part of the source code of a program to users while keeping another part inaccessible to them.

You may define a header of your program for precompilation with the #HEADER and #ENDHEADER commands. When you compile a program with these commands with the P option, only the header will be compiled and the files ProgramName.FLD, ProgramName.PBG, ProgramName.PKD and ProgramName.PRP will be produced. When you compile the program without the P option, the .FLD will be included and the header will not be recompiled. Only the portion of your program after the #ENDHEADER will be compiled. As portions of your program become complete and tested you may move them into the header and recompile the header. It is your responsibility to make sure that the header is recompiled (with p) every time it changes. For example:

#HEADER

Use Windows.pkg

Use cMyCustomGrid.pkg

#ENDHEADER

:

Object oMyCustomGrid1 is a cMyCustomGrid

:

End_Object

See Also

Precompiling


The Rules of Precompiling

  • Forward references are allowed from the first program (or header) to the second. So, in the first you could declare an object in the second program (or header) and access it in the first.

  • All symbols, variables, objects, and files are carried forward from the first program to the second, just as if the program where compiled altogether.

  • The precompiled portion must compile without (compile-time) errors.

  • Command blocks and object definitions may not span the program files or header. In general, anything you begin in the first part you must complete in the first part.

  • The files .FLD, .PBG and .PKD must be accessible to load the file. If the first part can't be found in these forms, a .PKG extension will be added and the file of that name #INCLUDEd in the program being compiled (defeating the benefits of precompilation).

  • Only one use command may load a program in this way. Other use commands will #INCLUDE the file as source, recompiling it, regardless of whether the used files have been precompiled.

  • The use or #HEADER command must be the first line of the program (excluding comments). If you have both a use and #HEADER, the use command would go after the #HEADER.

See Also

Precompiling


Compiler Directives

Macros can be defined directly within one or more programs or packages. Macros defined within a program will operate only within that program when executing. The definition must appear in the source code before the defined macro is first used. Definitions added to packages, on the other hand, will make the new macro available to every program that uses the package.

For detailed information on all compiler directives, see Compiler Directives in the Language Reference book.