GUI ScreenIO for Windows

 ScreenIO.com


COBOL-IT (or OPENCOBOL)

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 COBOL-IT 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 COBOL-IT and OpenCOBOL comments.

 SPECIAL-NAMES.
*--> Decomment following line for: COBOL-IT or OPENCOBOL <--*
     CALL-CONVENTION 74 IS WINAPI.   

PROCEDURE DIVISION

 0001-PASSTHROUGH-CALL.
*----------------------------------------------------------
***--> COBOL-IT and OpenCobol <--*
* Note: Decomment the appropriate entry in SPECIAL-NAMES.
*
* CALL WINAPI 'GS32' USING BY REFERENCE A B C D.
* IF CLOSE-AND-STOP-MANDATORY GO TO 0002-SHUTDOWN-MANDATORY.
* GOBACK.
* ENTRY 'GSWINAPI' USING W A B C D E F.
* CALL WINAPI 'GSWAPI' USING BY REFERENCE W A B C D E F.
* GOBACK.

 

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

Save GS.COB.

Compiling GS.COB

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

In either case you must compile GS.COB using the directive -fstatic-call to ensure that the GUI ScreenIO runtime entry points are linked into it and not searched for at run time.

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

SET COBITOPT=-fstatic-call

SET COB_STDUNIX=NO

SET COB_LDFLAGS=/SYBSYSTEM:WINDOWS 

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.

Note:  You must use OBJ or DLL forms if your application will call GSWINAPI to access the Windows APIs that GUI ScreenIO provides.  You will need to use GS32.lib while linking.

Differences from other Compilers

The COBOL-IT compiler on the Windows Platform translates COBOL to C++ code, and then compiles it with the free Microsoft C++ compiler.  Be sure you execute the supplied setenv_cobolit.bat that came with the COBOL-IT compiler so that the Microsoft C compiler will be properly integrated into your work environment.

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.  This will be necessary to instruct the linker to include GS32.LIB while linking your application.  

At a minimum you will need to include GS32.LIB when linking GS.COB to a DLL, you will need to include GS32.LIB in all link commands.

Also,  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 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 is the only advantage to compiling GS as a DLL.

Using an OBJ Library

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

You can see that if you have 10 or 30 such subroutines, linking all of them can become very problematic with complex command lines.  You would have to remember which DLL or EXE needs which list of subroutines and add them to the command line when compiling.  

The alternative of using DLLs for all subroutines is equally messy, makes for a slower run time, 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 an 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.

To add any obj file to a library, simply use the LIB command.  The Compilers do not do this automatically (as of this writing) but since LIB is provided by the C-Compiler which is required by COBOL-IT and OpenCobol, 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)
   LIB MYLIBRARY.LIB sub1.obj sub2-obj ... ... (to add others)

 

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 

(Nothing prevents you from adding your subroutines to a COPY OF GS32.LIB and therefore having only one library to mention.  Don't clobber your only copy of GS32.LIB.  GS32.LIB is very stable and has not changed for years, but is subject to change on any upgrade to GUI ScreenIO.  So while this is possible, we don't recommend it.  Create your own library instead.).

Bear in mind the Microsoft Library manager (LIB) is easier to manage if it is run in 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:


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom