GUI ScreenIO for Windows

ScreenIO.com

GnuCOBOL

Copy the file GS.COB from the GUI ScreenIO installation directory to wherever you keep your COBOL program source code. (Click Here for a copy of GS.COB).

Launch your COBOL programming editor.  Almost any text editor will do.

Open GS.COB so that you can edit it.

Examine the source code (it's pretty simple, most of it is comments). The comments at the beginning of the program explain what you need to do.  Remove the comments from the GnuCOBOL sections of code as shown below. 

DATA DIVISION

You need to uncomment the following lines in the DATA DIVISION to specify the linkage convention used to call GUI ScreenIO.  These are clearly marked with GnuCOBOL in the comments.

PROCEDURE DIVISION

Be sure that the source code for other compilers is commented out or removed.

Save GS.COB.

Compiling GS.COB

Note: This section isn't about how you call GS from your program, it is about how compiling and linking GS.COB so that it calls the GUI ScreenIO Runtime properly.  After this is done once, you can call GS from your application just like any other subroutine.

You can compile GS.COB as a Statically Linked Subroutine (OBJ) or as a DLL.  GS is very small and won't affect your application size either way.

In either case you must assure that GS.COB is linked in such a way that the GUI ScreenIO runtime entry points are linked into GS STATICALLY and not DYNAMICALLY searched for at run time. 

In most cases, simply performing the modifications to GS as indicated above will accomplish this, and you need not worry about it.  However in rare cases other compiler options may have been chosen that might override this static linking.  In this case -fstatic-call option can be specified when compiling GS.COB.

We generally recommend you set the environmental variables for working with GUI ScreenIO projects:  

SET COB_STDUNIX=NO

SET COB_LDFLAGS=/SYBSYSTEM:WINDOWS    (Without this you will get a dos-box popping up each time you run your application)

Without the -fstatic-call directive, the compiler and linker may choose to set up calls each subroutine dynamically, as if they were all compiled as DLLs (ignoring the fact that the call was to a literal.  This makes for some runtime crashes when the DLLs are not found, and makes distributing your application more complex as you need to include many more DLLs.   See Static and Dynamic calls. While this is simply an efficiency concern for your applications, it is critical for the linking of GS.COB.  Compiling GS.COB to a DLL removes any restrictions on how your application is linked, and you need worry about it only once.  

You will need to use GS32.lib while linking GS.COB to a DLL.  (See Dynamic Calls below).  You would then never have to include Gs32.LIB while compiling or linking your application.

 If you compile GS.COB to an OBJ, you will need to include GS32.LIB whenever you compile your application's EXE or DLL files.  (The easiest way to do this is to copy GS32.LIB into the same folder that contains GnuCOBOL's .lib files.

Differences from other Compilers

The GnuCOBOL compiler on the Windows Platform translates COBOL to C code, and then compiles it with the free Microsoft C compiler.  

Because of this translation to C, the compiler is designed to handle Linking as well as compiling.  While it is possible to work around this and use your own linking commands and batch files, its often problematic and not worth the effort.  We therefore recommend (at least initially) using the compiler to perform linking in the way intended by the compiler's authors.

The compiler also determines that types of files it was handed, and deals with them appropriately.  Therefore if you invoke the compiler with a Link flag (-m or -x) and the name of a COBOL source file (.COB,.CBL) it will compile it then link it.  If called with an object file (.OBJ) it will simply link it. 

Similarly, if you provide the name of Obj Libraries (.LIB) those libraries will be added to the list of libraries searched for subroutines.  

At a minimum you will need to include GS32.LIB when linking GS.COB to a DLL for calling dynamically.  Then, when GS is called from your programs you will not have to mention GS32.LIB when compiling.  It will be found at run time automatically.  This is often the easiest way to do it.  

However,  when linking your main program which calls gs.cob as a static call (when gs.cob was previously compiled to an obj) you will need to include GS32.LIB in all compile and link commands. 

See the samples below.

STATIC CALLS:

To compile GS.COB to an OBJ (for statically linking to your programs) use the following example

     cobc -c -o gs.obj gs.cob

This says to compile gs.cob to an obj named gs.obj.  You will need to save gs.obj.  You would call gs.cob in your program as follows:

     CALL 'GS' USING ... ... ...

DYNAMIC CALLS

If you prefer to call gs.cob as a dynamically called program (DLL), use the following compile command instead:

     cobc -m -o gs.dll gs.cob gs32.lib

This says to compile gs.cob to a DLL namded GS.DLL and to link it with GS32.LIB (which we supply).  If done this way all subsequent calls to GS.DLL should be coded as a call to a data element as in the following example:

     01  MY-SCREEN-HANDLER          PIC X(8) VALUE 'GS'.
            ...
         CALL MY-SCREEN-HANDLER USING ... ... ... 

Note that in the case where you decide to call GS as a DLL, you can eliminate the -fstatic-call on all compiles (except GS.COB), and you would not need to mention GS32.lib on any link command (except when compiling GS.COB).  This simplicity is the Main Advantage to compiling GS as a DLL.

Using an OBJ Library (strongly recommended)

Note:  Much of the GnuCOBOL documentation uses terminology from the Linux world.  Specifically this can lead to confusion when talking about library files in the Windows environment.  In the Microsoft world, a .LIB file is a file containing one or many .OBJ files, which are the result of compiling one or more subroutines.  In the Linux world the word library is often used to refer to any collection of files in simple directories holding executable files in one of several forms. 

GnuCOBOL, in some versions, simply tosses those .OBJ files all into a directory and usually calls them dynamically.  This can be quite slow, and linking those obj files renders much faster code, and putting these in a .LIB file facilitates linking.  It also makes development and shipping your application easier. You can link them all together and ship one large .EXE file.  

If you have a number of statically called subroutines that are called from many places in your application (such as file handlers) it is often convenient to place all such subroutines in a library file (.LIB).  If you do this, GS.OBJ can be placed in that library file as well, eliminating the need to remember to add it on every compile and link operation.  This goes a long way toward simplifying the development effort. 

You can see that if you have 10 or 30 such subroutines, linking all of them can become very problematic with complex command lines listing every sOBJ that needs to be included in the DLL or EXE you are creating.  You would have to remember which DLL or EXE needs which list of subroutines and add them to the command line when compiling.  That's ok if you only developed small systems.  Its unmanageable for any large application.

The alternative of using DLLs for all subroutines is equally messy, and pushes missing DLL problems down to the end-user, rather than discovering them at link time. 

Adding the .OBJ modules  of all such subroutines to a .LIB solves this, because the linker will find only the ones needed when linking any EXE or DLL.  The computer should work for you, not the other way around.  Let the computer find missing stuff at link time, rather than you having to set up complex compile commands.

To add any obj file to a library, simply use the LIB command.  GnuCOBOL does not do this automatically (as of this writing), but since LIB is provided by the C-Compiler which is required by GnuCOBOL, you can simply add your subroutines to a user obj library as follows

   cobc -c -o gs.obj gs.cob
        LIB /OUT:MYLIBRARY.LIB gs.obj    (for the first subroutine - you usually do this once)
   LIB MYLIBRARY.LIB sub1.obj sub2-obj ... ... (to add others) 

After this you could sub1.obj, and sub2.obj from your working directory and reduce the clutter because they are safely tucked into the .LIB file.

Subsequent compilations of your Main Program (or DLLs) would then simply mention these .LIB files:

    cobc -x -o mymain.exe mymain.cob mylibrary.lib  gs32.lib 

Bear in mind the Microsoft Library manager (LIB) is easier to manage if it is run from the directory with the lib and obj files.

Note that there may be ways of specifying LIBs to be used when linking without the need to include them on each compile/link command.  In the past this as been hit or miss and therefore these examples show the brute force method.  

Other Compilation Conventions

Not strictly required, but highly suggested compiler conventions we use with GUI ScreenIO are as follows.  These can be placed in a Config file for your compiler and mentioned on each compile line, or simply added to the bottom of default.conf in your compilers installation directory.  

Note that BinaryByteOrder Native is required by windows on Intel processors. (x86 or x86_64).  (Bold entries below are required for GUI ScreenIO):

assign-clause: ibm
pretty-display: no
complex-odo: yes
indirect-redefines: yes

binary-size: 2-4-8
binary-byteorder: native
binary-truncate: no

perform-osvs: yes
sticky-linkage: no

top-level-occurs-clause: ok
eject-statement: ok
entry-statement: ok
relax-bounds-check: no
next-sentence-phrase: ok
relax-level-hierarchy: yes 

A note on computer Set up

For simplicity we have shown the compiler command as if you were using a command prompt (dos box) and sitting in the directory with your source code.

With such an environment you would find all of the compiler output and work files will placed in that same directory.  In reality this is a very messy setup, and you will find all sorts of files dropped into this directory by the compiler.  It will become unmanageable in short order.

We recommend that you set up a specific directory, separate from your source directory, for compiler output.  You might for instance use a directory named C:\compilerwork\ABC-project for storing compiled object modules, LIB files, and generated .EXE and .DLLs.  This directory will also accumulate a fair amount of other compiler work files which you don't need to retain.

You could set an Environmental Variable to hold this location:  SET WRKDIR=C:\compilerwork\ABC-project .  

Then using the compile commands we've shown above (or a batch file) to compile, you would simply pre-pend %WRKDIR% in place of any arguments referencing files other than source files:  cobc -c -o %wrkdir%gs.obj gs.cob.  

You would them move or copy only ONLY the EXEs and DLLs to your production directory when you are satisfied with your product.  You would of course also need to distribute the Compiler's runtime DLLs and the GUI ScreenIO runtime DLLs in your production directory and use that directory as the source for distribution your application.

Related topics:

• Problems Getting Started