GNUCOBOL (già OpenCobol) Italian Group

Nuova versione settembre 2019

Change language

How does it work.

There is an idea behind guicobol. use the cobol itself to manage an advanced gui. No superstructures just cobol and advanced widgets. The syntax object in my opinion is functional to this. Gnucobol does not yet support the "invoke" understood as a real statement, therefore GuiCOBOL takes advantage of this lack by integrating the runtime construction of a gui with the invokes. So one instruction like invoke super "addform" returning self returns an object that specifically in accordance with the rules of oop is the instance of the form in execution (self).The other instruction to access the properties of objects is the classic "move" where the property itself is referenced through quotes then one move "this is the window" to "caption" of self inserts the string "this is the window" as the value of the "caption" property of the window object on the current form. Simple and intuitive.

depending on the direction of the move

you can do a set statement with  move value to "property" of widget

or get with  move "property" of widget to value

The gui cobol preprocessor does the "dirty" work ...behind the scenes an instruction becomes

move "yellow" to "color" of self.

becomes (inline code)

* move "yellow" to "color" of self.
call static "AG_SetStyle" using by value agar-Form by content "color"
by content '#FFFF00'


move "property" of object to value

move "text" OF atext to yourbuffer.


* move "text" OF atext to yourbuffer.
move atext to agar-widget
move "get-text" to agar-function
call agar-cobol
move agar-text to yourbuffer .
As far as invokes are concerned, the preprocessor carries out as a formal check that the number of parameters indicated in the row are the minimum and maximum ones possibly present in the relative header of the declaration in guicobol.Inf. and from the same file derives the structure that it will have to insert in the generated code. So if you want to integrate the pre-processor just insert the skeleton of the new instruction and call the agar library directly in the guicobol.inf file which contains the logic of these declarations

invoke self "show"

in the generated .gui file becomes

* invoke self "show"
move agar-Form to agar-widget
move "set-visible" to agar-function
call agar-cobol

and in the agarcob source code you have the set-visible perform invoked

perform get-class thru ex-get-class. evaluate agar-class
when "form"
call "AG_WindowShow"
using by value agar-widget returning omitted
when other call "AG_WidgetShow"
using by value agar-widget returning omitted.
call static "AG_ObjectGetClassName"
using by value agar-object
by value 0
returning agar-dummy
set address of agar-string TO agar-dummy.
Evaluate function upper-case( agar-string(4:3)) when "WIN" MOVE "form" to agar-class
when "BOX" MOVE "box" to agar-class
when "LAB" MOVE "label" to agar-class
when "TEX" MOVE "text" to agar-class
when "RAD" MOVE "radio" to agar-class
when "CHE" MOVE "check" to agar-class
when "COM" MOVE "combo" to agar-class
when "BUT" MOVE "button" to agar-class
when other
agar-string(4:3) to agar-class
display "new class -->" agar-class upon syserr
end-evaluate. ex-get-class.

Take care at

At the moment the code generator expects to find all the instruction on a single line even if this exceeds the conventions of the standard Cobol margins. However, it is necessary to note that if a very long constant is used when it is repositioned by the preprocessor in the transformation of the code, it will probably be necessary to make a subsequent modification on the source generated once the process has been successfully completed. Guicobol simply creates a new file with the .gui extension which can be compiled in a conventional way with the gnucobol compiler, indicating any options if necessary and possibly passing it to the animator (renaming it .in gui.cbl) if necessary. All the original instructions of the cobol program are reported in the generated file as comments and under all the generated instructions. There are also a series of additional elements in working storage that the preprocessor inserts to report the values ​​of the objects that it will use internally, the standard procedures connected to the close form (if you do not indicate a precise one) and the whole structure of the methods that are all the effects of the complete cobol programs. For the events to reduce the code and improve the readability when they are created in the original code they are only identified by a "method-id" header. Some of these procedures generated by the preprocessor are inline code since the execution of the same through the agarcob library it would be more expensive in terms of accesses and number of lines of code executed In these cases, be careful because the switch to activate the debugging mode present in the guicobol, if activated, affects only the control of the code inserted in the agarcob library. (export GuiCOBOLdebug = enable).


