This document discusses documenting large legacy 4GL applications. It introduces the 4GL App Analyzer tool, which can automatically generate documentation like functional flow charts, comments in source code, and more from 4GL source code. The tool outputs documentation in HTML and other formats. Using tags in source code comments allows more detailed documentation of modules, functions, variables, forms and other elements. The documentation provides a centralized resource for understanding an application and planning its future.

1. Journey to the Center
of your 4GL application
Eric Vercelletto
eric@begooden-it.com

2. About the speaker
2
• Informix 4GL passionate and advocate since 1986
• Has tried many solutions about 4GL documentation
since 1986
• Understood the impact of losing an application
Architect
• Prefers doing more and better with smallest effort
than doing less and worse with biggest effort
• Loves understanding where he is before stepping
forward

3. Agenda
• Questions about huge old 4gl applications and
what to do with them
• Yes, having a good application documentation is
important for many different reasons!
• There are not many good solutions available for
x4gl documentation
• Explore the right solution and look to the future
with optimism
3

4. Our 4GL applications
fulfill company’s requirements
• They are tailored to the company’s
functionality needs
• They have been running for tens of years
• They are bug free
• Productivity and user adoption is great
• But ….
4

5. The environment is changing
• Young and mid-age users do not like text-based
• Company’s activity is evolving or changing
• Architectures and infrastructures are changing
• New functionality often require new
developments based on new technologies
5

6. Time is flying
• The application is getting more and more complex
• In-house developers are getting old
• The application architect knows everything about the
application, but
– Developers know only separate parts of it
– New developers do not know 4GL
– Management has no global nor in-depth knowledge of it
6

7. Panic mode!
This had to happen one day!
• The application historical designer will retire within
1 year
• He knows every single piece of the application, but
no one else does
• the application documentation is not usable
• Beautiful 1300 pages Word document, last update in 2003
• No big picture nor flowcharts helping to understand
• Comments in source code not easily accessible and lots of trash
7

8. Is this your 4gl application documentation?
8

9. Or is it more identified by that?
9

