\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename open-cobol.info
@settitle OpenCOBOL Manual
@footnotestyle end
@setchapternewpage odd
@c %**end of header

@include version.texi

@ifinfo
@dircategory COBOL
@direntry
* OpenCOBOL: (open-cobol).      A COBOL compiler
@end direntry

This file documents OpenCOBOL, a COBOL compiler

Copyright @copyright{} 2002-2008 Keisuke Nishida
Copyright @copyright{} 2007-2008 Roger While

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end ifinfo

@titlepage
@title OpenCOBOL Manual
@subtitle for OpenCOBOL @value{VERSION}
@author Keisuke Nishida / Roger While

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
Updated for OpenCOBOL @value{VERSION} @*
@value{UPDATED} @*

Copyright @copyright{} 2002-2008 Keisuke Nishida
Copyright @copyright{} 2007-2008 Roger While

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage

@contents

@node Top, Getting Started, (dir), (dir)
@top OpenCOBOL Manual

OpenCOBOL is an open-source COBOL compiler, which translates COBOL
programs to C code and compiles it using GCC.

This manual corresponds to OpenCOBOL @value{VERSION}.

@menu
* Getting Started::             Introduction to OpenCOBOL
* Compile::                     Compiling COBOL programs
* Customize::                   Customizing the compiler
* Optimize::                    Optimizing your program
* Debug::                       Debugging your program

@detailmenu
 --- The Detailed Node Listing ---

Getting Started

* Hello World!::                Hello World!

Compile

* Compiler Options::            Compiler options
* Multiple Sources::            Compiling multiple source files
* C Interface::                 Dealing with C files

Compiler Options

* Built Target::                Built Target
* Source Format::               Source Format
* Warning Options::             Warning Options

Multiple Sources

* Static Linking::              Compiling into a single executable
* Dynamic Linking::             A main program and separate modules
* Building Library::            Building a shared library
* Using Library::               Using external libraries

C Interface

* Main C Program::              Writing Main Program in C
* Static C to COBOL::           
* Dynamic C to COBOL::          
* Static COBOL to C::           
* Dynamic COBOL to C::          

Customize

* Customizing Compiler::        Customizing Compiler
* Customizing Library::         Customizing Library

Optimize

* Optimize Options::            How to enable optimization
* Optimize Call::               Call subroutines efficiently
* Optimize Binary::             Use efficient binary representation

Debug

* Debug Options::               Debug options

@end detailmenu
@end menu

@node Getting Started, Compile, Top, Top
@chapter Getting Started

@menu
* Hello World!::                Hello World!
@end menu

@node Hello World!,  , Getting Started, Getting Started
@section Hello World!

This is a sample program that displays ``Hello World'':

@example
---- hello.cob -------------------------
      * Sample COBOL program
       IDENTIFICATION DIVISION.
       PROGRAM-ID. hello.
       PROCEDURE DIVISION.
       DISPLAY "Hello World!".
       STOP RUN.
----------------------------------------
@end example

The compiler is @code{cobc}, which is executed as follows:

@example
$ cobc -x hello.cob
$ ./hello
Hello World!
@end example

The executable file name (i.e., @file{hello} in this case) is
determined by removing the extension from the source file name.

You can specify the executable file name by specifying the compiler
option @code{-o} as follows:

@example
$ cobc -x -o hello-world hello.cob 
$ ./hello-world
Hello World!
@end example

@node Compile, Customize, Getting Started, Top
@chapter Compile

This chapter describes how to compile COBOL programs using OpenCOBOL.

@menu
* Compiler Options::            Compiler options
* Multiple Sources::            Compiling multiple source files
* C Interface::                 Dealing with C files
@end menu

@node Compiler Options, Multiple Sources, Compile, Compile
@section Compiler Options

The compiler @code{cobc} accepts the options described in this section.

@menu
* Built Target::                Built Target
* Source Format::               Source Format
* Warning Options::             Warning Options
@end menu

@node Built Target, Source Format, Compiler Options, Compiler Options
@subsection Built Target

The following options specify the target type produced by the
compiler:

@table @code
@item -E
Preprocess only.  Compiler directives are executed.  Comment lines are
removed.  COPY statements are expanded.  The output goes to the
standard-out.

@item -C
Translation only.  COBOL source files are translated into C files.
The output is saved in file @file{*.c}.

@item -S
Compile only.  Translated C files are compiled by cc.
The output is saved in file @file{*.s}.

@item -c
Compile and assemble.  This is equivalent to @code{cc -c}.
The output is saved in file @file{*.o}.

@item -m
Compile, assemble, and build a dynamically loadable module (i.e.,
a shared library).  The output is saved in file @file{*.so}.
@footnote{The extension varies depending on your host.}.

