Journey to the Centerof your 4GL application

Eric Vercelletto

eric@begooden-it.com

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 steppingforward

Agenda

• Questions about huge old 4gl applications and what to do with them

• Yes, having a good application documentation isimportant 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

Our 4GL applications fulfill company’s requirements

• They are tailored to the company’sfunctionality needs

• They have been running for tens of years

• They are bug free

• Productivity and user adoption is great

• But ….

4

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

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

Panic mode!This had to happen one day!

• The application historical designer will retire within1 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

Is this your 4gl application documentation?

8

Or is it more identified by that?

9

Time to stop and thinkWhere 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

Time to stop and thinkHow 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 comprehensivedocumentation is necessary if we want to takea correctly grounded decision!

11

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

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

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

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 rolein 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

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

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

First run result

18

Tree view: fold or unfold objects

Main menu

Search box

Drill down f_update_lot function

19

Function flowchart

Link to source code

Call graph

Browse the source codein read-only mode

20

Detail on a function

21

Inbound parameters

Instructions, blocks

Call Graph of the function

22

Click on function and navigate to its definition

Caller graph

23

See where tables are used

24

Table « divers »

In function « maj_technum »

used for SELECT, INSERT, UPDATE

What about the forms ?

25

Click on OPEN FORM

cAnd visualizethe 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

Let’s go further thanOut of the Box

• All of the previous has been obtained with no alteration

• If you understood that FAA is really the tool youneed, put a bit of positive energy on in-source literature

• In-source litterature is based on 4gl comments + FAA tags

26

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

First step: document the module

• Use the \file and \brief tags, then describe what thismodule 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

Result of \file \brief, \author, \bug

29

\brief tag

\author tag

\bug tag: build a documented bug list

Documenting the module

30

Module \brief tag

List of module’s functionwith brief

Detailed description (lines after 1st brief line)

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 detaileddescription

• 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

Detailed view of function doc

32

\param: inbound parameters

\return: outbound parameters

Function’s flowchart

Caller graph

Documenting the variables

• Some variables declaration may needexplanations. Here is how to do:

33

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

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 evencreate new pages ( \page pagename )and hyperlink to them (\refpagename)

35

\mainpage

\section

\subsection

Define new page

link to new page

Main page rendering

36

\section

\subsection

New page defined

Link to new page

The management insistson 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

Write 239 pdf pages in seconds

38

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 someremote location as his new activity ?

Questions ?

40

41

Journey to the Centerof your 4GL application

Eric Vercelletto

eric@begooden-it.com