GuiCOBOL …behind the scene

There is an idea behind guicobol. use the cobol itself to manage an advanced gui. No superstructures just cobol and advanced widgets. The object orientation 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 GuiCOBOL preprocessor does the “dirty” work …behind the scenes an instruction

move “yellow” to “color” of self.

becomes

call static “AG_SetStyle” using by value agar-Form by content “color” by content ‘#FFFF00’ end-call

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.

N.B. Take care 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

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 great and strong WYSIWYG editor) and the development environment itself is extremely evolved and enhanced. With 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 instead always a conventional cobol source.

This means, for example, that the module when it is generated has a callback 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 field declaration all fields used for the objects will be automatically declared inside the individual working-storage section for all script.

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.

Widgets 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

WINDOW

BOX

BUTTON

COMBOBOX

CHECKBOX

LABEL

FIXED

MENU

NUMERIC

PANE

PROGRESSIVE BAR

RADIO

SCROLLBAR

SCROLLVIEW

SLIDER

TEXTBOX

HORIZONTAL LINE

VERTICAL LINE and now ..a complete sample

list of objects

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

Becomes...

000001  IDENTIFICATION DIVISION.
000002  PROGRAM-ID.    demo2.
000003  ENVIRONMENT DIVISION.
000004  DATA DIVISION.
000005  WORKING-STORAGE SECTION.
000006           copy "global".
000007  01 abox                 usage pointer external.
000008  01 alabel               usage pointer external.
000009  PROCEDURE DIVISION.
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
000030*
000031* this note will be added to the gui source
000032*
            *          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"
000081*
000082**  link the event to the required procedure
000083*
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. 







Some .bat available are:

  • 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