This document serves as both a user's and programmer's guide for the GnuCOBOL Interactive Compiler (GCic) program. It is intended for those that wish to use, customize, support, and/or enhance that program.
| User's Guide | Programmer's Guide | |
|---|---|---|
This document and the source code for the GCic program is copyright © 2022 and may not be supplied or any part thereof, embedded or as a separate element, in any program language or form, with any COBOL compiler other than GnuCOBOL ® without the express authority of the copyright holder.
It's usage in conjunction with the COBOL compiler known as GnuCOBOL is herewith granted to all users of said product unconditionally.
Documentation Copyright © 2022 Gary L. Cutler
Permission is granted to copy and distribute this document under the terms of the GNU Free Documentation License, version 1.3 or later published by the Free Software Foundation with no Invariant Sections, Front-Cover Texts, and no Back-Cover Texts other than those originally supplied. A copy of the license is availalable at https://www.gnu.org/licenses/fdl-1.3.en.html.
TOPI would like to thank you for downloading GCic and giving it a look. I hope you find it useful.
I would also like to thank the GnuCOBOL team for developing and supporting such an amazing product.
Finally, special thanks go to Vince B. Coen, who's "cobxref" tool has proven so valuable to so many of us. Vince - thank you too for the suggestions you made during the development of V2.0 of GCic.
If you have any questions, comments, or would like to report a bug, you can contact me through the Sourceforge GnuCOBOL support site. TOP
The GnuCOBOL Interactive Compiler, or GCic, program provides an interactive Textual User Interface (TUI) to the process of compiling and (optionally) executing a GnuCOBOL program. IT DOES NOT REPLACE THE COBC COMPILER THAT IS PART OF GNUCOBOL, but rather provides an easy-to-use front-end to it.
GCic has been designed to be compiled and run from the following environments:
These Unix-emulation environments are the typical choice for installing GnuCOBOL on Windows, with MinGW far more common than Cygwin.
It is possible to install GnuCOBOL using native Windows components, and GCic can be compiled for such an environment.
GCic has been successfully run on MacOS (formerly OSX) systems all the way back to "Mountain Lion".
These environments are also suitable to host GCic.
GCic uses some specific features of GnuCOBOL 3.1 and may not compile or function optimally on releases of GnuCOBOL prior to 3.1. It is fully compatible with release 3.2 of GnuCOBOL. It is not designed for use with ANY release of OpenCOBOL.
TOPThese instructions assume that GnuCOBOL 3.1 (or greater) is installed and is fully operational on your computer. To install GCic on your system:
gcic.cbl
gciclock.cbl
gcic-readme.html (you're reading this now)
gcic.ico and gciclock.ico (Windows, Windows/Cygwin, and Windows/MinGW users only), or...
gcic.jpg and gciclock.jpg (MacOS, *NIX users only)
...to the folder of your choice on your computer. The purpose of the two image files will be made clear in the After Compiling gcic.cbl Or gciclock.cbl section.
cmd.exe (or console or terminal, whichever is appropriate for your computer's OS) window on your computer and cd to the folder into which you copied the above four files.
cobc -x gcic.cbl
cobc -x gciclock.cbl
gcic-readme.html file to ANY folder that exists in your system's PATH. As a recommendation, copy them to the same folder the GnuCOBOL compiler executable resides in.
gciclock.cbl as the one and only argument. One of three things will happen:
GCic was unable to recognize your OS automatically. Just follow the procedure it asks for on the screen, using a value of 1 for Native Windows, 2 for Windows/Cygwin, 3 for Unix/Linux, 4 for MacOS, or 5 for Windows/MinGW; recompile gcic.cbl, copy the new executable to the same folder you used in step #4 and repeat step #5.
GCic was unable to resize your console window automatically. Increase the window size until it reaches the requested dimensions (at a minimum), and repeat step #5.
$SET statements in the ENVIRONMENT DIVISION of the MAIN program (the first in the gcic.cbl file) along with the Customizing GCic instructions in this document.
gcic program-filename
The argument is the name of the file containing the GnuCOBOL program(s) to be compiled, including any PATH information needed to locate the file. That is the only file you may specify on the command-line and there are no switches to specify, unless debugging features have been enabled. You will have the chance to enter additional files to be compiled or linked on the screen GCic displays.
Additionally, many premium text editors or Integrated Development Environments (Visual Studio and Eclipse, for example) have the ability for the user to specify the command to be used to compile a program. As a suggestion, assuming you're using the Windows operating system, use the command:
START "GnuCOBOL" C:\GnuCOBOL\bin\gcic.exe $FileWhere $File represents whatever symbol the editor/IDE uses to represent the fully-qualified name of the file being edited.
Once executed, a screen will be presented showing the compilation options that will be used. The following section shows the layout of the 106 column by 28 row GCic screen.
TOPThe sample screen below shows how the screen looks if the LINEDRAW configuration setting is set to a value of 1 - this setting means that line-drawing characters will be used to create the lines and frames you see on the sample screen. The GCic Configuration Constants section will discuss how to change this to other possibilities should the line-drawing characters not be available to you.
All color-pallette configuration is performed by modifying the values of level-78 constants defined in the SCREEN SECTION of the MAIN program in the gcic.cbl file. Each 78-level data item's relationship to the screen is documented in the program.
|
GCic 2.0 (2022/09/28 08:52) ─ GnuCOBOL 3.2-dev 26SEP2022 Interactive Compilation ┌────────────────────────────────────────────────────────────────────────── Automatic COPY libraries: ─┐ │ Folder: C:\GnuCOBOL\extras C:\GnuCOBOL\copy │ │ Filename: GCic.cbl C:\GnuCOBOL\extras │ ├──────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ Debugging Source & Xref Listing Truncate COMP to PIC Save Temporary Files │ │ 'D' Lines are Comments Yes: Wide (Landscape) No No OK │ │ Run─time Err Checking Listing Produced By Optimization 'On Success' Commands │ │ Normal GCic None Ignore CANCEL │ │ Generate Tracing Code FUNCTION w/ Intrinsics Dump DATA DIV on Abort │ │ No FUNCTION is Optional No HELP │ │ Compiler Output Commands and Warnings Behavior & Standards │ │ A DLL (-m) No Commands/Warnings DEFAULT │ │ Run After Compilation Program Source Format Pgm─Specified Switches │ │ No Variable Ignore │ ├─ COBCPY COPY Libraries: ─────────────────────────────────────────────────────────────────────────────┤ │C:\Users\Gary\Documents\MyPROCs_______________________________________________________________________│ ├─ Extra 'cobc' Switches: ─────────────────────────────────────────────────────────────────────────────┤ │-fwrite-after_________________________________________________________________________________________│ ├─ Extra 'cobc' Arguments: ────────────────────────────────────────────────────────────────────────────┤ │______________________________________________________________________________________________________│ ├─ Program Execution Arguments: ───────────────────────────────────────────────────────────────────────┤ │______________________________________________________________________________________________________│ │______________________________________________________________________________________________________│ └──────────────────────────────────────────────────────────────────────────────────────────────────────┘ GCic Copyright (C) 2009─2022, Gary L. Cutler, GPL |
If GCic is run on Windows, through cmd.exe, it must run with codepage 437, 85x (x=0125789), or 86x (x=01234569) activated to display the line-drawing characters. One of those will probably be the default on your Windows system's cmd.exe environment - use the chcp command (no arguments) to see what the default codepage is on your system.
With a Windows/Cygwin build, set the environment variable CYGWIN to a value of codepage:oem (this cannot be done from within the program though - you will have to set the environment variable via Control Panel).
MacOS users may use line drawing characters in this and any GnuCOBOL program simply by setting their terminal application's font to Lucida Console, because that font contains the line-drawing characterset at the appropriate code points. This has worked in some *NIX environments also, but it may depend on the settings of the console/terminal application used.
Users will have the opportunity to do any or all of the following from this screen:
cobc by:
cobc switches that pertain to compilation features not provided by the feature buttons in the Extra 'cobc' Switches field.
COBCPY environment variable will be displayed on the screen, where it can be deleted, modified, or added to.
You may use the Tab key to traverse from one entry field to (the first character of) another. You can also click a field with the mouse to position to the first character of that field. Once positioned in a field, use the arrow keys to move forward or backward in the field, the Del key to delete characters, the Ins key to toggle between "insert" and "overwrite" mode, and - of course - the usual keys to enter data.
TOPOnce options have been selected, any desired COPY libraries, cobc switches, extra arguments, and/or execution arguments have been entered (in the example, the user has requested that the -fwrite-after switch be added to cobc), clicking
If the compilation is successful, the compiler messages file will be automatically loaded into the viewing application appropriate for the filetype/extension, normally ".lst", assigned to the file. See the Customizing GCic section for information on how to change ".lst" to what you might prefer. On Windows, it will be opened via the start command, on MacOS it will be via the open -t command, and on *NIX it will be opened using the xdg-open command. Upon a successful compilation, any selected source/xref listing will appended to the messages file before that file gets auto-opened.
If the compilation failed, the messages file will contain the error messages cobc produced. The file will be automatically loaded, but source/xref listings will be suppressed. GCic will remain running, allowing you to fix the errors and recompile by clicking
You may have multiple GCic sessions active simultaneously, but only one session at a time for the same program. This is true of both single- and multi-user environments. Anyone attempting to compile a program that is already being compiled will see a black screen with "xxxxxxx is already being compiled". See the Locking discussion for more information on how this is done. This is not so much intended to manage multiple programmers working simultaneously on the same computer as it is meant to reduce the clutter of multiple GCic sessions for the same program - sessions that exist because the programmer initiated a new compilation after making changes to correct errors rather than simply clicking
When you start GCic:
gcic-lock-xxxxxx, where "xxxxxx" is the filename portion of the file that was specified on the command-line.
gciclock executable. That program will be passed two arguments:
Immediately upon starting and retrieving the command-line arguments, gciclock will create the lock file (with a simple OPEN OUTPUT followed immediately with a CLOSE). It then waits for the OS to notify it that the GCic process that spawned it has terminated.
Once the GCic process terminates for any reason INCLUDING a Ctrl-C/Ctrl-Break, the gciclock task will be awakened and will delete the lock file immediately before it too terminates.
gciclock process that created it i>is still running, waiting for it's gcic process to finish. The new gcic process will therefore issue the message "xxxxxxx is already being compiled" message and then halt after 3 seconds.
If you wish, the locking mechasism can be disabled using the LOCKFILE configuration constant
TOP
Users of GCic will quickly notice that - regardless of whether they're using Windows, MacOS, or *NIX - the gcic and gciclock tasks appear with bland, default icons on the Taskbar, Dock, Task Widget, and so on. Included with the GCic software and documentation are four image files - two for gcic and two for gciclock. These image files can provide icons for the two programs. The two "ico" files can be used on Windows and the two "jpg" files can be used on MacOS and will serve as templates for establishing application icons on the various *NIX environments.
Windows (including MinGW and Cygwin) requires an application's icon be imbedded into the executable file itself. While the "visual" Microsoft language compilers can do that, the GnuCOBOL compiler cannot, and Windows does not include any utility that can do it either. Fortunately, there is an excellent FREEWARE utility that can do this - a command-line utility named rcedit, available from Github.
Whevever you recompile gcic or gciclock, use one of these two utilities to add the appropriate icon to the exe file.
The GCic screen provides two ways to specify the switches that the cobc compiler will use. There is also a THIRD way, by placing comments such as the following anywhere prior to the PROCEDURE DIVISION of the first program in the compilation group that GCic passes to cobc:
*> COBC Switches: switch-1 [switch-n]...Statements of this form are good to have in your programs to document compiler switches the program needs. GCic, however, can honor (or not) the switches on these comments based upon the setting of the Pgm-Specified Switches feature.
The following rules apply to the use of this feature:
PSSQTY configuration constant - see the GCic Configuration Constants section for additional information.
*> form of comment must be used, but there is no column requirement other than what is required by cobc.
cobc and switches: are case-independent, but there must be EXACTLY ONE space between the *> and cobc and between cobc and switches:.
cobc expects.
With this capability, GCic can execute one or more OS commands, batch files, or scripts when a compilation is successful. This execution process takes place right before the MAIN module of GCic executes a STOP RUN. The best way to explain the details is with an example.
I use the C:\GnuCOBOL folder on my system as the basis for packaging GnuCOBOL distributions for others I share with. Using GCic as a prime example, after I finish my own testing of changes to gcic.cbl, I need to:
gcic.cbl so that the "extras" copy is the distributable version.
The following structured comments in the MAIN program in gcic.cbl take care of everything!
LOCAL *> On Success: Set-Icon gcic.exe gcic.ico gcic.lst
LOCAL *> On Success: Promote extras gcic-readme.html COPY gcic.lst
LOCAL *> On Success: Promote extras gcic.cbl COPYSTRIP gcic.lst
LOCAL *> On Success: Promote extras gcic.ico COPY gcic.lst
LOCAL *> On Success: START /MIN cmd.exe /C Promote bin gcic.exe MOVEWAIT gcic.lst
The first record runs a batch file that uses the freeware "rcedit" utility (see After Compiling gcic.cbl or gciclock.cbl), which installs the script's second argument (gcic.ico) into the just-created first argument (gcic.exe). The third argument is the name of this program's messages/listing file; it is there in case rcedit issues any messages. Here is my "Set-Icon" batch file:
@ECHO OFF
REM ************************************************************************
REM ** Attach an icon to an executable **
REM ** **
REM ** Syntax: SET-ICON exe-filename ico-filename listing **
REM ** **
REM ** Where: exe-filename = Executable filename.extension **
REM ** ico-filename = Icon filename.extension **
REM ** listing = listing filename.extension **
REM ************************************************************************
ECHO Setting icon for %1 to %2 >> %3 2>&1
rcedit %1 --set-icon %2 >> %3 2>&1The remaining records execute a batch file that will each "promote" a file to various places in the "GnuCOBOL" folder. You may have noticed that I have one extra "Promote" command - that one makes sure the latest version of the "gcic.ico" file gets promoted to the GnuCOBOL folder along with the other files. The last "Promote" comment deals with moving the new executable file. The START command will run the "Promote" script in a separate and minimized ("/MIN") command shell ("cmd.exe"), which will execute the script (which puts itself to sleep for 3 seconds) and then close the shell window when the script finishes ("/C"). That disconnects the batch file from the GCic execution, allowing GCic to halt so that When the script wakes up from its 3-second nap, GCic has executed its STOP RUN and the gcic.exe file is now available to be updated.
Here is the coding for "Promote":
@ECHO OFF
REM ************************************************************************
REM ** Promote a file to the GnuCOBOL folder after saving a backup copy **
REM ** of the file that is getting replaced. **
REM ** **
REM ** Syntax: PROMOTE folder filename method listing **
REM ** **
REM ** Where: folder = "extras", "bin", ... **
REM ** filename = filename.extension **
REM ** method = COPY Copy as-is, immediately **
REM ** method = COPYWAIT Copy as-is, after 3-sec delay **
REM ** method = COPYSTRIP Copy stripping "LOCAL", immediately **
REM ** method = MOVE MOVE as-is, immediately **
REM ** method = MOVEWAIT MOVE as-is, after 3-sec delay **
REM ** listing = listing filename.extension **
REM ************************************************************************
SET ACTION=%3
SET WAIT=0
SET STRIP=0
SET FOLDER=%USERPROFILE%\Documents\Programs\-Backups-\%2\%COB_GCIC_TIME%\%1
IF NOT EXIST %FOLDER% MKDIR %FOLDER%
IF "%ACTION%" == "COPYWAIT" SET WAIT=1 && SET ACTION=COPY
IF "%ACTION%" == "COPYSTRIP" SET STRIP=1 && SET ACTION=COPY
IF "%ACTION%" == "MOVEWAIT" SET WAIT=1 && SET ACTION=MOVE
IF "%WAIT%" == "0" GOTO :nowait
TIMEOUT /T 3 /NOBREAK >nul
:nowait
ECHO Backing Up %1\%2 At %COB_GCIC_TIME% >> %4 2>&1
COPY /Y C:\GnuCOBOL\%1\%2 %FOLDER%\%2 >> %4 2>&1
ECHO Promoting %2 To %1 >> %4 2>&1
IF "%STRIP%" == "0" GOTO :copymove
FINDSTR /V /I /R "^LOCAL" %2 > C:\GnuCOBOL\%1\%2 2>>%4
ECHO Promoted w/o LOCAL lines >> %4
GOTO:EOF
:copymove
%ACTION% /Y %2 C:\GnuCOBOL\%1\%2 >> %4 2>&1The script takes advantage of a new environment variable (COB_GCIC_TIME) which GCic creates immediately before executing the first "On Success" command. The value will be the date and time when the first command is run, in the format "YYYYMMDD-hhmmss".
You must code the batch files or scripts yourself - they don't "come with" either GnuCOBOL or GCic - but they can be as simple or as complex as you wish, and can perform these functions or whatever else you want!
Take note of the following points:
FREE and VARIABLE source formats). You may add (or reduce) the number of allowable lines using the OSCQTY configuration constant - see the GCic Configuration Constants section for additional information.
*> form of comment must be used, but there is no column requirement other than what is required by cobc.
On and Success: are case-independent, but there must be EXACTLY ONE space between the *> and On, between On and Success:.
There are currently seventeen categories of compilation features you can control via the GCic screen. These are labeled on the screen as Debugging, Source & Xref Listing, and so on. Directly underneath each feature's caption will be a button with it's own caption describing the option that is currently selected for that feature. For the two aforementioned features, those option buttons currently have the captions 'D' Lines Are Comments and Yes: Wide (Landscape), respectively, on the sample screen. All option buttons colored green on that sample screen are showing captions for their default values. Those buttons that are yellow are showing non-default option values.
The following table shows each of the seventeen features and the options available for them. Those options that are highlighted are the defaults for their respective features, as GCic is distributed. The number of each option will come into play if you reconfigure GCic to change the assumed defaults.
| Feature | No | Available Options | Cobc Options and Other Actions |
| Debugging (F1) | 1 | 'D' Lines Are Comments | None |
| 2 | Compile 'D' Lines | -fdebugging-line |
|
| x | |||
| Run-time Err Checking (F2) | 1 | Normal | None |
| 2 | Enhanced | -debug |
|
| x | |||
| Generate Tracing Code (F3) | 1 | No | None |
| 2 | Yes: Procedures Only | -ftrace |
|
| 3 | Yes: Procedures+Stmnts | -ftraceall |
|
| x | |||
| Compiler Output (F4) See note 1, below |
1 | An EXE (-x) | -x |
| 2 | A DLL (-m) | -m |
|
| 3 | Save C Source (-C) | -C |
|
| 4 | Save Asm Source (-S) | -S |
|
| 5 | Save Object Code (-c) | -c |
|
| x | |||
| Run After Compilation (F5) | 1 | No | None |
| 2 | Yes: If Comp. OK | -j |
|
| x | |||
| Source & Xref Listing (F6) | 1 | None | None |
| 2 | Yes: Wide (Landscape) | -T gcic$output.txt |
|
| 3 | Yes: Narrow (Portrait) | -t gcic$output.txt or -T gcic$output.txtIf the Listing Prepared By feature is set to "cobc", the first switch will be used. If "GCic" is selected, the second switch is used and GCic will reformat the wide listing to the narrow format. |
|
| 4 | Yes: Preproc. COBOL | -E |
|
| x | |||
| Listing Produced By (F7) | 1 | GCic | -ftsymbols -save-tempsThe LISTER subroutine needs to work with the expanded source file produced by cobc in order to produce the cross-reference listing - hence the inclusion of -save-temps. GCic will handle temporary file cleanup. |
| 2 | cobc | -XThe -T or -t option will be added by the previous feature |
|
| x | |||
| Commands and Warnings (F8) | 1 | No Commands/Warnings | -q -w |
| 2 | Cmds, Minimal Warnings | None | |
| 3 | Cmds, Most Warnings | -W |
|
| 4 | Cmds, All Warnings | -Wall -Wextra -Wadditional |
|
| x | |||
| FUNCTION w/ Intrinsics (F9) | 1 | FUNCTION Is Optional | -fintrinsics=all |
| 2 | Managed By REPOSITORY | None | |
| x | |||
| Program Source Format (F10) See note 4, below |
1 | Free | -fformat=free (GnuCOBOL 3.2+)-free (GnuCOBOL 3.1) |
| 2 | Fixed | -fformat=fixed (GnuCOBOL 3.2+)-fixed (GnuCOBOL 3.1) |
|
| 3 | Variable | -fformat=variable (GnuCOBOL 3.2+)-fixed -ftext-column=250 (GnuCOBOL 3.1) |
|
| 4 | COBOL85 | -fformat=cobol85 (GnuCOBOL 3.2+)(N/A GnuCOBOL 3.1) |
|
| 5 | XOPEN | -fformat=xopen (GnuCOBOL 3.2+)(N/A GnuCOBOL 3.1) |
|
| 6 | ICOBOL XCARD | -fformat=xcard (GnuCOBOL 3.2+)(N/A GnuCOBOL 3.1) |
|
| 7 | ICOBOL Free (CRT) | -fformat=crt (GnuCOBOL 3.2+)(N/A GnuCOBOL 3.1) |
|
| 8 | AcuCOBOL Terminal | -fformat=terminal (GnuCOBOL 3.2+)(N/A GnuCOBOL 3.1) |
|
| 9 | COBOLX | -fformat=cobolx (GnuCOBOL 3.2+)(N/A GnuCOBOL 3.1) |
|
| x | |||
| Truncate COMP to PIC (F11) | 1 | No | -fnotrunc |
| 2 | Yes | None | |
| x | |||
| Optimization (F12) | 1 | None | -O0 |
| 2 | Size Only | -Os |
|
| 3 | Size+Speed (Level 1) | -O |
|
| 4 | Size+Speed (Level 2) | -O2 |
|
| x | |||
| Dump DATA DIV on Abort (F13) | 1 | No | None |
| 2 | Yes | -fdump=all |
|
| x | |||
| Behavior & Standards (F14) | 1 | AcuCOBOL | -std=acu |
| 2 | AcuCOBOL (Strict) | -std=acu-strict |
|
| 3 | BS2000 | -std=bs2000 |
|
| 4 | BS2000 (Strict) | -std=bs2000-strict |
|
| 5 | COBOL2002 | -std=cobol2002 |
|
| 6 | COBOL2014 | -std=cobol2014 |
|
| 7 | COBOL85 | -std=cobol85 |
|
| 8 | DEFAULT | -std=default |
|
| 9 | Bull GCOS | -std=gcos |
|
| 10 | Bull GCOS (Strict) | -std=gcos-strict |
|
| 11 | IBM Enterprise | -std=ibm |
|
| 12 | IBM Enterprise (Strict) | -std=ibm-strict |
|
| 13 | MicroFocus | -std=mf |
|
| 14 | MicroFOCUS (Strict) | -std=mf-strict |
|
| 15 | REALIA | -std=realia |
|
| 16 | REALIA (Strict) | -std=realia-strict |
|
| 17 | RmCOBOL | -std=rm |
|
| 18 | RmCOBOL (Strict) | -std=rm-strict |
|
| 19 | IBM VSCOBOL II | -std=mvs |
|
| 20 | IBM VSCOBOL II (Strict) | -std=mvs-strict |
|
| 21 | XOPEN | -std=xopen |
|
| x | |||
| Pgm-Specified Switches (F15) | 1 | Ignore | None |
| 2 | Honor | None | |
| x | |||
| Save Temporary Files (F16) | 1 | No | None |
| 2 | Yes | -save-temps |
|
| x | |||
| 'On Success' Commands (F17) | 1 | Ignore | None |
| 2 | Execute | None | |
The Customizing GCic section will show you how you may change any of these defaults. To change an option for a single compilation, just left-click an option button on the screen to advance the selection forward (i.e. downward on the above list) and use a right-click to move the selection backward (i.e. upward on the above list).
Some of these features/options deserve special consideration, as follows.
LINKAGE SECTION, the option will default to A DLL (-m). If the LINKAGE SECTION cannot be found in that program, the An EXE (-x) option will be assumed. If you configure GCic to make the A DLL (-m) option the default, this checking will not be performed. The terms "EXE" and "DLL" will change, depending on the OS and environment GCic is configured for, as follows:
cobc compiler.
>>SOURCE FORMAT IS xxxxx in your programs. GnuCOBOL 3.1 only supports THREE formats - FREE, FIXED, and VARIABLE. GCic, when used in conjunction with GnuCOBOL 3.1, also supports just those three options.
BINARY and COMP fields. For example, PIC S99 COMP fields will normally be limited to a range of values of -99 to +99. By turning this truncation off, the range of possible values would become -127 to +127 (0-255 if unsigned). As a bonus, turning truncation off will yield a substantial performance boost to arithmetic operations performed on BINARY and COMP fields.
cobc to compile a program. The contents of that file are controlled by the Commands and Warnings feature. This dictates whether or not the text of the generated cobc command, along with the compilation and linking commands cobc generates, will be included. It also controls how in-depth any cobc-generated warnings will be.
Error messages generated by cobc are always included
If source and cross-reference listings are selected by the Source & Xref Listing feature, they will be appended to the messages file. If cobc issued error messages, source/xref listings will NOT be generated.
Compilation Failed - Correct error and try again
As the message suggests, you may correct the errors and click
|
This is a sample of a GCic source listing. These listings show every line of COBOL code in the entire compilation group, including comments and code introduced by COPY statements.
Some areas of this sample been highlighted:
|
GCic determined that the debugging lines were not compiled because NONE of the following were detected by GCic:
SOURCE-COMPUTER paragraph WITH DEBUGGING MODE.
-fdebugging-line switch being included in the Extra 'cobc' Switches area on the GCic screen, or on a Program-Specified Switch comment.
-debug switch being included in the Extra 'cobc' Switches area on the GCic screen, or on a Program-Specified Switch comment.
GCic will start the source listing of each file it compiles at the top of a new page. The same is true of any non-nested programs in that file. You may use the /, eject, space1, space2, and space3 directives to control the source listing; you may wish to include a "/" (or an "eject") between programs in your source files so that each program begins on a new page.
TOP
|
This is a sample of a GCic cross-reference ("xref", for short) listing. These listings are generated by analyzing every non-comment line of COBOL code in the complete compilation group.Some points of note about the listing have been highlighted:
|
Here are some points of interest regarding the cross-reference process:
DEF, REF, and UPD in the Customizing GCic section.
RELATIVE or INDEXED files. How this is done is explained in the The "Records-And-Files-Tbl" Table section.
OPENing and CLOSEing of files logs only references to the file(s).
- in column 7 of the continuation lines) will consider each of the word segments on the two lines to be separate words. I do have to ask though - "Why are you coding like that to begin with?" The splitting of character strings in that manner will not be a problem.
cobc (via the -ftsymbols switch) and that report currently truncates names at 30 characters.
GCic expects to run in a terminal window that has at least 28 rows and 106 columns. In some OS environments, it is possible for GCic to automatically resize the terminal window to that geometry, if any aspect of the current screen size is smaller than that.
mode con: cols=106 lines=28 to resize the window to 28 lines x 106 columns.rxvt terminal emulator and will use the command printf "\x1B[8;28;106t" to issue the VT100 command sequence to resize the window.
resize -s 28 106&&stty rows 28&&stty cols 106 to resize the terminal window to 28 lines x 106 columns.resize -s 28 106&&stty rows 28&&stty cols 106 to resize the window.
mode con: cols=106 lines=28 to resize the window.If you don't find the right combination of environments and assumptions for your setup, automatic resizing may not be possible for you and you may just have to resize your terminal window manually.
Before giving up on automatic resizing, do some research into the terminal or console emulator you are using. Perhaps it does have a way to resize its window from the command line. If so, you can configure GCic to issue the necessary command(s) using the RESIZECMD configuration constant, provided the total size of the command(s) needed (including ";", "││", or "&&" command separator characters) does not exceed 256 characters. If you do need more than a linear sequence of commands 256 characters long, consider writing a shell script to do the job and then configure GCic to execute that script.
If your system runs *NIX and you do NOT use an X11 emulator (i.e. xterm) and you CANNOT identify a command sequence to resize the screen window, set the XTERM configuration constant to 0 (zero) to at least stop trying to run resize.
TOP
The gcic.cbl file contains the code for seven programs. The first of these, MAIN, contains a number of <$SET CONSTANT statements which configure the GCic program, allowing for the customization of default options for the features, the sizing of various tables used within the program, specification of the host environment GCic will be running in, and more.
| Constant Name | Setting as Distributed | Description | ||||||||||||||||
| CMDMAXSIZE | 8191 | This will define the size (in characters) of the buffer GCic uses to submit commands (like "cobc") to the operating system. It is recommended that this be set to the maximum size of a command in the operating system GCic will be running under. Windows (including MinGW and Cygwin) allows 8191 characters. Most *NIX versions allow 4096 and MacOS allows 262144 (as do many BSD UNIX systems) - it might be a just a LITTLE absurd to go THAT HIGH though. | ||||||||||||||||
| DEF | '^' | The character that will be appended to line numbers in the GCic-generated cross-reference listing to indicate that the item in question was DEFINED at that line number in the merged and expanded source listing (the number in the "LineNo") column in the source listing. | ||||||||||||||||
| F1 | 1 | Debugging feature default option number (see Using GCic). | ||||||||||||||||
| F2 | 1 | Run-time Err Checking feature default option number (see Using GCic). | ||||||||||||||||
| F3 | 1 | Generate Tracing Code feature default option number (see Using GCic). | ||||||||||||||||
| F4 | 1 | Compiler Output feature default option number (see Using GCic). | ||||||||||||||||
| F5 | 1 | Run After Compilation feature default option number (see Using GCic). | ||||||||||||||||
| F6 | 1 | Source & Xref Listing feature default option number (see Using GCic). | ||||||||||||||||
| F7 | 1 | Listing Generated By feature default option number (see Using GCic). | ||||||||||||||||
| F8 | 2 | Commands and Warnings feature default option number (see Using GCic). | ||||||||||||||||
| F9 | 1 | FUNCTION w/ Intrinsics feature default option number (see Using GCic). | ||||||||||||||||
| F10 | 3 | Program Source Format feature default option number (see Using GCic). | ||||||||||||||||
| F11 | 1 | Truncate COMP to PIC feature default option number (see Using GCic). | ||||||||||||||||
| F12 | 1 | Optimization feature default option number (see Using GCic). | ||||||||||||||||
| F13 | 1 | Dump DATA DIV on Abort feature default option number (see Using GCic). | ||||||||||||||||
| F14 | 8 | Behavior & Standards feature default option number (see Using GCic). | ||||||||||||||||
| F15 | 1 | Pgm-Specified Switches feature default option number (see Using GCic). | ||||||||||||||||
| F16 | 1 | Save Temporary Files feature default option number (see Using GCic). | ||||||||||||||||
| F17 | 2 | 'On Success' Commands feature default option number (see Using GCic). | ||||||||||||||||
| FASTSIZE | 50 | Set this to the desired size of the Files And Statuses table. This should have a value of the expected number of data items registered as FILE STATUS or SORT STATUS items across all programs being compiled and cross-referenced. This has no bearing on cross-referencing performed by cobc/cobxref. |
||||||||||||||||
| GCICVER | '2.0' | The version.release.update.subupdate number for GCic. | ||||||||||||||||
| LINEDRAW | 1 | Set to a value 0-5 to produce the following results on the screen ("X" represents text):MacOS USERS - To use the linedrawing characterset (option 1), set your 'terminal' font to 'Lucida Console' |
||||||||||||||||
| LISTEXT | '.lst' | The desired extension for the file containing any "cobc" output as well as the source and cross-reference listings. In prior versions you were stuck with ".gclst" but as of V2.0 you can choose your own extension (including ".gclst" if you want to stick with that). DON'T FORGET THE LEADING PERIOD! | ||||||||||||||||
| LOCKFILE | 1 | To turn off the locking feature, set this to 0. | ||||||||||||||||
| LPP | 51 | Set to the maximum number of printable lines per page when a GCic-generated listing should be generated for landscape orientation (can be overridden at runtime time using the GCXREF_LINES environment variable). This value plus 6 (the number of lines in page headers) plus 3 (the number of lines in page footers) should add up to the total number of theoretically-printable lines on the printer you use. Lines-per-page control for cobc-generated listings uses the cobc --tlines=lines switch, which must be entered in the Extra 'cobc' Switches field on the GCic screen. |
||||||||||||||||
| LPPP | 78 | Similar to LPP, but applies when a GCic-generated listing should be generated for portrait orientation (can be over-ridden at runtime time using the GCXREF_LINES_PORT environment variable. |
||||||||||||||||
| MAXSWITCH | 200 | Set to the maximum number of switches you believe will EVER need to be specified on a cobc command. This value is probably much more than sufficient. |
||||||||||||||||
| OS | 0 | Defines the Operating System and environment. Set to:
|
||||||||||||||||
| OSCQTY | 10 | Set this to the maximum number of *> on success: command lines that can be processed |
||||||||||||||||
| PROMPTCHAR | ' ' | Set to the character that will serve as the fill (i.e. "PROMPT") character for the four input areas on the screen. A common character used instead of a space is an underscore ("_"); you're welcome to use that! of course! but it may make the screen look a little too "busy". | ||||||||||||||||
| PSSQTY | 5 | Set this to the maximum number of *> lines that can be processed |
||||||||||||||||
| PSTACKSIZE | 50 | Set this to the number of entries in the Procedure Stack - a data structure that the debugging routines use to track module-to-module CALLs snd procedure-to-procedure PERFORMs. The default setting allows for a 50-deep CALL/PERFORM sequence - more than enough. | ||||||||||||||||
| RAFTSIZE | 150 | Set this to the desired size of the Records And Files table. This should be a value greater than the expected total number of 01 level data items defined in the FILE SECTIONs of all programs being compiled and cross-referenced by GCic. This has no bearing on cross-referencing performed by cobc/cobxref. |
||||||||||||||||
| REF | ' ' | The character that will be appended to line numbers in the GCic-generated cross-reference listing to indicate that the item in question was REFERENCED at that line number in the merged and expanded source listing (the number in the "LineNo") column in the source listing. | ||||||||||||||||
| RESIZE | 1 | Set this to one of the following values to control automatic screen resizing:
|
||||||||||||||||
| RESIZESTR | ' ' | Ignored unless RESIZE has the value -5, +5, -7, or +7, this specifies the custom escape- or command-sequence to be used to resize the screen. When coding a command sequence, use the "&&", "||", or ";" characters to separate multiple commands from one another. If coding an escape-sequence, remember that GCic will automatically supply the leading ASCII ESC character. |
||||||||||||||||
| RWTSIZE | 2047 | Set to the size of the Reserved Word Table. This should have a value of a power of 2, minus one. As of GnuCOBOL 3.1 there are a little more than 1000 reserved words, so this value here should be good for quite a while, if not forever. | ||||||||||||||||
| STACKSIZE | 50 | Set to the size of the stack used in the scanning of ADD, SUBTRACT, MULTIPLY, and DIVIDE statements. This should have a value of the expected number of numeric identifiers used in any ONE of these statements, in any single program being cross-referenced. It's hard to imagine one of these statements involving more that THIS number of identifiers. |
||||||||||||||||
| STSIZE | 7500 | Set to the size of the Symbol Table which contains an entry for each non-FILLER, non-77, non-66, and non-78 data item defined in all programs currently being compiled and cross-referenced. | ||||||||||||||||
| UPD | '*' | The character that will be appended to line numbers in the GCic-generated cross-reference listing to indicate that the item in question was UPDATED at that line number in the merged and expanded source listing (the number in the "LineNo") column in the source listing. |
This section will provide a glimpse into the structure, data structures, and algorithms that make up the GCic program. It consists of a main program (named "MAIN") and nine subprograms, all found in a single file named gcic.cbl. The programs in this file are separated from one another using END PROGRAM statements.
Of these ten programs, six are part of a built-in debugging facility and provide no direct support to thevfunctional goals of GCic. As a result, these six routines will be covered in the Testing GCic discussion.
The following table summarizes each of the four functionality-providing programs.
| PROGRAM-ID | Description | |
| MAIN | Purpose: | This is the main program for GCic. It is responsible for all user interaction and for generating and submitting the |
| x | ||
| GCINFO | Purpose: | MAIN CALLs this subroutine to collect information about the GnuCOBOL installation on your system. The information will be collected by executing cobc with just the "-i" option, and parsing the output to collect the information. |
| Linkage: | |
|
| Arguments: |
|
|
| x | ||
| LISTER | Purpose: | This program is responsible for generating GCic's source and cross-reference listings. This subroutine will ONLY be called if:
|
| Linkage: | |
|
| Arguments: |
|
|
| x | ||
| LOADER | Purpose: | This subroutine is CALLed by MAIN to:
|
| Linkage: | |
|
| Arguments: |
|
|
As was stated earlier, this is the program responsible for all interaction with the user. All of its actions are managed through the use of four key tables. TOP
01 Button-FILLER.
*>************************************************************************
*> Button coordinates for the four two-line entry fields **
*>************************************************************************
05 PIC X(21) VALUE "025003104NOP". *> COBCPY COPY Libraries
05 PIC X(21) VALUE "027003104NOP". *> Additional 'cobc' Switches
05 PIC X(21) VALUE "029003104NOP". *> Additional 'cobc' Arguments
05 PIC X(21) VALUE "031003104NOP". *> Program Execution Args (line 1)
05 PIC X(21) VALUE "032003104NOP". *> Program Execution Args (line 2)
*>************************************************************************
*> Button coordinates for the seventeen function option buttons **
*>************************************************************************
05 PIC X(21) VALUE "010004025F01". *> Debugging
05 PIC X(21) VALUE "013004025F02". *> Run-time Err Checking
05 PIC X(21) VALUE "016004025F03". *> Generate Tracing Code
05 PIC X(21) VALUE "019004025F04". *> Compiler Output
05 PIC X(21) VALUE "022004025F05". *> Run After Compilation
05 PIC X(21) VALUE "010027048F06". *> Source & Xref Listing
05 PIC X(21) VALUE "013027048F07". *> Listing Produced By
05 PIC X(21) VALUE "016027048F08". *> FUNCTION w/ Intrinsics
05 PIC X(21) VALUE "019027048F09". *> Commands and Warnings
05 PIC X(21) VALUE "022027048F10". *> Program Source Format
05 PIC X(21) VALUE "010050071F11". *> Truncate COMP to PIC
05 PIC X(21) VALUE "013050071F12". *> Optimization
05 PIC X(21) VALUE "016050071F13". *> Dump DATA DIV on Abort
05 PIC X(21) VALUE "019050071F14". *> Behavior & Standards
05 PIC X(21) VALUE "022050071F15". *> Pgm-Specified Switches
05 PIC X(21) VALUE "010073094F16". *> Save Temporary Files
*> 05 PIC X(21) VALUE "013073094F17". *> Unused
*> 05 PIC X(21) VALUE "016073094F18". *> Unused
*> 05 PIC X(21) VALUE "019073094F19". *> Unused
*> 05 PIC X(21) VALUE "022073094F20". *> Unused
*>************************************************************************
*> Button coordinates for the main screen static buttons **
*>************************************************************************
05 PIC X(21) VALUE "010095103OK OK 8".*> All captions must have at least
05 PIC X(21) VALUE "012095103CAN CANCEL 8".*> leading and ONE trailing space
05 PIC X(21) VALUE "014095103HLP HELP 8".
05 PIC X(21) VALUE LOW-VALUES. *> Must be last entry
01 All-Buttons REDEFINES Button-FILLER.
05 Button-Tbl OCCURS 25 TIMES
INDEXED BY Button-Idx.
10 BT-Row PIC 9(3). *> Screen row no where button resides
10 BT-Col-Start PIC 9(3). *> Screen column where button begins
10 BT-Col-End PIC 9(3). *> Screen column where button ends
10 BT-ID. *> Three-char button function, or...
15 BT-ID-Type PIC X(1). *> ...Letter "F", followed by...
15 BT-Function-No PIC 9(2). *> ...2-digit function button # (01-16)
10 BT-Caption PIC X(8). *> Fixed button caption text
10 BT-Caption-Size PIC 9(1). *> The size (chars) of the caption
Whenever the Switches-Screen is ACCEPTed, and the COB-STATUS-CODE register has a value of COB-SCR-LEFT-PRESSED or COB-SCR-RIGHT-PRESSED, the Buttons-Tbl table will be searched to find out what button or field (if any) the user clicked.
The Cursor-Coordinates group will receive the six-digit cursor coordinates:
01 Cursor-Coordinates PIC 9(6). *> Locn of cursor on screen ACCEPTs
01 REDEFINES Cursor-Coordinates.
05 CC-Row PIC 9(3).
05 CC-Col PIC 9(3).
The Cursor-Coordinates data item was defined in SPECIAL-NAMES as the data item to receive the cursor coordinates when a mouse-click occurs. The table will searched (sequentially, via SEARCH) for the first entry where BT-Row = CC-Row AND BT-Col-Start <= CC-Col AND CC-Col <= BT-Col-End. If no such entry was found, MAIN will ring the bell, signaling a user input error.
If such an entry is found, MAIN will then know what button was clicked, and the BT-ID(Button-Idx) field value in the table ("NOP", "F01"..."F15", "OK ", "CAN", "HLP") is ready-made for an EVALUATE statement to be able to take the desired action. The NOP fields represent the five data-entry fields on the screen.
015-Identify-Click - whose job it is to perform the aforementioned searching. It also, in the instance where a function option button was clicked, populates a data-item named Function-No with the number of the function button (1-16).
When adding (or removing) entries in the This is easily correctable by making the source code change the message recommends and recompiling |
This table exists to track which option is currently selected for each of the seventeen features.
01 Function-FILLER. *> Function button characteristics
05 Function-No PIC 9(2) VALUE 0. *> Subscript of most-recently clicked function button
*> ------------------------------------------------------------------------
*> Function 1 - Debugging
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F1. *> FT-Curr-Opt-No (1)
05 PIC 9(2) VALUE F1. *> FT-Default-Opt-No(1)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (1) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 2 - Run-time Err Checking
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F2. *> FT-Curr-Opt-No (2)
05 PIC 9(2) VALUE F2. *> FT-Default-Opt-No(2)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (2) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 3 - Generate Tracing Code
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F3. *> FT-Curr-Opt-No (3)
05 PIC 9(2) VALUE F3. *> FT-Default-Opt-No(3)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (3) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 4 - Compiler Output
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F4. *> FT-Curr-Opt-No (4)
05 PIC 9(2) VALUE F4. *> FT-Default-Opt-No(4)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (4) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 5 - Run After Compilation
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F5. *> FT-Curr-Opt-No (5)
05 PIC 9(2) VALUE F5. *> FT-Default-Opt-No(5)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (5) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 6 - Source & Xref Listing
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F6. *> FT-Curr-Opt-No (6)
05 PIC 9(2) VALUE F6. *> FT-Default-Opt-No(6)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (6) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 7 - Listing Produced By
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F7. *> FT-Curr-Opt-No (7)
05 PIC 9(2) VALUE F7. *> FT-Default-Opt-No(7)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (7) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 8 - FUNCTION w/ Intrinsics
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F8. *> FT-Curr-Opt-No (8)
05 PIC 9(2) VALUE F8. *> FT-Default-Opt-No(8)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (8) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 9 - Commands and Warnings
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F9. *> FT-Curr-Opt-No (9)
05 PIC 9(2) VALUE F9. *> FT-Default-Opt-No(9)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (9) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 10 - Program Source Format
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F10. *> FT-Curr-Opt-No (10)
05 PIC 9(2) VALUE F10. *> FT-Default-Opt-No(10)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (10) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 11 - Truncate COMP to PIC
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F11. *> FT-Curr-Opt-No (11)
05 PIC 9(2) VALUE F11. *> FT-Default-Opt-No(11)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (11) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 12 - Optimization
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F12. *> FT-Curr-Opt-No (12)
05 PIC 9(2) VALUE F12. *> FT-Default-Opt-No(12)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (12) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 13 - Dump DATA DIV on Abort
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F13. *> FT-Curr-Opt-No (13)
05 PIC 9(2) VALUE F13. *> FT-Default-Opt-No(13)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (13) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 14 - Behavior & Standards
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F14. *> FT-Curr-Opt-No (14)
05 PIC 9(2) VALUE F14. *> FT-Default-Opt-No(14)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (14) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 15 - Pgm-Specific Switches
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F15. *> FT-Curr-Opt-No (15)
05 PIC 9(2) VALUE F15. *> FT-Default-Opt-No(15)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (15) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 16 - Save Temporary Files
*> ------------------------------------------------------------------------
05 PIC 9(2) VALUE F16. *> FT-Curr-Opt-No (16)
05 PIC 9(2) VALUE F16. *> FT-Default-Opt-No(16)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (16) Computed by 100-Initialization
------------------------------------------------------------------------
Function 17 - 'On Success' Commands
------------------------------------------------------------------------
05 PIC 9(2) VALUE F17. *> FT-Curr-Opt-No (17)
05 PIC 9(2) VALUE F17. *> FT-Default-Opt-No(17)
05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (17) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 18 - ???
*> ------------------------------------------------------------------------
*> 05 PIC 9(2) VALUE F18. *> FT-Curr-Opt-No (18)
*> 05 PIC 9(2) VALUE F18. *> FT-Default-Opt-No(18)
*> 05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (18) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 19 - ???
*> ------------------------------------------------------------------------
*> 05 PIC 9(2) VALUE F19. *> FT-Curr-Opt-No (19)
*> 05 PIC 9(2) VALUE F19. *> FT-Default-Opt-No(19)
*> 05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (19) Computed by 100-Initialization
*> ------------------------------------------------------------------------
*> Function 20 - ???
*> ------------------------------------------------------------------------
*> 05 PIC 9(2) VALUE F20. *> FT-Curr-Opt-No (20)
*> 05 PIC 9(2) VALUE F20. *> FT-Default-Opt-No(20)
*> 05 PIC 9(2) VALUE 0. *> FT-Opt-Qty (20) Computed by 100-Initialization
*> ------------------------------------------------------------------------
05 PIC X(6) VALUE LOW-VALUES. *> Must be the last entry
01 Function-Redef REDEFINES Function-FILLER.
05 PIC 9(2).
05 Function-Tbl OCCURS 18 TIMES. *> # Supported funcs + 1 for end sentinel
10 FT-Curr-Opt-No PIC 9(2). *> Current displayed option (varies)
10 FT-Default-Opt-No PIC 9(2). *> Default displayed option (unchanging)
10 FT-Opt-Qty PIC 9(2). *> Number of option choices (unchanging)
01 Function-Names REDEFINES Function-FILLER.
05 PIC 9(2).
05 F1-Debugging-Opt-No PIC 9(2).
05 PIC X(4).
05 F2-ErrCheck-Opt-No PIC 9(2).
05 PIC X(4).
05 F3-Tracing-Opt-No PIC 9(2).
05 PIC X(4).
05 F4-Output-Opt-No PIC 9(2).
05 PIC X(4).
05 F5-Run-Opt-No PIC 9(2).
05 PIC X(4).
05 F6-Listing-Opt-No PIC 9(2).
88 F6-No-Listing-Wanted VALUE 1.
88 F6-Landscape-Listing-Wanted VALUE 2.
88 F6-Portrait-Listing-Wanted VALUE 3.
88 F6-Exp-Srce-Listing-Wanted VALUE 4.
05 PIC X(4).
05 F7-Lister-Opt-No PIC 9(2).
88 Listing-Generated-By-GCic VALUE 1.
88 Listing-Generated-By-Cobc VALUE 2.
05 PIC X(4).
05 F8-Function-Opt-No PIC 9(2).
05 PIC X(4).
05 F9-CmdWarn-Opt-No PIC 9(2).
05 PIC X(4).
05 F10-SrceFmt-Opt-No PIC 9(2).
05 PIC X(4).
05 F11-Truncation-Opt-No PIC 9(2).
05 PIC X(4).
05 F12-Optimization-Opt-No PIC 9(2).
05 PIC X(4).
05 F13-Dump-Opt-No PIC 9(2).
05 PIC X(4).
05 F14-Config-Opt-No PIC 9(2).
05 PIC X(4).
05 F15-PrgSpcSwtchs-Opt-No PIC 9(2).
05 PIC X(4).
05 F16-SaveTemps-Opt-No PIC 9(2).
05 PIC X(4).
05 F17-Success-Opt-No PIC 9(2).
88 F17-Success-Ignore VALUE 1.
88 F17-Success-Xqt VALUE 2.
05 PIC X(4).
*> 05 F18-XXXX-Opt-No PIC 9(2).
*> 05 PIC X(4).
*> 05 F19-XXXX-Opt-No PIC 9(2).
*> 05 PIC X(4).
*> 05 F20-XXXX-Opt-No PIC 9(2).
*> 05 PIC X(4).
05 PIC X(6). *> Lines up w/ end-of-table sentinal
Once a mouse button has been clicked, the Button-Tbl will be consulted to identify which button, if any, was clicked. Assuming it was one of the function buttons, the Function-Tbl comes into play as follows.
Depending on whether the option button was left-clicked or right-clicked, the value of the FT-Curr-Opt-No item for the "Function-No"th button will be incremented by 1 or decremented by 1, respectively. The FT-Opt-Qty items are there so the code knows how many options there are for each function (those values are calculated automatically by the 100-Initialization routine). With that knowledge, the value will be set back to 1 if you left-click past the last option for the function, or will be set to the last option if you attempt to right-click to 0.
The Function-Names group provides a non-subscripted and more meaningful name for each function's current option number, for use when appropriate. As you can see, there are also four additional unused entries already coded for future expansion.
When adding (or removing) entries in the This is easily correctable by making the source code change the message recommends and recompiling |
This table defines every option for every function, the caption that option will have on its feature button whenmit is selected, and the switches (if any) that option will pass to the cobc command.
As the user clicks option buttons, their captions will change. When Function-No gets set as a result of the click and the FT-Curr-Opt-No(Function-No) value gets incremented or decremented, this table will be consulted when it comes time to repaint. the screen so that the new caption can be displayed. This is done via a SEARCH ALL using Function-No and FT-Curr-Opt-No(Function-No) as the search key against the Option-Func table.
01 Option-FILLER.
*> ---------------------------------------------------------------------
*> Function 1 - Debugging
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "010100".
05 PIC X(29) VALUE " Treat 'D' Lines as Comments ".
05 PIC X(94) VALUE SPACES.
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "010217".
05 PIC X(29) VALUE " 'D' Lines Will Be Compiled ".
05 PIC X(94) VALUE "-fdebugging-line".
*> ---------------------------------------------------------------------
*> ---------------------------------------------------------------------
*> Function 2 - Runtime Error Checking
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "020100".
05 PIC X(29) VALUE " Normal ".
05 PIC X(94) VALUE SPACES.
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "020207".
05 PIC X(29) VALUE " Enhanced ".
05 PIC X(94) VALUE "-debug".
*> ---------------------------------------------------------------------
*> ---------------------------------------------------------------------
*> Function 3 - Generate Tracing Code
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "030100".
05 PIC X(29) VALUE " No ".
05 PIC X(94) VALUE SPACES.
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "030208".
05 PIC X(29) VALUE " Yes - Procedures Only ".
05 PIC X(94) VALUE "-ftrace".
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE "030311".
05 PIC X(29) VALUE "Yes - Procedures & Statements".
05 PIC X(94) VALUE "-ftraceall".
*> ---------------------------------------------------------------------
.
.
.
*> ---------------------------------------------------------------------
*> Must be the last entry
*> ---------------------------------------------------------------------
05 PIC X(6) VALUE LOW-VALUES.
05 PIC X(29) VALUE LOW-VALUES.
05 PIC X(94) VALUE LOW-VALUES.
01 Option-Redef REDEFINES Option-FILLER.
05 Option-Tbl OCCURS 65 TIMES
ASCENDING KEY Option-Func
INDEXED BY Option-Idx.
10 Option-Func.
15 OF-Func-No PIC 9(2). *> Function # (static) - 01-16
15 OF-Opt-No PIC 9(2). *> Option # (static) - 01-FT-Opt-Qty(n)
15 OF-Opt-Size PIC 9(2). *> If > 0, eligible for PSS
10 Option-Text PIC X(22). *> Function button text for option (static)
10 Option-Switch PIC X(30). *> "cobc" switches for this option (static)
Once the appropriate entry has been found, MAIN knows both the caption to be used for the currently-selected option and the option switches (if any) that need to be added to the cobc command that will be built and submitted.
The option numbers for any given function must be coded in strictly ascending and consecutive sequence (01, 02, 03, 04, ...). Failure to adhere to this will result in the following fatal error:
Fatal Error: Missing Option in Option-tbl (ffoo)Where "ff" is the function number and "oo" is the option number, the combination of which is not present in the table.
When adding (or removing) entries in the This is easily correctable by making the source code change the message recommends and recompiling |
The process of producing the source and cross-reference listings relies heavily on files produced by the cobc compiler - some of which the compiler will delete before LISTER can "get its hands on them". Because of that, GCic will code the "-save-temps" switch on the cobc command it generates. Since the user will undoubtedly get annoyed as these files start to build up, GCic will clean up after itself and delete those files itself UNLESS the user actually specified the "-save-temps" switch in the "Extra cobc Switches" field on the screen. Also included are the various "gcic$xxxx.txt" files that GCic creates in the process of doing its job.
The cleanup process is managed by this table. Comments in the code (shown here) explain the conventions used in the table entries.
01 Temp-Files-FILLER. *> Files that we have to clean up on normal finish
*> *********************************************************************
*> ** Entries containing "xxxxxx" will have the command-line program **
*> ** filename (minus extension) substituted for the "xxxxxx". Those **
*> ** entries with a TF-Wildcard value of "*" will be deleted using **
*> ** a "SYSTEM" command while all others will be deleted via the **
*> ** CBL_DELETE_FILE subroutine. **
*> *********************************************************************
05 PIC X(21) VALUE "*xxxxxx.c.l*.h". *> ..."C" header for local storage from "cobc"
05 PIC X(21) VALUE " gcic-info.txt". *> ..."cobc -i" output
05 PIC X(21) VALUE " gcic-list.txt". *> ..."cobc -list-reserved", etc. output
05 PIC X(21) VALUE " gcic-output.txt". *> ..."cobc -T│t [-ftsymbols]" output
05 PIC X(21) VALUE " gcic-source.txt". *> ..."cobc -T" source listing
05 PIC X(21) VALUE " gcic-symbols.txt". *> ..."cobc -ftsymbols" listing
05 PIC X(21) VALUE " xxxxxx.c". *> ..."C" source code from "cobc"
05 PIC X(21) VALUE " xxxxxx.c.h". *> ..."C" header file from "cobc"
05 PIC X(21) VALUE " xxxxxx.i". *> ...Expanded COBOL code from "cobc"
05 PIC X(21) VALUE " xxxxxx.o". *> ...Object code from "cobc"
05 PIC X(21) VALUE " xxxxxx.s". *> ...Assembler source from "cobc -S"
05 PIC X(21) VALUE LOW-VALUES. *> ...End-of-table sentinal
01 Temp-Files-Tbl REDEFINES Temp-Files-FILLER.
05 Temp-File OCCURS 12.
10 TF-Wildcard PIC X(1).
10 TF-Filename PIC X(20).
When adding (or removing) entries in the This is easily correctable by making the source code change the message recommends and recompiling |
As seen back in the Using GCic section, this feature of GCic allows for specially-formatted comments to be included in GnuCOBOL programs. In addition to serving as documentation of compilation requirements these can also be collected by GCic and added to the cobc statement before it is submitted.
The 025-Scan-PSS routine scans the Options-Tbl table, looking for entries with a SPACE in their PSS-Exclude field. Those will be the options having a single option switch defined for them. The complete set of PSS options accumulated during the 020-Is-Prog-A-Subprogram scan of the source file supplied as the argument to GCic will be searched (via INSPECT TALLYING, not SEARCH) for an occurrence of the entry in the Options-Tbl table. If not found, 025-Scan-PSS will move on.
The 025-Scan-PSS routine is executed at two points during GCic's execution:
020-Is-Prog-A-Subprogram. Switch matches found here will have the corresponding options selected in time for the first presentation of the screen to show their captions.
This subroutine:
cobc -i, piping the output of that command to a file named gcic-info.txt (in the same folder as the file being compiled)
Token-1, Token-2, ... , Token-5
The following table shows how a variety of cobc -i results would be mined for their configuration information. Words shown in yellow are the words GCINFO looks for while those in green are the ones providing the actual information.
| cobc -i Output | Returned Results | |
cobc (gnucobol) 3.2-dev.20220908 copyright (c) 2022 free software foundation, ... license gplv3+: gnu gpl version 3 or later ... this is free software; see the source for ... warranty; not even for merchantability or ... written by keisuke nishida, roger while, ... built sep 08 2022 20:15:25 packaged sep 08 2022 20:15:02 utc c version (microsoft) 1500 build information build environment : ???????????????? |
GA-Version | "3.2-dev.20220908" |
| GA-Version-No | 00000003 | |
| GA-Release-No | 00000002 | |
| GA-Update-Major-No | "dev " | |
| GA-Update-Minor-No | 20220908 | |
| GA-Release-Date | "08SEP2022" | |
| GA-Build-Date | "08SEP2022" | |
| GA-Build-Env | "????????????????" * | |
| GA-OS-Type | 1 (i.e. Native Windows) | |
cobc (gnu cobol) 2.0.0 copyright (c) 2001,2002,2003,2004,2005,2006,2007 ... copyright (c) 2006-2012 roger while copyright (c) 2009,2010,2012,2014 simon sobisch this is free software; see the source for copying ... warranty; not even for merchantability or fitness ... built jul 11 2014 07:13:23 packaged jan 20 2014 07:40:53 utc c version "4.8.3" build information build environment : i686-pc-cygwin |
GA-Version | "2.0.0" |
| GA-Version-No | 00000002 | |
| GA-Release-No | 00000000 | |
| GA-Update-Major-No | 00000000 | |
| GA-Update-Minor-No | 00000000 | |
| GA-Release-Date | "11JUL2014" | |
| GA-Build-Date | "20JAN2014" | |
| GA-Build-Env | "i686-pc-cygwin" | |
| GA-OS-Type | 2 (i.e. Windows/Cygwin) | |
cobc (gnucobol) 3.2-dev.0 copyright (c) 2022 free software foundation, ... license gplv3+: gnu gpl version 3 or later ... this is free software; see the source for ... warranty; not even for merchantability or ... written by keisuke nishida, roger while, ... built aug 15 2021 19:53:08 packaged aug 15 2021 17:52:29 utc c version "10.3.0" build information build environment : x86_64-pc-linux-gnu |
GA-Version | "3.2-dev.0" |
| GA-Version-No | 00000003 | |
| GA-Release-No | 00000002 | |
| GA-Update-Major-No | "dev " | |
| GA-Update-Minor-No | 00000000 | |
| GA-Release-Date | "15AUG2021" | |
| GA-Build-Date | "15AUG2021" | |
| GA-Build-Env | "x86_64-pc-linux-gnu" | |
| GA-OS-Type | 3 (i.e. *NIX) | |
cobc (gnucobol) 3.1.2.0 copyright (c) 2020 free software foundation, ... license gplv3+: gnu gpl version 3 or later ... this is free software; see the source for ... warranty; not even for merchantability or ... written by keisuke nishida, roger while, ... built sep 24 2021 12:31:22 packaged dec 23 2020 12:04:58 utc c version "4.2.1 compatible apple llvm 11.0.3 ... build information build environment : x86_64-apple-darwin19.6.0 |
GA-Version | "3.1.2.0" |
| GA-Version-No | 00000003 | |
| GA-Release-No | 00000001 | |
| GA-Update-Major-No | 00000002 | |
| GA-Update-Minor-No | 00000000 | |
| GA-Release-Date | "24SEP2021" | |
| GA-Build-Date | "23DEC2020" | |
| GA-Build-Env | "x86_64-apple-darwin19.6.0" | |
| GA-OS-Type | 4 (i.e. MacOS) | |
cobc (gnucobol) 3.1.2.0 copyright (c) 2020 free software foundation, ... license gplv3+: gnu gpl version 3 or later ... this is free software; see the source for ... warranty; not even for merchantability or ... written by keisuke nishida, roger while, ... built jun 28 2022 10:38:00 packaged dec 23 2020 12:04:58 utc c version (mingw) "6.3.0" build information build environment : i686-pc-mingw32 |
GA-Version | "3.1.2.0" |
| GA-Version-No | 00000003 | |
| GA-Release-No | 00000001 | |
| GA-Update-Major-No | 00000002 | |
| GA-Update-Minor-No | 00000000 | |
| GA-Release-Date | "28JUN2022" | |
| GA-Build-Date | "23DEC2020" | |
| GA-Build-Env | "i686-pc-mingw32" | |
| GA-OS-Type | 5 (i.e. Windows/MinGW) | |
| * | Being only able to obtain a sample of cobc -v output for a native Windows build, the actual "build environment" string for such remains a mystery. |
This program, CALLed by GCic only when the user has elected to create a source and cross-reference listing AND the user chose GCic (instead of cobc) as the creator of those listings. There is NO interaction with the user in this program; even the error messages generated by LISTER are actually delivered to the user by the GCic main program via an Exit-Code value passed back to GCic.
LISTER obtains its list of reserved words directly from cobc via the -list-reserved, list-intrinsic, and -list-mnemonic switches, and uses the reports produced by cobc when those switches are used to populate the Reserved Word Table. Unfortunately, cobc doesn't distinguish verbs (actual statement names) from any of the other reserved words. Since LISTER needs to know any time a new PROCEDURE DIVISION statement has been encountered while it's generating the cross-reference listing, this table is used to flag those entries in the Reserved Word Table with a RWT-Type-Code value of "V".
01 ALL-Verbs. *> All GnuCOBOL verbs
05 PIC X(32) VALUE "ACCEPT".
05 PIC X(32) VALUE "ADD".
05 PIC X(32) VALUE "ALLOCATE".
05 PIC X(32) VALUE "ALTER".
05 PIC X(32) VALUE "CALL".
05 PIC X(32) VALUE "CANCEL".
05 PIC X(32) VALUE "CLOSE".
05 PIC X(32) VALUE "COMMIT".
05 PIC X(32) VALUE "COMPUTE".
05 PIC X(32) VALUE "CONTINUE".
05 PIC X(32) VALUE "DELETE".
05 PIC X(32) VALUE "DISABLE".
05 PIC X(32) VALUE "DISPLAY".
05 PIC X(32) VALUE "DIVIDE".
05 PIC X(32) VALUE "ELSE".
05 PIC X(32) VALUE "END". *> Pseudo-verb to pick up "END PROGRAM"
05 PIC X(32) VALUE "ENABLE".
.
.
.
05 PIC X(32) VALUE "START".
05 PIC X(32) VALUE "STOP".
05 PIC X(32) VALUE "STRING".
05 PIC X(32) VALUE "SUBTRACT".
05 PIC X(32) VALUE "SUPPRESS".
05 PIC X(32) VALUE "TERMINATE".
05 PIC X(32) VALUE "TRANSFORM".
05 PIC X(32) VALUE "UNLOCK".
05 PIC X(32) VALUE "UNSTRING".
05 PIC X(32) VALUE "USE".
05 PIC X(32) VALUE "WHEN".
05 PIC X(32) VALUE "WRITE".
05 PIC X(32) VALUE "XML". *> Only GENERATE
05 PIC X(32) VALUE LOW-VALUES. *> Must be last entry
01 All-Verbs-Tbl REDEFINES All-Verbs.
05 Verb-Name OCCURS 61 TIMES
PIC X(32).
When adding (or removing) entries in the This is easily correctable by making the source code change the message recommends and recompiling |
While LISTER is parsing a program during the process of creating a cross-reference listing, some reserved words unimportant to the generation of the xref listing need to be ignored by the parser, if they are found. This table contains those words, and is used to flag Reserved Word Table entries as "buzzwords" to be ignored.
01 Buzzwords. *> Reserved words ignored to simplify parsing
05 PIC X(32) VALUE "ADDRESS".
05 PIC X(32) VALUE "ARE".
05 PIC X(32) VALUE "AS".
05 PIC X(32) VALUE "AWAY-FROM-ZERO".
05 PIC X(32) VALUE "CHARACTERS".
05 PIC X(32) VALUE "IN".
05 PIC X(32) VALUE "IS".
05 PIC X(32) VALUE "KEY".
05 PIC X(32) VALUE "MODE".
05 PIC X(32) VALUE "NEAREST-AWAY-FROM-ZERO".
05 PIC X(32) VALUE "NEAREST-EVEN".
05 PIC X(32) VALUE "NEAREST-TOWARD-ZERO".
05 PIC X(32) VALUE "NOT".
05 PIC X(32) VALUE "OF".
05 PIC X(32) VALUE "OPTIONAL".
05 PIC X(32) VALUE "PROCEED".
05 PIC X(32) VALUE "PROHIBITED".
05 PIC X(32) VALUE "ROUNDED".
05 PIC X(32) VALUE "SEQUENCE".
05 PIC X(32) VALUE "STATUS".
05 PIC X(32) VALUE "TOWARD-GREATER".
05 PIC X(32) VALUE "TOWARD-LESSER".
05 PIC X(32) VALUE "TRUNCATION".
05 PIC X(32) VALUE "WITH".
05 PIC X(32) VALUE LOW-VALUES. *> Must be last entry
01 Buzzwords-Tbl REDEFINES Buzzwords.
05 Buzzword OCCURS 25 TIMES
PIC X(32).
When adding (or removing) entries in the This is easily correctable by making the source code change the message recommends and recompiling |
Whenever a program references a file, any FILE STATUS or SORT STATUS item associated with that file will be updated with the two-digit status code. This table exists so the cross-reference listing can reflect those implied updates.
01 Files-And-Statuses. *> Relates files in parsed program
*> w/ FILE STATUS items defined for them
05 FAST-Sub USAGE BINARY-LONG *> Subscript into table
UNSIGNED
VALUE 0.
05 FAST-Hold-Name PIC X(63). *> Working save area
05 Files-And-Statuses-Tbl OCCURS FASTSIZE TIMES.
10 FAST-Filename PIC X(63). *> File-name
10 FAST-Status PIC X(63). *> FILE-STATUS item (if > 1,
*> multiple table entries)
This table is set to a fixed size by a configuration constant. If the table fills up at runtime the following fatal error will result (the actual numbers may differ): Fatal Error: 'Files-And-Statuses-Tbl' is full - Increase FASTSIZEThis is easily correctable by making the source code change the message recommends (to the FASTSIZE constant in the MAIN program) and recompiling |
Whenever a program reads a file, the various records defined for that file are updated. Any time a program writes a record to a file, not only is the record data item referenced, by the file contents are updated. This table exists so the cross-reference listing can reflect those implied references and updates.
01 Records-And-Files. *> Relates files in parsed program with the records defined for them
05 RAFT-Sub USAGE BINARY-LONG *> Subscript into table
UNSIGNED
VALUE 0.
05 Records-And-Files-Tbl OCCURS RAFTSIZE TIMES.
10 RAFT-Filename PIC X(63). *> Filename
10 RAFT-Recordname PIC X(63). *> Record name (Multiple recs, multiple entries)
This table is set to a fixed size by a configuration constant. If the table fills up at runtime the following fatal error will result (the actual numbers may differ): Fatal Error: 'Records-And-Files-Tbl' is full - Increase RAFTSIZEThis is easily correctable by making the source code change the message recommends (to the RAFTSIZE constant in the MAIN program) and recompiling |
This table contains the various reserved words of the language dialect the program compilation used (-std). After being loaded, the table will be sorted according to it's description to allow it to be searched via SEARCH ALL. While GCic makes the distinction between different classes of reserved words documented in the comments, it is not necessarily using all of the RWT-Type-Code values - just call it preparation for future possibilities.
01 Reserved-Words. *> Populated using the output of "cobc" run
*> with the various "-list-xxxx" switches
05 Reserved-Word-Tbl OCCURS RWTSIZE TIMES
ASCENDING KEY RWT-Word
INDEXED BY RWT-Idx.
10 RWT-Type-Code PIC X(1). *> "B": A buzzword (to be ignored)
*> "D": A device
*> "F": A feature
*> "I": An intrinsic (function)
*> "M": A device mnemonic
*> "R": Just a plain 'ol reserved word
*> "V": A verb
*> "W": A switch name
10 RWT-Word PIC X(32).
This table is set to a fixed size by a configuration constant. If the table fills up at runtime the following fatal error will result (the actual numbers may differ): Fatal Error: 'Reserved-Word-Tbl' is full - Increase RWTSIZEThis is easily correctable by making the source code change the message recommends (to the RWTSIZE constant in the MAIN program) and recompiling |
The ADD, SUBTRACT, MULTIPLY, DIVIDE, RELEASE, REWRITE, and WRITE statements present a challenge to producing a cross-reference listing that differentiates between simple references and updates because all of these statements allow the use of a clause that reverses initial assumptions made the reference/update status of user-defined items named on the statements.
For the arithmetic statements, it's the presence or absence of a GIVING clause. Observe these two ADD statements:
ADD A TO B
ADD A TO B GIVING C
In the first case, A is referenced while B is updated. In the second, both A and B are referenced and it's C that's actually updated. With the I/O statements, it is the FROM clauses that cause problems:
WRITE A
WRITE A FROM B
The first statement references A, while the second references B and updates A
The solution to this problem, is the following:
01 Stack.
05 Stack-Sub PIC 9(4).
05 Stack-Entry OCCURS STACKSIZE TIMES
PIC X(244). *> Must be the same size as Sort-Work-Rec
The data collection portion of the cross-referencing process actually runs as the INPUT PROCEDURE of a SORT statement, with the OUTPUT PROCEDURE being the report production. During the INPUT PROCEDURE, references and updates are usually easily differentiated from each other and are immediately released to the sort as they are found. In the cases of these problem-statements, the sort records are still built, for whatever mode would be the case if no GIVING or FROM were present, but are then "pushed" onto the stack rather than getting released to the sort. If a GIVING or FROM is found before the end of the statement, the entries are popped off the stack, one at a time, reversed so that references become updates and updates become references, and are then released to the sort. If the statement ended before a GIVING or FROM was found, the entries on the stack each get popped and released to the sort as-is.
This table is set to a fixed size by a configuration constant. If the table fills up at runtime the following fatal error will result (the actual numbers may differ): Fatal Error: 'Stack-Entry' is full - Increase STACKSIZEThis is easily correctable by making the source code change the message recommends (to the STACKSIZE constant in the MAIN program) and recompiling |
01 Symbol-Table.
05 ST-Sub PIC 9(4). *> Subscript into "ST-Entry"
05 ST-Entry OCCURS STSIZE TIMES *> Entry for a non-FILLER, 66, 77, 78 item
INDEXED BY ST-Idx. *> Second way to point to "ST-Entry"
10 ST-Level PIC X(2). *> Data item's level number
10 ST-Name PIC X(30). *> 1st 30 chars of data item's name
10 ST-Name-UC PIC X(30). *> UPPER-CASE copy of "ST-Name"
This structure is used during LISTER's creation of the cross-reference listing. The structure is loaded from the symbol table report built by cobc (-ftsymbols). Here's a sample group item:
01 Employee-Record.
05 ER-Name.
10 ER-First PIC X(15).
10 ER-Last PIC X(20).
05 ER-Address.
10 ER-Street PIC X(20).
10 ER-City PIC X(15).
10 ER-State PIC X(2).
10 ER-Zip.
15 ER-Zip-5 PIC 9(5).
15 ER-Zip-4 PIC 9(4).
Here's what the portion of the table that pertains to the above structure would look like:
..... Previous Structure...
01Employee-Record EMPLOYEE-RECORD
05ER-Name ER-NAME
10ER-First ER-FIRST
10ER-Last ER-LAST
05ER-Address ER-ADDRESS
10ER-Street ER-STREET
10ER-City ER-CITY
10ER-State ER-STATE
10ER-Zip ER-ZIP
15ER-Zip-5 ER-ZIP-5
15ER-Zip-4 ER-ZIP-4
01... Next Structure ...
Consider the statement MOVE SPACES TO ER-Zip, which occurs at line 677 of a compilation group for which source and cross-reference listings, prepared by GCic, have been requested. This results in the generation of a "677*" xref for "ER-Zip".
One of the design goals for V2.0 of GCic was to propagate update xrefs both upward and downward in the tree structures represented by group items. So, the MOVE will also generate additional "677*" xrefs for other items in the structure by applying the following algorithm.
When applied to the "MOVE" statement mentioned earlier, this algorithm will generate additional "677*" xrefs for "ER-Address", "Employee-Address", "ER~Zip-5", and "ER-Zip-4".
This table is set to a fixed size by a configuration constant. If the table fills up at runtime the following fatal error will result (the actual numbers may differ): Fatal Error: 'ST-Entry' is full - Increase STSIZEThis is easily correctable by making the source code change the message recommends (to the STSIZE constant in the MAIN program) and recompiling |
Before attempting to modify any of the code in GCic, you should be aware of the following design principles if you plan on sharing those changes with the community.
DATA DIVISION sections have been defined in alphabetical order of their top-level data names.
GO TO statements have been avoided wherever possible. The only place they are used is within the Finite State Machine in LISTER.
PERFORM statements are used, they always reference SECTIONs. What few GO TO statements exist only reference paragraphs within the same SECTION as they are.
000-Main always being the root of the tree (that is, the one at the very top). The sections at the next layer - numbered 100, 200, 300, and so on, represent the top-levels of up to nine common threads of activity. In the LISTER program, for example:
100-Initialization.
200-Build-Keyword-Table.
300-Produce-Source-Listing is responsible for generating the program source listing
400-Tokenize-Source.
500-Produce-Xref-Listing.
PERFORMed by multiple procedures, maybe even from multiple subtrees, are numbered 0nn.
PERFORM. Please keep these current as you make any changes.
Should you decide to make changes to GCic or any of it's subprograms, you may find the built-in debugging capabilities useful. This feature will allow you to add debugging switches to the GCic command-line, after the name of the file you are compiling. Debugging information will then be written to SYSERR (or STDERR) for you to review. To activate these features, you will need to either:
cobc -x -fdebugging-line GCic.cbl, or...
path\GCic yourprogfile switch-1 [ switch-n ]... 2>filename
All debugging output will be piped to filename; each line of output will be prefixed with the name of the switch that caused it. This is especially useful if your text editor has the ability to hide lines matching (or not matching) a mask!
| Command-Line Switch Name | Switch Data-Item Name | Program(s) | Description |
| ALL | None | All | Turns on every debugging switch. |
| INFO | INFO-Sw | GCINFO |
Displays the "thought process" as GCINFO acquires the information it seeks. |
| SOURCE | SOURCE‑Sw | LISTER |
Displays the handling of program source during the process of generating the source code listing. |
| SPLIT | SPLIT-Sw | LISTER |
Displays the splitting of the cobc output file into the formatted sourcencode and symbol table files. |
| SUB | SUB-Sw | GCic |
Displays the "thought process" as GCic determines if the to-be-compiled program is a subroutine or not (020-Is-Prog-A-Subprogram). |
| TRACE | TRACE-Sw | All | Generates a procedure-entry trace of all procedures in all programs. |
| USER | USER-Sw | GCic |
Logs all mouse-clicks, action key-presses (Enter, Esc, PgUp, PgDn), and the contents of the input fields. |
| XALL | None | LISTER |
Turns on all "X..." switches. |
| XFAST | XFAST-Sw | LISTER |
Displays Files-And-Statuses-TBL (FAST) entries as they are saved. |
| XFSM | XFSM-Sw | LISTER |
Traces the state-by-state, character-by-character operation of the finite state machine (FSM) that parses GnuCOBOL programs while a cross-reference listing being generated. |
| XPARSE | XPARSE-Sw | LISTER |
Produces diagnostic displays of information documenting the "thought process" the parser is going through while identifying and properly recognising the user-defined data names found in the FSM output. |
| XRAFT | XRAFT-Sw | LISTER |
Displays Records-And-Files-Tbl (RAFT) entries as they are saved. |
| XREAD | XREAD-Sw | LISTER |
Displays program expanded source code as it is being read and having its contents prepared for parsing. The records will be dumped AFTER the transformation they undergo to be prepared for parsing has taken place. |
| XTOKEN | XTOKEN-Sw | LISTER |
Displays the recognized syntactical tokens that are generated by the finite state machine and parser. |
| XWORDS | XWORDS-Sw | LISTER |
Displays the Reserved-Word-Tbl once it's been loaded, sorted, and tailored. |
These switches are defined in the following structure:
DEBUG D01 Debug-Switches EXTERNAL.
DEBUG D 05 INFO-Sw PIC 9(1).
DEBUG D 05 SOURCE-Sw PIC 9(1).
DEBUG D 05 SPLIT-Sw PIC 9(1).
DEBUG D 05 SUB-Sw PIC 9(1).
DEBUG D 05 TRACE-Sw PIC 9(1).
DEBUG D 05 USER-Sw PIC 9(1).
DEBUG D 05 X-OPTIONS.
DEBUG D 10 XFAST-Sw PIC 9(1).
DEBUG D 10 XFSM-Sw PIC 9(1).
DEBUG D 10 XPARSE-Sw PIC 9(1).
DEBUG D 10 XRAFT-Sw PIC 9(1).
DEBUG D 10 XREAD-Sw PIC 9(1).
DEBUG D 10 XREF-Sw PIC 9(1).
DEBUG D 10 XTOKEN-Sw PIC 9(1).
DEBUG D 10 XWORDS-Sw PIC 9(1).
There are seven subroutines in the gcic.cbl compilation unit that are CALLed to generate debugging output of varying types. Here are those routines.
This subroutine generates a dump of the contents of up to six USAGE DISPLAY data items, separated from one another by "|" characters.
CALL "DBGCOL" USING debug-switch
"debug-switch-name"
"title"
identifier-n...
END-CALLThe first two arguments are the same for all six routines. The debug-switch is the name of one of the debug switches, as defined in the previous table - for example, TRACE-Sw, XFSM-Sw, USER-Sw, and so on. The value of this data item will be either 1 or 0, depending on whether the switch was coded on the gcic command (1) or not (0). if the switch value is 0, the subroutine immediately returns without generating any output.
The second argument is the name of the command-line switch that is associated with the debug switch.
The third argument is a brief title for the output.
The remaining one to six arguments are the names of the data items to will have their contents dumped.
Assuming the following CALL to this routine:
CALL "DBGCOL" USING USER-Sw "USER" "Sample:" AA BB CC DD EE FF END-CALL
And also assuming the six data items have the values "One", "Two", "Three", ... , then the output would be:
USER...........Sample:One|Two|Three|Four|Five|Six
PURPOSE
CALL "DBGDUMP" USING debug-switch
"debug-switch-name"
"title"
identifier-1
END-CALLThe third argument is a brief title for the output.
The fourth argument is the name of the data item to will have its contents dumped.
Assuming the following CALL to this routine:
CALL "DBGDUMP" USING XPARSE-Sw "XPARSE" "Record:" Source-Record END-CALL
And also assuming that Source-Record contains an end-of-image delimited "MOVE SPACES TO Output-Rec" statement, then the expected output would be:
XPARSE.........Record: <Byte> <-------------------------- Hexadecimal --------------------------> <--------- Character ---------->
XPARSE.........Record: 1 2020202020202020 2020204D4F564520 5350414345532054 204F757470757420 MOVE SPACES TO Output
XPARSE.........Record: 33 2D52656320202020 2020202020202020 2020202020202020 2020202020202020 -Rec
XPARSE.........Record: 65 2020202020202020 2020202020202020 2020202020202020 2020202020202020
XPARSE.........Record: 225* 2020202020202020 2020202020202020 2020202020202020 2020202020202020 ØThis subroutine, intended for use exclusively with the TRACE switch, announces that control is entering a new subroutine or procedure.
CALL "DBGENTER" USING TRACE-Sw
"TRACE"
"procedure-or-subroutine-name"
END-CALLThe third argument is the name of the subroutine (1st character is a letter) or a PERFORMed procedure (1st character is a digit).
Assuming the following CALLs to this routine are coded at the beginning of the GCINFO routine's PROCEDURE DIVISION:
CALL "DBGENTER" USING TRACE-Sw "TRACE" "GCINFO" END-CALL
CALL "DBGENTER" USING TRACE-Sw "TRACE" "000-Main" END-CALLThen the output would be:
TRACE..........Entering routine GCINFO
TRACE..........Entering 000-Main
The second routine intended for use with the TRACE debug switch, this routine announces the return of a PERFORMed procedure to the procedure which invoked it.
CALL "DBGEXIT" USING TRACE-Sw
"TRACE"
END-CALLAssuming the following CALL to this routine was made from within the 100-Initialization procedure in the MAIN program:
CALL "DBGEXIT" USING TRACE-Sw "TRACE" END-CALL
Then the following output would be generated:
TRACE..........Exiting 100-Initialization, Returning To 000-Main
This subroutine walks-back the sequence of nested PERFORMs (if any) and announces the CALLing subroutine's exit.
CALL "DBGGOBACK" USING TRACE-Sw
"TRACE"
END-CALLAssuming that MAIN has CALLed LISTER, and LISTER has encountered a fatal condition that forces it to return to it's CALLer prematurely. The following CALL to this routine:
CALL "DBGGOBACK" USING USER-Sw "USER" END-CALL
Would then produce this output:
TRACE..........Canceling Return To 100-Initialization Of LISTER
TRACE..........Canceling Return To 000-Main Of LISTER
TRACE..........Exiting LISTER From 099-GOBACK, Returning To 400-Generate-Listing Of MAIN
This subroutine generates a dump of the contents of up to three USAGE DISPLAY data items, each presented in a keyword="value" format. There can be as many as three sets of the last two arguments.
CALL "DBGKWV" USING debug-switch
"debug-switch-name"
{ "text-n" identifier-n }...
END-CALLThe third argument is the "keyword" portion of the display, while the fourth argument is an identifier whose contents will be the "value" portion of the display. There may be as many of three occurrences of these two arguments.
Assuming the following CALL to this routine:
CALL "DBGKWV" USING USER-Sw "USER" "Sample:" "AA" AA "BB" BB "CC" CC END-CALL
And also assuming the three data items have the values "One", "Two", "Three", then the output would be:
USER...........AA="One" BB="Two" CC="Three"
This subroutine walks-back the sequence of nested PERFORMs and CALLs, (if any), and announces the program's halt.
CALL "DBGSTOP" USING TRACE-Sw
"TRACE"
END-CALLAssuming that MAIN has CALLed LISTER, and LISTER has encountered a fatal condition in 100-Initialization that forces it to halt the program without returning, the following CALL to this routine:
CALL "DBGSTOP" USING TRACE-Sw "TRACE" END-CALL
would then produce this output::
TRACE..........TRACE..........Canceling Return To 000-Main Of LISTER
TRACE..........Canceling Return To 400-Generate-Listing Of MAIN
TRACE..........Canceling Return To 000-Main Of MAIN
TRACE..........Halting Program In 100-Initialization Of LISTER
This subroutine is used to display a text message in the debugging output.
CALL "DBGTXT" USING debug-switch
"debug-switch-name"
"text"
END-CALLThe third argument is the text to display.
Assuming the following CALL to this routine:
CALL "DBGTXT" USING USER-Sw "USER" "Already Scanned for PSS" END-CALL
Then the output would be:
USER...........Already Scanned for PSS
The source code to GCic has grown to over 6000 lines of code, between all seven programs. In effort to reduce "clutter" in the code, software changes will now be placed in this document.
Legend to initials used:
Immediately upon starting and retrieving the command-line arguments, gciclock will create the lock file (with a simple OPEN OUTPUT followed immediately with a CLOSE). It then waits for the OS to notify it that the GCic process that spawned it has terminated.
Once the GCic process terminates for any reason INCLUDING an abort, Ctrl-C, Ctrl-Break, or a window close, the gciclock task will be awakened and will delete the lock file immediately before it too terminates.
ENVIRONMENT DIVISION of the MAIN program, the screen color palette configuration (a series of 78-level constants) has been moved to the beginning of the MAIN program's SECTION SECTION, and the debug-switches and GCInfo-Arg structures have been moved to the programs that need them.
OS configuration constant still exists, but now expects a numeric integer value in the range 0 to 5. A setting of 0 (the default setting) indicates auto-detection should be performed while 1-5 defines a specific environment of Native Windows, Windows/Cygwin, *NIX, MacOS, and Windows/MinGW, respectively. These values of 1-5 should be resorted to only if auto-detection fails to identify the environment.
resize command requires the installation of X11, and the usage of an xterm-compliant terminal/console emulator. While not a problem for MacOS users, where X11 is standard, this does pose a problem for *NIX users that have chosen not to install X11 on their systems. A new configuration constant - X11 - has been introduced into gcic-setup.cpy so that *NIX users may turn off the attempt to use resize.
RESIZECMD - has been introduced into gcic-setup.cpy so that a user-specified alternative command (or series of commands, separated by ";", "││", or "&&") may be specified to perform the terminal/console window resizing. The $SET statement for this may not exceed the GnuCOBOL statement length in effect when gcic-setup.cpy is COPYed.
ACCEPT and deleting it immediately after the ACCEPT. When GCic starts, if the lock file already exists (part of it's name is the filename being compiled), the attempt to compile is rejected because another instance of GCic is already doing so. Clicking the "X" to close the GCic window, however, will leave the lock file in-place - requiring manual intervention to delete it before the program can be compiled again via GCic. None of this has any impact on the ability to compile directly with cobc.
gcic-setup.cpy".
gcic-setup.cpy proc.
*> COBC Switches: -facucomment -fwrite-after -fsingle-quote, which make great documentation for someone who might need to compile a program, can now be recognized by GCic and used to put the specified switches on the cobc command. See the Program-Specified Switches topic for more information.
terminal in MacOS); Fully tested with MacOS (required a few alterations); Expanded both extra-options and runtime-arguments areas to 2 lines (152 chars total) each; Added support for MF/IBM/BS2000 listing-control directives EJECT,SKIP1,SKIP2,SKIP3 (any of these in copybooks will be ignored).cobc switch specified.cobc command.