FGLDOC(1)							     FGLDOC(1)

NAME
       fgldoc - A documenter for Informix-4GL programs

SYNOPSIS
       fgldoc [-v] [-s] [-x modname[,modname...]]
	      [-apfro] progname

DESCRIPTION
       fgldoc reads a list of 4GL module names comprising the program progname
       from the program design database or standard input (one name per line,
       without the .4gl extension), parses the modules, and generates one or
       more summary listings on standard output.  Verbosity of fgldoc's opera-
       tion and the amount of summary information generated on output are con-
       trolled by command-line options.

OPTIONS
       -v  Verbose mode.  The program's progress is reported to standard error
	   output.

       -s  Use standard input to read module names.  This option is perma-
	   nently set if the program has been compiled without database sup-
	   port routines.

       -x  This option should be followed by a comma-separated list of addi-
	   tional modules to be parsed.	 The modules are assumed to be in the
	   current directory.  There shouldn't be any whitespace in the list.
	   The intended use of -x is to specify modules containing external
	   function templates; see the NOTES section for discussion.

       -a  Print all summaries (program, function, report, form).  This is the
	   default.

       -p  Print the program summary, which reports the following:

	   -  The number of modules, name and line count for each module, and
	      total LOC for all modules.

	   -  The number of functions in the program.

	   -  The number of reports in the program.

	   -  The number of forms that the program activates, along with their
	      names.

       -f  Print the function summary, which consists of two listings:

	   Function hierarchy.	Hierarchical list of functions, starting from
	   main.  For each function, the list of functions (reports, forms)
	   which the function calls is printed.	 If a called function is non-
	   terminal (i.e., it makes one or more calls itself), the process is
	   recursively applied to that function.

	   Functions by name.  Alphabetical list of functions (exception: main
	   is always displayed first, regardless of its actual lexicographic
	   position).  For each function, the following information is pro-
	   vided:

	   -  The name of the module where it is defined.

	   -  The list of functions (reports, forms) which it calls.

	   -  The list of functions/reports which call the function.

	   If a function is orphaned (i.e., defined but not called from any-
	   where in the progam), a hash sign ('#') will be displayed before
	   its name, in the first column of the line, making it easy to find
	   all orphaned functions with something like

	       fgldoc -f progname | grep '^#'

       -r  Print the report summary, which is similar in form to the second
	   part of the function summary.

       -o  Print the form summary.  For each form, print its name and the list
	   of functions which activate it.

       Options -p, -f, -r and -o can be specified in any combination to pro-
       duce just the desired summaries.	 The -a option (which is, strictly
       speaking, redundant) is equivalent to -pfro.  The order of options does
       not affect the order in which the summaries are output.

NOTES
       When opening the program design database, fgldoc will first try to use
       the value of the environment variable PROGRAM_DESIGN_DBS as the
       database name.  If that variable is unset, the standard name syspgm4gl
       will be used.

       Connection to the program design database is made implicitly, for com-
       patibility with the older versions of ESQL/C libraries.	There is no
       way to connect using a different username and password.

       If a character variable is used to specify the form file in OPEN FORM
       and OPEN WINDOW... WITH FORM statements, fgldoc will print the variable
       identifier in all uppercase to distinguish it from file names given as
       literals.

       By design, functions for which the corresponding definition is not
       found in the source are not reported anywhere (otherwise the parser
       could not have been as simple as it is).	 If you want to track foreign
       functions (e.g., in external libraries for compiled 4GL, or those in a
       custom p-code runner), create one or more modules with dummy defini-
       tions and list their names as an argument to the -x option.  For exam-
       ple, if an external function foo() is used in the program bar, you
       could create the file .extern.4gl containing the lines

	   FUNCTION foo()
	   END FUNCTION

       and invoke fgldoc as follows:

	   fgldoc -x .extern bar

AUTHOR
       Ivan Nejgebauer <ian@uns.ns.ac.yu>