Synergy Prototype utility (dblproto)

WTSupported in traditional Synergy on Windows

 

USupported on UNIX
VSupported on OpenVMS

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

The Synergy Prototype utility has the following syntax:

dblproto [options] sourcefile [...]

Arguments

options

(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. The main purpose of this option when prototyping is that if your Synergy files do not have namespaces, they will be assigned to the default namespace, which is the first specified by ‑qdefns.

‑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.

‑single

Prototype multiple source files (for example, ‑single *.dbl or ‑single a.dbl b.dbl c.dbl) one file at a time instead of as a compilation unit. This option is deprecated and should not be used.

‑? 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.)

Note

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

Note

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.

Tip

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 versionfor additional information on this feature. Valid values for value and the Synergy version they correspond to are listed below:

90501 for version 9.5.1

90503 for version 9.5.3

100101 for version 10.1.1

10010101 for version 10.1.1a

10030100 for version 10.3.1

10030101 for version 10.3.1a

10030102 for version 10.3.1b

10030103 for version 10.3.1c

10030300 for version 10.3.3

10030301 for version 10.3.3a

10030302 for version 10.3.3b

10030303 for version 10.3.3c

10030304 for version 10.3.3d

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.

1. If you want to specify a default namespace to use for prototypes that do not have a namespace, set SYNDEFNS to the desired namespace. (Or specify it with ‑qdefns on the dblproto command line.) If a default namespace is not specified, synglobal will be used.
2. 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.
3. 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.

4. 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:

See also