@item -x
Include the main function in the output.

This option takes effect at the translation stage.
If you give this option with @code{-C}, you will see the main
function at the end of the generated C file.

@end table

Without any options above, the compiler tries to build a
dynamically loadable module.

@node Source Format, Warning Options, Built Target, Compiler Options
@subsection Source Format

OpenCOBOL supports both fixed and free source format.

The default format is the fixed format.  This can be explicitly
overwritten by one of the following options:

@table @code
@item -free
Free format.

@item -fixed
Fixed format.
@end table

@node Warning Options,  , Source Format, Compiler Options
@subsection Warning Options

@table @code
@item -Wall
Enable all warnings

@item -Wcolumn-overflow
Warn any text after column 72

@item -Wend-evaluate
Warn lacks of END-EVALUATE

@item -Wend-if
Warn lacks of END-IF

@item -Wparentheses
Warn lacks of parentheses around AND within OR
@end table

@node Multiple Sources, C Interface, Compiler Options, Compile
@section Multiple Sources

A program often consists of multiple source files.  This section
describes how to compile multiple source files.

This section also describes how to build a shared library that can
be used by any COBOL programs and how to use external libraries from
COBOL programs.

@menu
* Static Linking::              Compiling into a single executable
* Dynamic Linking::             A main program and separate modules
* Building Library::            Building a shared library
* Using Library::               Using external libraries
@end menu

@node Static Linking, Dynamic Linking, Multiple Sources, Multiple Sources
@subsection Static Linking

The easiest way of combining multiple files is to compile them into a
single executable.

One way is to specify all files on the command line:

@example
$ cobc -x -o prog main.cob subr1.cob subr2.cob
@end example

Another way is to compile each file with the option @code{-c},
and link them at the end.
The top-level program must be compiled with the option @code{-x}:

@example
$ cobc -c subr1.cob
$ cobc -c subr2.cob
$ cobc -c -x main.cob
$ cobc -x -o prog main.o subr1.o subr2.o
@end example

You can link C routines as well using either method:

Method 1:
@example
$ cobc -o prog main.cob subrs.c
@end example

Method 2:
@example
$ cc -c subrs.c
$ cobc -c -x main.cob
$ cobc -x -o prog main.o subrs.o
@end example

Any number of functions can be contained in a single C file.

The linked programs will be called dynamically; that is, the symbol
will be resolved at run time.  For example, the following COBOL
statement

@example
CALL "subr" USING X.
@end example

will be converted into an equivalent C code like this:

@example
int (*func)() = cob_resolve("subr");
if (func != NULL)
  func (X);
@end example

With the compiler options @code{-fstatic-call}, more efficient code
will be generated like this:

@example
subr(X);
@end example

Note that this option is effective only when the called program name
is a literal (like @code{CALL "subr".}).  With a data name (like
@code{CALL SUBR.}), the program is still called dynamically.

@node Dynamic Linking, Building Library, Static Linking, Multiple Sources
@subsection Dynamic Linking

There are two methods to achieve this.
Method 1 (Using driver program).
Compile all programs with the option @code{-m}:
@example
$ cobc -m main.cob subr.cob
@end example
This creates shared object files @file{main.so subr.so}
@footnote{The extension varies depending on your host.}.

Before running the main program, install the module files in your
library directory:
@example
$ cp subr.so /your/cobol/lib
@end example
Set the environment variable @code{COB_LIBRARY_PATH}
to your library directory, and run the main program:
@example
$ export COB_LIBRARY_PATH=/your/cobol/lib
@end example
Note: You may set the variable to directly point to the
directory where you compiled the sources.

Now execute your program:
@example
$ cobcrun main
@end example

Method 2.
The main program and subprograms can be compiled separately.

The main program is compiled as usual:
@example
$ cobc -x -o main main.cob
@end example

Subprograms are compiled with the option @code{-m}:
@example
$ cobc -m subr.cob
@end example
This creates a module file @file{subr.so}
@footnote{The extension varies depending on your host.}.

Before running the main program, install the module files in your
library directory:
@example
$ cp subr.so /your/cobol/lib
@end example

Now, set the environment variable @code{COB_LIBRARY_PATH}
to your library directory, and run the main program:
@example
$ export COB_LIBRARY_PATH=/your/cobol/lib
$ ./main
@end example

@node Building Library, Using Library, Dynamic Linking, Multiple Sources
@subsection Building Library

You can build a shared library by combining multiple COBOL programs
and even C routines:

@example
$ cobc -c subr1.cob
$ cobc -c subr2.cob
$ cc -c subr3.c
$ cc -shared -o libsubrs.so subr1.o subr2.o subr3.o
@end example

