After you’ve compiled the source files for your program, you must combine the resulting object files into a single module that can be executed by the Synergy runtime. This step is accomplished using the Synergy linker.
On Windows and UNIX, the dblink command starts the linker. Additional methods you can use in a Windows environment to invoke the dblink command are explained in Methods for invoking commands on Windows.
On OpenVMS, use the OpenVMS LINK command to link your object files. Invoking the linker on OpenVMS (LINK) explains how to use this command in greater detail.
Invoking the linker on Windows and UNIX (dblink)
dblink [options] [--] input_1 [...input_n]
Options
options
(optional) One or more linker options and their arguments, shown in the Linker Options table. You can either precede a group of options with a minus sign (-) or precede each option with a minus sign. (For example, -eos and -e -o -s are both valid.) If an option requires an argument and that argument does not follow the option or option group immediately, Synergy DBL assumes that the option’s argument is the next undefined element on the line. For example, the following dblink commands are equivalent:
dblink -e lib mod -s 8192 input_file dblink -es lib mod 8192 input_file
In both cases, the lib mod arguments go with the -e option, and the 8192 argument goes with the -s option. The Discussion explains what happens if a required argument is omitted.
On Windows, if system option #34 is set, you must use a forward slash (/) instead of a minus sign (-) before each linker option or group of options.
|
Name |
Description |
Option |
|---|---|---|
|
Incorporate symbolic access table information in the .dbo file into the .dbr file for use by the debugger. If you don’t compile and link with this option, symbolic information won’t be available to the debugger at runtime. |
-d |
|
|
Extract |
Extract the object module mod from object library lib for use as a main routine in the current program. The default library name extension is .olb. |
-e lib mod |
|
Information |
Provide additional system-specific information to resolve the link problem if an internal error occurs. |
-I |
|
Library file |
Create an executable subroutine library named library_file. The default filename extension is .elb. |
-l library_file |
|
Map file |
Create an allocation map file named map_file. If map_file is not specified, the linker uses the name of the first input file plus the extension .map. |
-m[map_file] |
|
No output |
Do not create an output file. |
-n |
|
Output file |
Name the output file output_file. If output_file is not specified, the linker uses the name of the first input file plus the extension .dbr. |
-o [output_file] |
|
Unresolved references only |
Only include the routines from the specified object library (olb_file) that are necessary to resolve the routines in the executable library being created. This option is used in conjunction with -l (lowercase L). |
-R olb_file |
| Redirect commands | Redirect linker commands from the specified ASCII file that contains one or more command lines to be input to the linker. File cannot contain more than 2,000 characters. If -T is specified, the command line(s) will be traced, or displayed, as they are executed. See Redirecting linker commands from a file for more information. | [-T] <file |
|
Reference check |
Do not allow unresolved references to subroutines in an executable library. This option is used in conjunction with -l (lowercase L). |
-r |
|
Runtime compatibility |
Verify that the object file version is not greater than the version specified by value. (Note that object files created prior to 10.3.3 cannot have their version verified.) Value can be one of the following: 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) |
-qrntcompat= |
|
Stack size |
Set the internal operations area equal to stack_size. The default stack size is 256K. For more information about increasing the size of the internal operations area, see Expanding the Synergy DBL stack through the linker. |
-s stack_size |
|
Warning |
Allow unresolved references to subroutines in an executable program. If you don’t use the warning option when linking a Synergy program and there are unresolved XCALLs, the linker aborts and won’t create an executable file. If you do use this option, the linker creates an executable file and maps all unresolved XCALLs to an internal XCALL, which generates a “Referenced undefined XCALL” error ($ERR_NOXCAL) when accessed at runtime. |
-W |
|
Warning disabled |
Disable linker warnings. |
-wd or -w 0 |
--
(optional) Separates options from the input file list.
input_1
The first input file to be linked. The default filename extension is .dbo.
input_n
(optional) Represents additional input files to be linked. The default filename extension is .dbo. You can specify a maximum of 8192 files.
The dblink command can be used to create an executable program file or an executable subroutine library.
If you are creating an executable program file, the linker creates the executable file with the same name as the first input file listed with the extension .dbr, unless the -o option (output file) is used to specify a different name.
To create an executable subroutine library, use the -l library_file option. The linker will create the library with the name you specify. The default extension for an executable subroutine library is .elb. Note that -l can be used to link additional, existing ELBs against the ELB being created (the primary ELB), so they can be opened automatically when the primary ELB is opened. Once dependent ELBs have been linked against the primary ELB, you only need to list the primary ELB on the command line when creating an executable program. To link ELBs, list the ELBs as input files according to the specifications in Input files.
Omitted arguments
If a linker option requires an argument and no argument immediately follows the option, the linker will use the next undefined element on the line as the argument. (Linker options and the “--” separator are considered to be “defined” elements, whereas filenames or arguments to the compiler options are considered to be “undefined.”) When the linker encounters another linker option group, it stops looking for the argument(s) to the previous option(s). The default argument then becomes the name of the first input file, with the appropriate extension. Once an element has been used as an argument to a linker option, it cannot be used as an argument to another linker option.
For example, in the following command:
dblink -el libA modA libB fileA
the arguments libA (with a default extension of .olb) and modA are used by the -e option. The argument libB (with an extension of .elb) is used by the -l option. The linker uses fileA (with an extension of .dbo) as the first input file.
The input file list can include any combination of the following types of files:
- Synergy DBL object files (.dbo)
- Synergy DBL object libraries (.olb)
- Synergy DBL executable subroutine libraries (.elb)
Input filename extensions always default to .dbo. If you’re specifying object or executable libraries, you must specify the .olb or .elb extension.
|
All ELBs specified on the dblink command line (as well as all ELBs linked to those ELBs) are automatically opened when the program is started. A maximum of 256 ELBs can be open at any one time. The maximum length of an ELB file specification on the dblink command line is 31 characters. |
Synergy DBL will use the ELB filename exactly as specified on the dblink command line when attempting to open the ELB at runtime. For example, let’s assume you build a program called script with the following dblink command:
dblink -o script script misc utils.elb
At runtime, Synergy DBL will expect utils.elb to be in the current directory. Therefore, you should include a logical that defines the location of utils.elb. For example:
dblink -o script script misc UTL:utils.elb
|
We recommend that you always include a logical when specifying ELBs. Using logicals will help avoid two potential problems:
/usr/fredrina/toolkit/common/utils.elb The above file specification has 38 characters, which is too long. If the path is defined as a logical (TKUTL, for example), a shorter file specification can be used (TKUTL:utils.elb). |
Link procedure for .dbrs
The Synergy linker follows the steps below when linking executable programs (.dbr):
| 1. | Link all object files. All object files are included in the output file in the order in which they are listed on the dblink command line. |
| 2. | Process all ELB files in the order in which they are listed on the dblink command line. If an ELB references other ELBs, those ELBs are processed and added to the list of ELB files in the header of the output file as they are referenced. |
| 3. | Add all ELB routines to the list of resolved routine names. The linker allows duplicate routine names across linked ELBs; the routines are linked in the order they are specified in the ELB. |
| 4. | Look at each OLB in order of reference. Do not start processing the next OLB until no more routine names can be resolved in the current OLB. |
|
|
The linker gives ELB routines precedence over OLB routines: if a subroutine is contained in both an ELB and an OLB and both libraries are linked with a program, the subroutine will be taken from the ELB. |
| 5. | Resolve any remaining unresolved routine names from the system-supplied subroutine library, dlib.lib. |
| 6. | If any unresolved routine names still exist, generate an “Undefined XCALL references” (XUNDEF) error. If -W is specified, the undefined references are listed as warnings instead of fatal errors. |
Link procedure for .elbs
The Synergy linker follows the steps below when linking executable libraries (.elb):
| 1. | Link all object files. All object files are included in the output file in the order in which they are listed on the dblink command line. |
| 2. | Link all object libraries. All routines from each object library are included in the output file in the order in which they are listed on the dblink command line. |
| 3. | Process all ELB files in the order in which they are listed on the dblink command line. If an ELB references other ELBs, those ELBs are processed and added to the list of ELB files in the header of the output file as they are referenced. |
| 4. | Resolve referenced routine names from the OBJ and OLB files. |
| 5. | Add all ELB routines to the list of resolved routine names. The linker allows duplicate routine names across linked ELBs; the routines are linked in the order they are specified in the ELB. |
| 6. | Resolve any remaining unresolved routine names from the ELB files in the order in which they were processed. |
| 7. | Resolve any remaining unresolved routine names from the system-supplied subroutine library, dlib.lib. |
| 8. | When -r is specified, if any unresolved routine names or common symbols still exist, generate an “Undefined XCALL references” (XUNDEF) or “COMMON symbol ‘symbol name’ undefined in module module name” (SUNDEF) error. |
Runtime compatibility
If you've compiled with -qrntcompat, you must specify the same or a later value for -qrntcompat on the link line. Additional information is added to the object file (.dbo) to mark which version it was targeted for at compile time, and if an earlier version of the linker is used or specified with a smaller -qrntcompat value, the discrepancy will be caught at link time instead of runtime. For example, if a file is targeted or compiled under 10.3.3c and an earlier version is specified on the link line (e.g., dblink -qrntcompat=10010101), the error below will occur:
$ dblink -qrntcompat=10010101 file %DBLINK-F-BADCMP, Bad module compile: MAIN$FILE compiled for 10.3.3c past 10.1.1a %DBLINK-F-ABORT, Link aborted
Unresolved references
When creating an executable program file (.dbr), by default the linker does not allow unresolved external references (routines, commons, or globals) and forces all references to be resolved. To override this default and allow unresolved references, use the -W option.
When creating an executable subroutine library (.elb), by default the linker allows unresolved external references. To override this default and require all references in the ELB to be resolved, use the -r option. Then, if there are unresolved routines, commons, or globals, the linker will abort with an error and won’t create the executable library. This option can be useful if you are planning to use the ELB with xfServerPlus, because it ensures that all references have been resolved.
When .dbo and .olb files are processed, the size of any global data section is verified to ensure that the size of the referenced global does not exceed the size of the definition. If the referenced size exceeds the definition, a REFBIG warning is issued.
When references are resolved in other ELBs, those ELBs should be added to the command line so they can be searched to resolve data references and then placed in a list in the DBR or ELB file. When the program is started, those ELBs are opened automatically, as if an explicit OPENELB had been performed on them. If an ELB references other ELBs, they are opened as well (if they weren’t open already).
The -W and -r options are mutually exclusive.
For debugging purposes,
- ELBs should be linked once (using -r) with all ELBs that the program opens with OPENELB. This ensures that all references are resolved, duplicate references don’t exist, there are no duplicate globals and commons, and references to globals don’t exceed the size of the defining global data section when creating .dbr or .elb files.
- DBRs should be linked once with all ELBs that the program opens with OPENELB. This ensures that duplicate routines do not exist. If the same routine exists in multiple ELBs, the one in the first ELB in the list of open ELBs will be called.
On Windows and UNIX, dblink can be used to create an ELB from an OLB. For example, the following command will link all routines in the object library mylib.olb into the executable subroutine library mylib.elb:
dblink -l mylib.elb mylib.olb
All routines in the specified object library are included in the ELB regardless of whether the references are resolved or unresolved. To include only routines that resolve an unresolved reference when creating an ELB, link with the -R option. This option is especially useful if the object library contains many routines, because it allows you to include only the routines that are necessary to resolve references, instead of including all routines from the object library.
Expanding the Synergy DBL stack through the linker
The Synergy DBL stack is an allocated area used by the runtime to process arithmetic expressions, subroutine arguments, and invocation controls. By default, the size of the Synergy DBL stack is 256K, which should be sufficient for most programs. The minimum stack size on UNIX is 8,192 bytes. We do not recommend lowering the stack size below its default. If the Synergy DBL stack is not large enough, the runtime will generate a “Runtime stack overflow” error (STKOVR).
You can increase the size of the Synergy DBL stack on Windows and UNIX when you link your Synergy program using the -s linker option. For example, the following command will set the size of the internal operations area equal to 40,000 bytes and link recipe.dbo, index.dbo, and the Synergy DBL object library ulib.olb to create the executable Synergy DBL program recipe.dbr:
dblink -s 40000 recipe index ulib.olb
Redirecting linker commands from a file
Synergy DBL on Windows and UNIX supports continuation lines in the specified input command file, which can make this file easier to read. If you need to continue a line to a new physical line, place the appropriate continuation character at the end of the line to be continued. The standard continuation line character on Windows and UNIX is the backslash (\). In Windows environments, if you set system option #34, use a minus sign (-) as the continuation character.
For example,
-o EXE:main sub1 sub2 sub3 sub4 sub5 sub6 sub7 \ sub8 ulib.olb elib.elb
If system option #34 is set in a Windows environment, you would use the minus sign (-) as the continuation character and the file would look like this:
/o EXE:main sub1 sub2 sub3 sub4 sub5 sub6 sub7 - sub8 ulib.olb elib.elb
To input the required information into the Synergy linker from link.cmd (without tracing), type
dblink <link.cmd
Examples
In the example below, the dblink command line links the object files main.dbo and util.dbo, and any referenced subroutines in the object library ulib.olb and the executable subroutine library elib.elb. An allocation map named file.map is created, and the resulting executable program is named main.dbr.
dblink -m file main util ulib.olb MYUTIL:elib.elb
In the example below, the command line creates an executable library named util.elb, which contains all of the subroutines in the files sub1.dbo, sub2.dbo, and sub3.dbo.
dblink -l util sub1 sub2 sub3
The example below creates an executable library named mylib.elb that contains the routines sub1 and sub2 and is linked to the ELBs lib1.elb, lib2.elb, lib3.elb, and lib4.elb, and it checks for (and disallows) any unresolved external references. (We recommend using the -r option if the ELBs are being linked for use with xfServerPlus.)
dblink -l mylib -r sub1 sub2 lib1.elb lib2.elb lib3.elb lib4.elb
The following is true for the example below:
- Test1.dbl has routines sub1, sub2, sub3, sub4, and sub5. Routine sub4 has an external reference to sub4a. Routine sub5 has an external reference to sub5a. Test1.dbo contains the routines from test1.dbl.
- Test2.olb contains the routines from test2.dbl, which has routines sub4a, sub4b, sub4c, and sub4d.
- Test3.olb contains the routines from test3.dbl, which has routines sub5a, sub5b, sub5c, and sub5d.
The example below creates the ELB containing all of the routines from test1.dbo, sub4a from test2.olb, and sub5a from test3.olb. The rest of the routines from test2.olb and test3.olb are not included in the ELB.
dblink -l test1.elb -R test2.olb -R test3.olb test1.dbo
Invoking the linker on OpenVMS (LINK)
To link your object files, use the OpenVMS LINK command. To link a Synergy program, use the following syntax:
LINK [/EXE=exe_name]object_1[,object_n,...], option_file/OPT
Arguments
exe_name
(optional) The name you want to use for the resulting executable file. If you don’t specify exe_name, the linker creates an executable file with the same name as the first object file listed, with the extension .EXE.
object_1
The first object file or object library to be linked. If you specify an object library, you must append /LIB to the library name. The default filename extension for object files is .OBJ. The default extension for object libraries is .OLB.
object_n
(optional) Represents additional object files or object libraries to be linked. If you specify an object library, you must append /LIB to the library name. The default filename extension for object files is .OBJ. The default extension for object libraries is .OLB.
option_file
A file that contains special directions to the linker. A template option file for the Synergy runtime, SYNRTL.OPT, is located in SYS$SHARE.
Discussion
The SYS$SHARE:SYNRTL.OPT file is a template linker options file that enables you to link programs against the Synergy runtime library. (You must use a linker options file when linking against shared images.)
Input files
The input file list can include any combination of the following types of files:
- Synergy DBL object files (.OBJ)
- Synergy DBL object libraries (.OLB)
- Other language object files or object libraries
- Option files, which can contain other libraries, shared images, and symbol tables
Input object filename extensions always default to .OBJ. Input object library extensions always default to .OLB. /LIB must be appended to each library file specification.
Link procedures
Refer to your OpenVMS linker manual for a description of the linker algorithms.
Break points
You can set debugger break points in modules inside shared images. Before you do so, add the following line to the linker options file:
$ELB_DBG=data
In addition, when you link the shared image, include the module DBLDIR:ELB.OBJ.
See SET for more information about setting break points.
Note that you can only have one shared image in any link command using ELB.OBJ. For example, if you link a shared image with this module, you can’t reference additional shared images that are also linked with this module, or you’ll get a “Duplicate symbol” warning.
Examples
The following example links the object file FRED and the object library WND:APLIB into an executable file named FRED.EXE.
$ LINK FRED,WND:APLIB/LIB,SYS$SHARE:SYNRTL/OPT
The next example links the object file DBLSORT into an executable file named SYS$SYSTEM:DBLSORT, with the library DBLTLIB and shared images SORTSHR and SYNRTL.
$ LINK /EXE=SYS$SYSTEM:DBLSORT DBLSORT,SYS$INPUT:/OPT SYS$SHARE:DBLTLIB/LIB SYS$SHARE:SORTSHR/SHARE SYS$SHARE:SYNRTL/SHARE