Powercobol (from Fujitsu ltd) and this Open Source project have some similarities and others observed different. In general, the approach to objects follows the rules of Powercobol. The most important difference of all is that the objects on Powercobol must be instantiated during the design phase (and Powercobol has a splendid WYSIWYG editor) and the development environment itself is extremely evolved and performing. In Guicobol it is possible to generate instances instead of a runtime with the "add" methods ... addform addlabel..ecc.ecc. Powercobol projects are totally dependent on the development environment and the project code is all written in a proprietary format. The code managed by guicobol is always a conventional cobol source. It's okay to smell the code writing the preprocessor takes care of manually incorporating some methods in the basic functions. This means, for example, that the module when it is generated has a recall procedure for closing created by default (when this has not been defined by the programmer anyway). All the object fields that are declared in order to refer the instances of the objects must also be observed in the individual event procedures in the relative work-archiving area of ​​the single programs connected to the callback. Guicobol will consent to omit the writing of this code which will instead be managed automatically by the preprocessor This means that in the first main operating memory indicated it indicates all the fields that are used for the objects and the same instructions which then relocate all inside the individual working-storage generates preprocessor. Furthermore, the same methods connected to the events require an extremely minimal structure, therefore it will be sufficient to indicate them in the Method-Id header "name of the procedure" associated with the event to write under the code entered as already present in the presence of a DIVISION PROCEDURE. the intermediate code is added by the preprocessor.


Guicobol has several kind of widgets: containers which are the base where you have to create your form widgets bottons, static label, combo, tabs and other.Actually I make first release of some of them but I have to prepare still a lot of them.. libagar has strong and beautilful objects rich of features.
You have to make first the window you can create the object by using a simple invoke SUPER "addform" returning SELF.
Then depending if you want to mange widget with fixed position you have to create a fixed or box containers






















and now ..a complete sample


List Widgets methods events and properties

addbox method makes a box container

invoke {PARENT} "addbox" returning abox where:{PARENT} is the container (self is the form) abox is a object reference field declared in the working storage eg: "01 widget   usage object." an example of declaration could be invoke self "addbox" returning awidget

addbutton method makes a simple button widget
invoke {PARENT} "addbutton" using  {button-caption} returning awidget
addbuttonto method makes a button and map it "to" a callback procedure
invoke {PARENT} "addbuttonto" using  {button-caption} {cobol_procedure} returning awidget
addcheck method makes a checkbox widget
invoke {PARENT} "addcheck" using  {check-caption} returning awidget
addcheckto method makes a checkbox and map it "to" a callback procedure
invoke {PARENT} "addcheckto" using  {check-caption}  {cobol_procedure} returning awidget
addcombo method makes a simple combo
invoke {PARENT} "addcombo" using  {combo-caption} returning awidget
addevent method adds a callback procedure for a specific event (if one procedure already is map on this goes running after that so no replace but becomes performed sequentially
INVOKE {object} "addevent" using {event} {cobol_procedure}. Where event is one that can reached from the kind of object  eg. "textbox-return" & X"00 is when a enter is pressed on a text box field. n.b. Events name follows the "c" rules for the string (must be terminated by X"00" null character)
addfixed method adds a fixed container to the parent
invoke {PARENT} "addfixed" returning awidget
addform method adds the form (SELF)
invoke SUPER "addform" returning awidget
addframe method adds a vertical box container
invoke {PARENT} "addframe" returning awidget
addhoriz method add an horizontal separator line invoke {PARENT} "addhoriz"
additem method adds an item to the appropriate object
invoke {object} "additem" using "this is my item" (depenging on the object instance that shold be a radio , combo, option or tlist widget
addlabel method makes a label widget upon the parent container
invoke {PARENT} "addlabel" returning awidget
addnumeric method makes a numeric widget

invoke {PARENT} "addnumeric" using "Value"  returning anumber usually followed by the other properties to manage the bind

move min      to "min" of anumber
move max     to "max" of anumber
move val       to "numeric" of anumber
move 1         to "increment" of anumber

where definition for numeric field are:

01 min                  usage binary-c-long.
01 max                 usage binary-c-long.
01 val                   usage binary-c-long external.

addpane method makes a pane container
invoke {PARENT}"addpane" using {orientation} returning abox abox1. {orientation} must be "vertical" or "horizonat" or "v" or "h for short definition. abox and abox1 are both containers where you can add you widgets
addprogress method makes a progressive bar

addradio method makes a radio widget

addradioto method makes a radio widget and map it to a callback procedure

addscroll method makes a scrollbar horizontal widget

addscrollv method makes a scrollbar vertical widget

addscrollview method makes a scrollview widget

addslider method makes a slider widget

addspaceshoriz method adds horizontal spaces
addspacesvertic method adds verticals spaces
addtext method makes a textbox widget
addvertic method adds a vertical line separator
close method closes the running event manager
closed method maps a callback at the closed event
connect method binds a textbox field to a buffer
disable method makes the object disabled
enable method makes the object enabled
expand method expands all widgets to horizontal and vertical
expandheight method expands objects to the height
expandwidth method expands object to the width
get-caption property returns the caption of the object
get-cursor property returns current cursor position in the textbox
get-focused property returns the widget object who has the focus
get-class property returns the class of the object
get-name property returns the name of the object
get-object property returns the object for the invoked name of widget
get-width property returns the width of the widget (for a fixed child object)
get-height property returns the height of the widget (for a fixed child object)
get-top property returns position x of the widget (for a fixed child object)
get-left property returns position y of the widget ((for a fixed child object)
get-parent property returns widget parent
get-root property returns the root for the invoked object
get-text property returns the text value
get-value property returns a boolean value from a check or option (true or false) if checked...
gotfocus method obtains the focus
hide method hides the object
if-get-is-widget method (work in progress...)
minimize method makes minimized the form
maximize method makes maximized the form
move method moves the object at x y cartesian coordinates
refresh method forces a refreh of the widget
run method runs the eventmanager loop
set-cursor property locates the cursor in the text position indicated by the value
set-decimal property binding al valore attuale di progressive/Scrollbar widget (float)
set-error property shows an error message
set-info property shows an info message
set-warning property shows a warning  message
set-numeric property binding to the cobol field the value of progressive/Scrollbar widget (integer)
set-min property sets the minimum value of a progressive/Scrollbar widget
set-max property sets the max value of a progressive/Scrollbar widget
set-mindecimal property sets the minimum value of a progressive/Scrollbar widget with decimal
set-maxdecimal property sets the maximum value of a progressive/Scrollbar widget with decimal
set-increment property sets the increment value for Scrollbar, numeric, progressive
set-incrementdecimal property sets the increment value for Scrollbar, numeric, progressive with decimal
set-bordercolor property sets assign the color to the border of the object
set-backcolor property sets assign the color to the backtext of the object
set-caption property sets assign the text  to the caption of the object
set-color property sets assign the color to the text of the object
set-isdecimal property forces decimla input for the widget
set-font property sets a  font for the widget
set-fontsize property sets la dimensione del font all'oggetto
set-fontstyle property sets lo stile al font dell'oggetto
set-fontweight property sets the peso al font dell'oggetto
set-homogenous method suddivide lo spazio in modo omogeneo tra i widget dell'oggetto
set-maxitem property sets the max items for the object (eg. combo)
set-prompt property testo da showsre se campo vuoto
set-width property sets la larghezza del widget (su container fixed)
set-height property sets l'altezza del widget (su container fixed)
set-top property sets the x  coordinate for the widget (su container fixed)
set-left property sets the y  coordinate for the widget (su container fixed)
set-name property sets the name of the widget to the passed string
set-position property declares the position of form
set-isnumeric property forces l'input di valori numerici
set-render property exposes the textedit in the specific render text
set-size property exposes the  slider size in pixel
set-text property sets the valore alla proprieta "text" dell'oggetto
set-textcolor property sets the valore del colore del testo dell'oggetto
set-value property sets the value of the widget (true or false) used for check or options widgets
set-visible property sets the obkect visible
show method come the precedente tramite invoke
showform method shows the form
size method sets la dimensione alla window - per gli altri widget solo su elementi disposti su fixed
stoprun method breaks of the eventmanager
zoomin method increases font for all widget upon the form size
zoomout method decreases font for all widget upon the form size
zoomReset method reset to the default font for all widget upon the form size
Enabledebug method sets on the debug features hence forth point
Disabledebug method sets off the debug features hence forth point
  here a short sample 

000010 IDENTIFICATION DIVISION. 000020 PROGRAM-ID. demo2. 000030 ENVIRONMENT DIVISION. 000040 DATA DIVISION. 000050 WORKING-STORAGE SECTION. 000060 01 abox usage pointer external. 000070 01 alabel usage pointer external. 000080 000100 PROCEDURE DIVISION. 000110 000120 invoke SUPER "addform" returning SELF. 000130 000140 move "GuiCOBOL TEST" to "caption" of self 000150 000160 move "orangered" to "color" of self. 000170 000180 invoke self "addbox" returning abox 000190 000200 move "this is a box" to "caption" of abox 000210 000220 move 1 to "homogenous" of abox 000230 000240 invoke abox "addlabel" using "simple line" returning alabel. 000250 000260 invoke abox "addlabel" using "another simple line" returning alabel. 000270 000280 invoke self "show" 000290 000300 invoke SELF "Closed" using "exitForm" 000310 000320 invoke SELF "run" 000330 000340 stop run. 000350 000360 end program demo2. 000370 000380 method-id. exitForm. 000390 000400 procedure division. 000410 000420 invoke self "close". 000430 000440 invoke self "stoprun". 000450 000460 exit program.000470 end method. 000480 000490

000002  PROGRAM-ID.    demo2.
000006           copy "global".
000007  01 abox                 usage pointer external.
000008  01 alabel               usage pointer external.
000270*          invoke SUPER "addform" returning SELF.
000010      move "addform"             to agar-function
000011      call agar-cobol
000012      if agar-main = NULL  move agar-object to agar-main end-if
000013      move  agar-object          to
000014      agar-Form
000015             .
      *          move  "GuiCOBOL TEST"  to "caption" of self
000016      move "set-caption"         to agar-function
000017      move  "GuiCOBOL TEST"
000018                                 to agar-text
000019      move
000020      agar-Form
000021                                 TO agar-object
000022      call agar-cobol
      *          move "orangered" to "color" of self.
000023     call static "AG_SetStyle" using
000024         by value
000025      agar-Form
000026            by content "color"
000027            by content
000028             '#FF4500'
000029     end-call
000031* this note will be added to the gui source
            *          invoke self "addbox" returning  abox
000034      move
000035      agar-Form
000036                                 to agar-object
000037      move "addbox"            to agar-function
000038      call agar-cobol
000039      move                       agar-widget to
000040      abox
            *        move "this is a box" to "caption" of abox
000041      move "set-caption"         to agar-function
000042      move "this is a box"
000043                                 to agar-text
000044      move
000045      abox
000046                                 TO agar-object
000047      call agar-cobol
            *          move 1 to "homogenous" of abox
000048         CALL  STATIC  "AG_BoxSetHomogenous"
000049          using by value
000050      abox
000051              by value 1
000053          end-call
             *          invoke abox "addlabel" using "simple line" returning alabel.
000054      move
000055      abox
000056                                 to agar-object
000057      move
000058      "simple line"
000059                                 to agar-text
000060      move "addlabel"           to agar-function
000061      call agar-cobol
000062      move                       agar-widget to
000063      alabel
000064             .
             *          invoke abox "addlabel" using "another simple line" returning alabel.
000065      move
000066      abox
000067                                 to agar-object
000068      move
000069      "another simple line"
000070                                 to agar-text
000071      move "addlabel"           to agar-function
000072      call agar-cobol
000073      move                       agar-widget to
000074      alabel
000075             .
               *          invoke self "show"
000076      move
000077      agar-Form
000078                                 to agar-widget
000079      move "set-visible"         to agar-function
000080      call agar-cobol
               *          invoke SELF  "Closed" using "exitForm"
000082**  link the event to the required procedure
000084      move
000085      agar-Form
000086                                 to agar-object
000087      set agar-callback          to entry
000088      "exitForm"
000089      move
000090      "exitForm"
000091                                 TO agar-procedure
000092      move "window-detached" & X"00"   to agar-event
000093      move "setevent"            to agar-function
000094      call agar-cobol
             *          invoke SELF "run"
000095      call "AG_EventLoop" returning  agar-eventManager
000096           stop run.
000097  end program demo2.
000098  identification division.
000099  program-id. exitForm.
000100  environment division.
000101  data  division.
000102  working-storage section.
000103       copy "global".
000104       copy "working".
000105  procedure division.
              *           invoke self "close".
000106      call "AG_QuitGUI" using by value 0
000107         returning omitted end-call
000108             .
              *           invoke self  "stoprun".
000109      call "AG_Terminate" using by value 0
000110          returning omitted end-call
000111             .
000112            exit program.
000113 end program exitForm. 

Download batch for GuiCOBOL under Windows

These windows batch can help to manage the source you are writing.       
  • cobagar compiles your agarcob.cbl making the agarcob.dll librar
  • animagar compiles the agarcob.cbl for animating
  • cobgui compiles a ".cbl" and make and build the ".gui" as ".exe" (default)
  • animate compiles a ".cbl" and make a ".exe" animated executable
  • anigui invokes the animator for a ".gui" file
  • cobcbl compiles a ".cbl" adding agar libraries without invoking GuiCOBOL
  • animcbl animates a ".cbl"  without invoking GuiCOBOL
  • menu just lists the available batch files.

Frequently Asked Questions

-It is possible to use TP-COBOL-DEBUGGER to animate a guicobol program?

Yes you have to use -k animator feature to join both environment (guicobol and tp-cobol-debugger)

guicobol %1.cbl
animator %1.gui -k -c
cobc %1.ani -x -v -fno-gen-c-decl-static-call -LC:/cygwin64/usr/local/lib -lag_gui -lag_core -I"C:/cygwin64/usr/local/include/agar" -I"C:/cygwin64/usr/include/SDL" -I"c:/cygwin64/usr/include/freetype2" -I"C:/cygwin64/usr/include/libpng16" -I"C:/cygwin64/usr/include/freetype2" -I"C:/cygwin64/usr/include/uuid" -L"C:/cygwin64/usr/lib" -lSDL.dll -lfreetype -lfontconfig -lfreetype -lopengl32 -lgdi32 -lX11 -lXinerama -lm -ljpeg -lpng16 -lwinmm

in this example guicobol make its .gui result file. then the animate uses it and make the debug intermediate cobol code (.ani) by using the -k feature (keep the internal ani file) then you have to compile the .ani file with the libraries

- how does it run the internal debugger of Guicobol ?

Guicobol has the capability to start the internl debugger (that view a console with agacob parameters used). You can set on its environement variable GuiCOBOLdebug=enable to run it at every call otherwise you can decide to start it only in specific section of your code so in this case you have to invoke where you want to put it on or off these sentences:

invoke super "EnableDebug"

invoke super "DisableDebug"


-Can I define a specific range of code where I want to use the animator inside a guicobol program with TP-COBOL-DEBUGGER ?

Guicobol can make a lot of internal code to manage a cobol debugger section You can avoid to spent time during the execution for sections you wanto to evaluate. in these cases you have only to to set SET-DEBUG-ON

before the line you want to start the debugger and e SET-DEBUG-OFF where you want to stop the evaluation.

It's better then start your procedure with SET-DEBUG-OFF to turn off the analysis and after use on and of

to manage the sections you want to investigate ...so after that you have only to run the animator with

c:\>animator -x yourcode) since this directives are working during the generation of cobol code.

-Can I use TP-COBOL-DEBUGGER to animate only the agarcob.dll guicobol library ?

Yes since the agarcob required a .dll format you have only to check to run the cobc without -x parameter

guicobol %1.cbl
animator %1.gui -k -c
cobc %1.ani -v -LC:/cygwin64/usr/local/lib -lag_gui -lag_core -I"C:/cygwin64/usr/local/include/agar" -I"C:/cygwin64/usr/include/SDL" -I"c:/cygwin64/usr/include/freetype2" -I"C:/cygwin64/usr/include/libpng16" -I"C:/cygwin64/usr/include/freetype2" -I"C:/cygwin64/usr/include/uuid" -L"C:/cygwin64/usr/lib" -lSDL.dll -lfreetype -lfontconfig -lfreetype -lopengl32 -lgdi32 -lX11 -lXinerama -lm -ljpeg -lpng16 -lwinmm