@node Using Library,  , Building Library, Multiple Sources
@subsection Using Library

You can use a shared library by linking it with your main program.

Before linking the library, install it in your system library directory:
@example
$ cp libsubrs.so /usr/lib
@end example
or install it somewhere else and set @code{LD_LIBRARY_PATH}:
@example
$ cp libsubrs.so /your/cobol/lib
$ export LD_LIBRARY_PATH=/your/cobol/lib
@end example

Then, compile the main program, linking the library as follows:
@example
$ cobc -x main.cob -L/your/cobol/lib -lsubrs
@end example

@node C Interface,  , Multiple Sources, Compile
@section C Interface

This chapter describes how to combine C programs with COBOL programs.

@menu
* Main C Program::              Writing Main Program in C
* Static C to COBOL::           
* Dynamic C to COBOL::          
* Static COBOL to C::           
* Dynamic COBOL to C::          
@end menu

@node Main C Program, Static C to COBOL, C Interface, C Interface
@subsection Writing Main Program in C

Include @file{libcob.h} in your C program.
Call @code{cob_init} before using any COBOL module:

@example
#include <libcob.h>

int
main (int argc, char **argv)
@{
  /* initialize your program */
  ...

  /* initialize the COBOL run-time library */
  cob_init (argc, argv);

  /* rest of your program */
  ...

  /* Clean up and terminate - This does not return */
  cob_stop_run (return_status);

@}
@end example

You can write @code{cobc_init(0, NULL);} if you do not want to pass
command line arguments to COBOL.

You can compile your C program as follows:

@example
cc -c `cob-config --cflags` main.c
@end example

The compiled object must be linked with libcob as follows:

@example
cc -o main main.o `cob-config --libs`
@end example

@node Static C to COBOL, Dynamic C to COBOL, Main C Program, C Interface
@subsection Static linking with COBOL programs

Let's call the following COBOL module from a C program:

@example
---- say.cob ---------------------------
       IDENTIFICATION DIVISION.
       PROGRAM-ID. say.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       LINKAGE SECTION.
       01 HELLO PIC X(6).
       01 WORLD PIC X(6).
       PROCEDURE DIVISION USING HELLO WORLD.
       DISPLAY HELLO WORLD.
       EXIT PROGRAM.
----------------------------------------
@end example

This program accepts two arguments, displays them, and exit.

From the viewpoint of C, this is equivalent to a function having the
following prototype:

@example
extern int say(char *hello, char *world);
@end example

So, your main program will look like as follows:

@example
---- hello.c ---------------------------
#include <libcob.h>

extern int say(char *hello, char *world);

int
main()
@{
  int ret;
  char hello[7] = "Hello ";
  char world[7] = "World!";

  cob_init(0, NULL);

  ret = say(hello, world);

  return ret;
@}
----------------------------------------
@end example

Compile these programs as follows:

@example
$ cc -c `cob-config --cflags` hello.c
$ cobc -c -static say.cob
$ cobc -x -o hello hello.o say.o
$ ./hello
Hello World!
@end example

@node Dynamic C to COBOL, Static COBOL to C, Static C to COBOL, C Interface
@subsection Dynamic linking with COBOL programs

You can find a COBOL module having a specific PROGRAM-ID by using a C
function @code{cob_resolve}, which takes the module name as a string
and returns a pointer to the module function.

@code{cob_resolve} returns NULL if there is no module.  In this case,
the function @code{cob_resolve_error} returns the error message.

Let's see an example:

@example
---- hello-dynamic.c -------------------
#include <libcob.h>

static int (*say)(char *hello, char *world);

int
main()
@{
  int ret;
  char hello[7] = "Hello ";
  char world[7] = "World!";

  cob_init(0, NULL);

  /* find the module with PROGRAM-ID "say". */
  say = cob_resolve("say");

  /* if there is no such module, show error and exit */
  if (say == NULL) @{
    fprintf(stderr, "%s\n", cob_resolve_error ());
    exit(1);
  @}

  /* call the module found and exit with the return code */
  ret = say(hello, world);

  return ret;
@}
----------------------------------------
@end example

Compile these programs as follows:

@example
$ cc -c `cob-config --cflags` hello-dynamic.c 
$ cobc -x -o hello hello-dynamic.o
$ cobc -m say.cob
$ export COB_LIBRARY_PATH=.
$ ./hello
Hello World!
@end example

@node Static COBOL to C, Dynamic COBOL to C, Dynamic C to COBOL, C Interface
@subsection Static linking with C programs

Let's call the following C function from COBOL:

@example
---- say.c -----------------------------
int
say(char *hello, char *world)
@{
  int i;
  for (i = 0; i < 6; i++)
    putchar(hello[i]);
  for (i = 0; i < 6; i++)
    putchar(world[i]);
  putchar('\n');
  return 0;
@}
----------------------------------------
@end example

This program is equivalent to the foregoing @file{say.cob}.

Note that, unlike C, the arguments passed from COBOL programs are not
terminated by the null character (i.e., @code{\0}).

You can call this function in the same way you call COBOL programs:

@example
---- hello.cob -------------------------
       IDENTIFICATION DIVISION.
       PROGRAM-ID. hello.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 HELLO PIC X(6) VALUE "Hello ".
       01 WORLD PIC X(6) VALUE "World!".
       PROCEDURE DIVISION.
       CALL "say" USING HELLO WORLD.
       STOP RUN.
----------------------------------------
@end example

Compile these programs as follows:

@example
$ cc -c say.c
$ cobc -c -static -x hello.cob
$ cobc -x -o hello hello.o say.o
$ ./hello
Hello World!
@end example

@node Dynamic COBOL to C,  , Static COBOL to C, C Interface
@subsection Dynamic linking with C programs

You can create a dynamic-linking module from a C program by passing an
option @code{-shared} to the C compiler:

@example
$ cc -shared -o say.so say.c
$ cobc -x hello.cob
$ export COB_LIBRARY_PATH=.
$ ./hello
Hello World!
@end example

@node Customize, Optimize, Compile, Top
@chapter Customize

@menu
* Customizing Compiler::        Customizing Compiler
* Customizing Library::         Customizing Library
@end menu

@node Customizing Compiler, Customizing Library, Customize, Customize
@section Customizing Compiler

These settings are effective at compile-time.

Environment variables (default value):

@table @code
@item COB_CC
C compiler ("gcc")
@item COB_CFLAGS
Flags passed to the C compiler ("-I$(PREFIX)/include")
@item COB_LDFLAGS
Flags passed to the C compiler ("")
@item COB_LIBS
Standard libraries linked with the program ("-L$(PREFIX)/lib -lcob")
@item COB_LDADD
Additional libraries linked with the program ("")
@end table

@node Customizing Library,  , Customizing Compiler, Customize
@section Customizing Library

These settings are effective at run-time.

Environment variables (default value):

@table @code
@item COB_LIBRARY_PATH
Dynamic-linking module path (".:$(PREFIX)/lib/open-cobol")
@item COB_DYNAMIC_RELOADING
Set to ``yes'' if modules must be reloaded when they are replaced (``no'')
@end table

@node Optimize, Debug, Customize, Top
@chapter Optimize

@menu
* Optimize Options::            How to enable optimization
* Optimize Call::               Call subroutines efficiently
* Optimize Binary::             Use efficient binary representation
@end menu

@node Optimize Options, Optimize Call, Optimize, Optimize
@section Optimize Options

There are three compiler options for optimization: @code{-O}, @code{-Os}
and @code{-O2}.  These options enable optimization at both translation
(from COBOL to C) and compilation (C to assembly) levels.

Currently, there is no difference between these optimization options at
the translation level.

The option @code{-O}, @code{-Os} or @code{-O2} is passed to the
C compiler as it is and used for C level optimization.

@node Optimize Call, Optimize Binary, Optimize Options, Optimize
@section Optimize Call

When a CALL statement is executed, the called program is linked at run
time.  By specifying the compiler option @code{-fstatic-call}, you can
statically link the program at compile time and call it efficiently.
(@pxref{Static Linking})

@node Optimize Binary,  , Optimize Call, Optimize
@section Optimize Binary

By default, data items of usage binary or comp are stored in the
big-endian form.  On those machines whose native byte order is
little-endian, this is not quite efficient.

If you prefer, you can store binary items in the native form of your
machine.  Set the config option @code{binary-byteorder} to
@code{native} in your config file (@pxref{Customize}).

In addition, setting the option @code{binary-size} to @code{2-4-8} or
@code{1-2-4-8} is more efficient than others.

@node Debug,  , Optimize, Top
@chapter Debug

@menu
* Debug Options::               Debug options
@end menu

@node Debug Options,  , Debug, Debug
@section Debug Options

The compiler option @code{-debug} can be used during the development
of your programs.  It enables all run-time error checking, such as
subscript boundary checks and numeric data checks, and displays
run-time errors with source locations.

The compiler option @code{-g} includes line directives in the output.
This helps debugging your COBOL programs using GDB, but this feature
is not complete and not very useful yet.

@bye

@c Local Variables:
@c mode:outline-minor
@c outline-regexp:"@\\(ch\\|sec\\|subs\\)"
@c End:
