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:

Module
(Windows)
Module
(UNIX)
Contents
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
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
  DSUXSYSP.o
DSVRSCRN.o
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
Windows
UNIX
All Dialog System applications dscrun.obj
dsfld.obj
dsadskey.obj
dsrtns.obj
DSCRUN.o
DSFLD.o
DSTERM.o
DSLCONV.o
DSUSRCAL.o
DSUXSYSP.o
Applications using field validation dscvalrn.obj
dserrhan.obj
DSCVALRN.o
DSERRHAN.o
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
Windows
UNIX
Applications that use the trace facility dstracer.obj
dsdlgini.obj
DSTRACER.o
DSTRACER.o
Applications that call Dialog System via the Trap dsc.obj
dsgetss.obj
DSC.o
DSGETSS.o

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

Windows:
To link your program on Windows systems, use the following command line:

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

where:

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.

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:

dsrun.obj
dscrun.obj
dsfld.obj
dsadskey.obj
dsrtns.obj

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

Examples

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

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

cob -xv prog module-name...

where:

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 as a Windows 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.bat (Windows), 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.bat to create Windows Dschar executables.

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

Examples

Windows: 
dsclink customer+extfh+dsusrfmt

Creates customer.exe for Windows 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 © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousProgramming PrintingNext