PreviousProgramming PrintingNext"

Chapter 13: Linking

The eleventh, optional, step in creating your Dialog System application, is to link Dialog System object modules to your application to create a single executable object.

This chapter explains:

13.1 Dialog System Object Modules

The following Dialog System object modules are provided:

(DOS, OS/2)
dsrun.obj DSRUN.o Standard entry module to Dialog System (character and graphical)
dscrun DSCRUN.o Interface to character DSCHAR
dsfld.obj DSFLD.o Screen field handler
dsadskey.obj   Keyboard handler
dsrtns.obj   Service routines for shifting and filling data
(DOS, OS/2)
dscvalrn.obj DSCVALRN.o Field validation routine
dserrhan.obj DSERRHAN.o Error file handler
dstracer.obj DSTRACER.o Dialog trace routine
dsdlgini.obj DSGLINI.o Initialization for trace routine
dsc.obj DSC.o Replacement for Dsrun if the application calls Dialog System via the Trap
dsgetss.obj DSGETSS.o Loads screensets
  DSTERM.o Terminal type dependencies
  DSLCONV.o Native line drawing routine
  DSUSRCAL.o User routine interface
System file locator
Handles variable screen size for menu placement
dscomp.obj DSCOMP.o Comp data type handler
dspanels.obj PANELS.o Micro Focus panels
dsnlsrtn.obj DSNLSRTN.o NLS support routine - needed only if NLS case-folding is required
  DSUSRVAL.o User validation
  DSUSRFMT.o User field formatting

Depending on the features your application uses, you might not require all of these object modules. Under UNIX, use -X module-name to exclude any such modules. The following sections list the object modules that production applications and applications in development require.

13.1.1 Production Applications

The following table lists the object modules required by production applications:

Application Type
All Dialog System applications dscrun.obj
Applications using field validation dscvalrn.obj
Applications using user validation dsusrval.obj DSUSRVAL.o
Applications using comp, comp-x, comp-5, comp-3 data types dscomp.obj DSCOMP.o
Applications using field formatting dsusrfmt.obj DSUSRFMT.o
Applications using Micro Focus PANELS dspanels.obj PANELS.o

13.1.2 Applications in Development

The following table lists the object modules required by applications in development:

Application Type
Applications that use the trace facility dstracer.obj
Applications that call Dialog System via the Trap dsc.obj

For more information about using trace, see the section Using the Trace Facility in an Executable Object.

When you have fully tested an application, you should re-link the application without any of these modules to create a smaller production object.

13.2 Linking Your Application

DOS and OS/2:
To link your program on DOS or OS/2 systems, use one of the following command lines:

link prog+@ds-link-file,prog,,coblib+os2;
link prog+@ds-link-file,prog,,coblib;


prog is the name of your application.
ds-link-file is the name of a linker response file. This is a text file that contains a list of all the Dialog System object modules to be linked to your application.

If you are using file handling, you must link in ExtFH. If you are using user formatting, you must link in Dsusrfmt. If you are using user key translation, you must link in Dsusrtrn.

Your OS/2 system might contain the file doscalls.lib instead of os2.lib.

The following linker response files are provided with Dialog System:

dsc.lnk Contains all the object modules listed in the section Dialog System Object Modules except those that are required for debugging purposes only. If you use this file, your application definitely has all the dialog objects that it needs. However, if your application does not use all the Dialog System features (such as field validation), you create a larger object than is necessary.
dscbasic.lnk Contains only those modules that are required for any Dialog System application to run, which are:


dscdebug.lnk Contains all the object modules required for debugging a Dialog System application.


link customer+extfh+dsusrfmt+dsc.lnk,customer,,coblib+os2;

Links ExtFH and Dsusrfmt for file handling and user formatting.

link customer+extfh+dsusrfmt+dsc.lnk,customer,,coblib;

Links ExtFH and Dsusrfmt for file handling and user formatting.

You can, of course, create your own custom linker response file.

See your COBOL System Reference for a details of linker and linker response file syntax.

To link your program on UNIX, use a command line of the form:

cob -xv prog module-name...


prog is the name to be given to the executable object
module-name is the name of an object module to be linked into the object.

13.2.1 Using Dsclink for Linking

Dsclink is a utility that generates the appropriate linker files and calls the linker to create an executable file. You can use it directly or use it as a template for your own linking procedure to suit your application. It is supplied both as an OS/2 command file and a DOS batch file.

dsclink object-name[+object-name...] /d /t /nc /nv /p /nls /st

where the parameters are:

object-name An object name. The executable (.exe file) is given the same name as the first object filename. You can specify multiple object names by concatenating them with the plus sign. You cannot specify a linker response file in this list because Dsclink creates one and you can use only one as input to the linker.
/d Debug version. Specify this parameter to use the Trap option, which also enables you to use Trace.
/t Trace version. Specify this parameter to use the Trace option without the Trap. If you also specify the /d parameter, it overrides the /t parameter.
/nc No COMP support.
/nv No field validation support.
/p Panels support.
/nls National Language (case folding) support.

If you use the supplied utility dsclink.cmd (OS/2) or dsclink.bat (DOS), a switch allows you to control this simply.

The linker file DSC.lnk has also been amended to include reference to these NLS supporting .obj files.

/st Static linked application (lcobol). Default is shared run-time linked application (coblib).

Use dsclink.cmd to link Dschar executables for OS/2. By default, dsclink.cmd creates an executable for production and includes field validation and COMP support but excludes Panels support.

Use dsclink.bat to create DOS Dschar executables.

Before linking, ensure your LIB environment variable contains the paths to ...cobol\lib, ...ds\charmode, ...OS2 (for doscalls.lib), and any other libraries that your application requires.


dsclink customer+extfh+dsusrfmt

Creates customer.exe that includes field validation and COMP support, and links ExtFH and Dsusrfmt for file handling and user formatting.

dsclink customer+extfh+dsusrfmt

Creates customer.exe for DOS that links ExtFH and Dsusrfmt for file handling and user formatting.

13.3 Using the Trace Facility in an Executable Object

You might wish to use the trace facility while you test an executable object. To do this, add code to your application to turn the trace facility on or off, using the following steps:

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousProgramming PrintingNext"