10. Time to stop and think
Where should we go?
• Decommission the application and purchase a famous ERP?
– Result is incertain: heavy hidden costs, customer adoption at risk,
no error is possible
• Re-develop in house with a more popular language (java,C+
+, C#,Python,php ...)?
– Risk is mainly on delivery time, app should meet requirements
• Go x4GL ? ( don’t think too much, go Querix Lycia 3 )
– Preserve app investment and re-instanciate into open, flexible
modern technologies. Probably the best solution and best return
on investiment
• Leave as is and pray ?
– How long will this situation be supportable?
10

11. Time to stop and think
How to avoid a mistake?
• Decommission the application and purchase a famous ERP?
• Re-develop in house with a more popular language ?
• Go x4GL ? ( Aubit, Genero, Querix)
• Leave as is and pray ?
In any case, having a clear and comprehensive
documentation is necessary if we want to take
a correctly grounded decision!
11

12. How to build a good documentation
if you are not happy with what you have?
• Pay for a company to build a 3000 pages documentation
– May take long to very long time
– Budget easily reaches 100’s of K$/K€ ….
– Will be deprecated as soon as it is delivered
– Not a productivity tool for dev team if dev continues with 4gl technology
• Use awk, grep and find:
– Can give good results but remains tedious and limited
• Develop a 4GL documentation tool:
– Tempting, but takes time and energy
• Use a documentation generator tool:
– Great with other languages, but nothing specific for 4GL
12

13. ou have been looking for it?
4GL App Analyzer does it!
• Querix 4GL App Analyzer© is a documentation generator tailored for applications
developped in x4GL language.
• It builds a structured documentation by parsing your source code
– Any flavor of 4GL
– Describes functions, reports, tables usage, variables, forms and properties
– Automatically designs functional flow charts
– Includes functions call tree (called and calling)
– Uses your own comments in source code if requested
– HTML generated pages allow easy and fast navigation thru the documentation source code,
publishable on any webserver
– Includes a smart search tool for focused research
– Multilingual tool: can generate doc in many languages
• It is a great centralized and collaborative tool for a development team
– Published on any internal or public website, read-only access
• In addition to html, many output forms possible, like .pdf, .rtf, man page
13

14. Main advantages
• The source code is the epicenter of your application
– the application structure doc is generated automatically: spend no time on it
– You decide what will appear in the documentation
– You can take benefit of comments already written in the source code
– Any code or comments alteration will automatically be reflected in the doc
– No need to duplicate between source and documentation, the doc is
generated from the source
– Do not waste time on layout, work on useful information
• Navigate between structural documentation and source code
– Access to the code in read-only mode
– Hyperlinks on modules, functions, tables, flowcharts etc…
– Included search tool, no more find … -exec grep «xxx » {}; and v
14

15. Main advantages
• The documentation provides all the relevant information for functional
people as well as for technical people.
• Work the way you need according to situations:
– Top Down: drill down from top application level to detailed description to
gain understanding
– Down Top: choose an object(table, variable, function) and evaluate its role
in the application
– Search mode: pin to a document object and understand the impact of
modifying it.
• Consider application documentation in a radically different way:
– not a painful timewaster task suddenly demanded by management
– Have fun building a great application documentation (yes, I know,
incredible, but true!)
15

16. H w does it work?
• You need FAA installed on linux, soon on windows
• Locate your 4gl, esql/c, C and Java source code and the forms
• Configure your project documentation file
– Where is the source code, codepage, generate html, txt, man page, doc
language and many other topics
– Use the configuration wizard or the configuration file directly
• Run fglaarun.sh and do something else
– According to application size, can take a few hours for 1000000+ lines
applications, but can also take minutes.
– The long part is the flowcharts generation, you can decide to cut it where not
necessary
16

17. configuration: important parameters
• INPUT_DIRECTORY: directory(ies) name where your source code is
• OUTPUT_DIRECTORY: directory where the documentation is written
• OPTIMIZE_OUTPUT_FGL YES: you parse mainly 4GL code
• SOURCE_BROWSER YES: you want to browse source code and doc
• GENERATE_HTML YES: you want to generate doc in HTML
• CALL_GRAPH YES: you want to see which functions each function calls
• CALLER_GRAPH YES: you want to which by which functions each function is called
• GENERATE_TREEVIEW YES: you want to have a documentation in tree view
• OUTPUT LANGUAGE language: you can generate the doc in your favorite language
(English, Spanish, French, Portuguese, German etc…)
Eventually you may want to
• GENERATE_RTF YES: you want to generate doc in RTF
• GENERATE_LATEXT: you want to generate PDF (needs some further steps)
17

18. First run result
18
Tree view: fold or
unfold objects
Main menu
Search box

19. Drill down f_update_lot function
19
Function flowchart
Link to source code
Call graph

20. Browse the source code
in read-only mode
20

21. Detail on a function
21
Inbound parameters
Instructions, blocks

22. Call Graph of the function
22
Click on function and navigate to its definition

23. Caller graph
23

24. See where tables are used
24
Table « divers »
In function « maj_technum »
used for SELECT, INSERT, UPDATE

25. What about the forms ?
25
Click on OPEN FORM
cAnd visualize
the form
• Forms are critical components of a 4GL
application, we need them in the doc
• More details will come in the next version,
including search capabilities

26. Let’s go further than
Out of the Box
• All of the previous has been obtained with no
alteration
• If you understood that FAA is really the tool you
need, put a bit of positive energy on in-source
literature
• In-source litterature is based on 4gl comments +
FAA tags
26

27. Before we start
• Your documentation is based on tags and comments blocks
– A comments line starts with ## or --
– A comments block stops at the next blank /empty line
– A comments block can be defined between { and }
– A tag is always put on a commented line and starts with or @
• Any comments block located just above an object declaration is by default
part of the documentation (caution, can give ugly results if comments are
used for disabled code)
– Unless you explicitly document those objects with tags
• Modules, functions, variables, records and forms can be documented
• A markdown syntax can be used to produce a high level layout quality,
including images, new pages, hyperlinks and more
27

28. First step: document the module
• Use the file and brief tags, then describe what this
module is about, like this
• brief is used to show the summary, the comments end
at the next blank line
• Generally the right place to list author, date, version
28
brief tag

29. Result of file brief, author, bug
29
brief tag
author tag
bug tag: build a
documented bug list

30. Documenting the module
30
Module brief tag
List of module’s function
with brief
Detailed description
(lines after 1st brief line)

31. Documenting the functions
• Put comments just above the function declaration OR use the fn tag
• Use brief tag for brief description, following comments are the detailed
description
• Describe inbound parameters with the param tag
• Describe the outbound parameters with the return tag
31
brief tag for function
param: inbound parameters
return: outbound parameters

32. Detailed view of function doc
32
param: inbound parameters
return: outbound parameters
Function’s flowchart
Caller graph

33. Documenting the variables
• Some variables declaration may need
explanations. Here is how to do:
33

34. You are lost?
Use the Search Box
34
Type an object name or first characters
Here is what search engine found
Click on name and get there

35. You like writing ?
Express yourself with litterature-only
• You may need to include non code-related documentation. Create a
dedicated .4gl inactive module and use the mainpage tag. You can even
create new pages ( page pagename )and hyperlink to them (ref
pagename)
35
mainpage
section
subsection
Define new page
link to new page

36. Main page rendering
36
section
subsection
New page defined
Link to new page

37. The management insists
on having paper documentation?
• Generate a pdf document in 2 more steps
– Ensure you set the flag GENERATE_LATEX YES
– After documentation generation:
cd latex then run make
– Enjoy the pdf document
and print only it if requested
37

38. Write 239 pdf pages in seconds
38

39. Conclusion
39
With 4GL App Analyzer you will:
• Obtain a professional, complete and useful application documentation with low to
moderate effort
• Get an inner vision of your application as you never had before
• Avoid wasting 100’s of K$ for a document natively deprecated
• Enhance your team’s productivity by sharing always up to date information
Do you really want to wait till the application architect has gone fishing in some
remote location as his new activity ?

40. Questions ?
40

41. 41

42. Journey to the Center
of your 4GL application
Eric Vercelletto
eric@begooden-it.com