Synergy Prototype utility (dblproto)

The Synergy Prototype utility generates prototype files (.dbp), which can be used for two purposes:

To strongly prototype Synergy code, which ensures that routine calls and non-private types (structures that aren’t inside a routine, classes, enums, etc.) match their definitions and enables you to detect more problems at compile time rather than waiting until runtime

To make declarations within a namespace available to other Synergy source files via the IMPORT statement

Strong prototyping is required for object-oriented code, and it happens automatically within a compilation unit. However, outside a compilation unit, such as when you use multiple dbl commands, prototype checking is not automatic, and you will need to generate prototypes.

The Synergy Prototype utility has the following syntax:

dblproto [option] sourcefile [...]

Options

option

(optional) One or more of the following. The equal sign is optional; you can use a space instead.

-expdir=directory

Specify the export directory for the generated prototype file, where directory is either a full directory specification or an environment variable that contains a directory location.

-N

Process decimal type arguments as numeric (equivalent to setting system option #28).

-out=file

Specify the name of the prototype file to generate. If .dbp is not the extension, it is added.

-platform=type

Specify 32- or 64-bit object file creation, where type is x86 for 32-bit platforms or x64 for 64-bit platforms. If not specified, defaults to the bitness of the machine.

-qdecargs

Convert all decimal type arguments to numeric type.

-qdefine:identifier1=value1[,identifer2=value2,...]

Set compile-time defines, where identifier is the name of the identifier being defined and value is the replacement text.

-qdefns=namespace[;namespace;...]

Specify namespaces to be imported automatically. This option overrides the setting for SYNDEFNS.

-qimpdir=importdir[,importdir,...]

Specify directories that the compiler will search for IMPORTed namespaces. This option does not override the SYNIMPDIR setting. Rather, if SYNIMPDIR is also specified, the -qimpdir directories are searched first, then the SYNIMPDIR directories.

-quserdef=file

Specify a file to include when compiling. This option overrides the setting for SYNUSERDEF.

-qrelaxed=opt[:opt]

Set -qrelaxed options, where opt is end or extf. The following -qrelaxed options are set by default and cannot be changed: allowdup, deprecate, interop, local, param, path. With the exception of allowdup (which will cause an error), you can put any of these on the dblproto command line, though it would be pointless to do so. Note that -qrelaxed=end is the same as the -qrelaxedend option; consequently the only real use for -qrelaxed is to set extf. (See Relax strong prototyping and error checking for details about the effect these options have.) You can substitute a colon (:) for the equal sign (=).

-qrelaxedend

Change the behavior of the END statement to clear .DEFINEs at the end of the routine instead of at the end of the file.

-qrntcompat=value

Target an earlier version of the Synergy runtime. See Targeting an earlier runtime version (-qrntcompat) in the Discussion for valid value options. (Windows, UNIX only)

-qvariant=value

Define an internal compiler variable that can be retrieved with ^VARIANT.

-? or -h

Display dblproto command line options and usage information.

sourcefile

The name of one or more source files to be prototyped. The default filename extension is .dbl, and wildcard characters are valid.

You can alternatively specify a redirected input file in the format < file, where file contains a list of files to be prototyped. Wildcard characters are not valid with this format. For Windows and UNIX, -T is valid (as described in Redirecting compiler commands from a file on Windows and UNIX). Within the input file, continuation lines are determined by a trailing minus sign (-) on the previous line.

Discussion

The Synergy Prototype utility creates a single prototype file that contains prototypes for all subroutines, functions, and classes in the source files being prototyped.

When you change your source code, you should regenerate prototypes. For best results, delete the original .dbp file(s) before regenerating.

If -out is not specified, the file is named with the name of the first source file on the command line. The extension is .dbp. If you use a wildcard to process multiple .dbl files in a directory, they are processed in alphabetical order, and the .dbp file will be named with the filename of the first file processed. (This means the prototype filename could change next time you run dblproto if you add or remove source files.)

The .dbp files are binary and cannot be moved from one endian system to another.

The export directory is determined by the following precedence order:

The location designated by the -expdir option, if -expdir is specified
The location designated by the SYNEXPDIR environment variable, if SYNEXPDIR is defined

The current directory

For performance reasons, prototypes should not be located on a network share. In addition, we recommend that you exclude the .dbp files, as well as dblproto.exe and dblproto64.exe, from virus scanning.

The Synergy Prototype utility supports a number of options that correspond to compiler options (-qdefine, -qvariant, etc.). This is because in order to generate prototypes, dblproto must do some of the same processing that the compiler does. Generally speaking, these options should be set the same way you set them when compiling (though this may not be possible for -qrelaxed, since dblproto sets a number of -qrelaxed options for you).

The Synergy Prototype utility ignores blocks of source code between a .NOPROTO directive and either a matching .PROTO directive or the end of the source file. It automatically encloses all prototypes between a pair of .NOLIST-.LIST directives to prevent prototypes from being sent to the listing file.

If errors occur during dblproto processing, they are reported but prototypes are still generated. We recommend that you fix these errors to avoid future problems when compiling or linking.

Prototyping a large number of files may exceed the memory capacity of 32-bit machines. If you need to output 32-bit dbp files, we recommend using the 64-bit version of dblproto (on a 64-bit machine) and specifying -platform=x86 to generate 32-bit files.

Targeting an earlier runtime version (-qrntcompat)

(Windows, UNIX only) The -qrntcompat=value option enables the compiler to target an earlier version of the runtime. If you will use this option when compiling the code that uses the .dbp file, you must also use it when generating that .dbp file. Note that the prototypes generated with -qrntcompat cannot be used with an earlier version of the compiler; they must be compiled with the current compiler. See Targeting a specific runtime version for additional information on this feature. Valid values for value and the Synergy version they correspond to are listed below:

90501 (9.5.1)

90503 ( 9.5.3)

100101 (10.1.1)

10010101 (10.1.1a)

10030100 (10.3.1)

10030101 (10.3.1a)

10030102 (10.3.1b)

10030103 (10.3.1c)

10030300 (10.3.3)

10030301 (10.3.3a)

10030302 (10.3.3b)

10030303 (10.3.3c)

11010100 (11.1.1)

11010104 (11.1.1d)

12010100 (12.1.1)

12030100 (12.3.1)

Implementing strong prototyping

If you generate prototypes for your source files and tell the compiler where to find them (by setting SYNIMPDIR), prototype checking will take place automatically when you compile. As of 10.3.3, you do not need to IMPORT prototypes to use this feature. Prototypes that do not have a namespace use the global namespace, synglobal.

Set the SYNEXPDIR and SYNIMPDIR environment variables to the same path. The prototype file will be generated to the SYNEXPDIR directory and then the compiler will search in the SYNIMPDIR directory. (You don’t have to make these two environment variables point to the same directory, but it is more efficient to do so.) Optionally, you can specify the export directory on the command line with -expdir and the import directory with -qimpdir.

Run dblproto on your .dbl files. For the -out value, specify a unique filename. For example,

dblproto -out=Fred myfile1.dbl myfile2.dbl

Or, use a wildcard character to prototype all the files in the directory:

dblproto -out=Fred *.dbl

The output file, Fred.dbp, will contain prototypes of all the functions, subroutines, structures, and classes in myfile1.dbl and myfile2.dbl (or, in the second example, all .dbl files in the directory). It will be created in the directory specified with SYNEXPDIR.

Compile your program. The compiler will look in the SYNIMPDIR directory and perform prototype checking against any source files in the compilation unit for which there is a prototype.

Handling source files in multiple directories

When prototyping sources in multiple directories, you have two options:

Place each prototype file in its respective source directory. Do not set SYNEXPDIR; rather, use the -expdir option to specify the directory for each file. Then, set SYNIMPDIR to point to all the directories where files were created.
Place all the prototype files together in a separate directory. Specify this directory with SYNEXPDIR and set SYNIMPDIR to point to the same directory. This method is simpler in that SYNIMPDIR needs to refer to only one directory, but you must take care that the .dbp files have different filenames. If you use this method, we recommend you always explicitly specify a filename with -out.