User Manual

This manual documents the administration and use of the TinyCOBOL compiler, version 0.61.

Published by the Free Software Foundation

59 Temple Place, Suite 330

Boston, MA 0211-1307, USA

Copyright © 2004 Free Software Foundation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documenation License, Version 1.2 or any later version published the the Free Software Foundatation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.

About This Manual

What is TinyCOBOL?

TinyCOBOL is an Open Source COBOL compiler released under the GNU license. The long-term goal of the developers it to create a COBOL compiler which is reasonably close to the COBOL 85 Standard with common extensions.

Who Should Use This Manual

This manual is intended for TinyCOBOL administrators and programmers. This manual assumes that the administrator or programmer does not have a strong knowledge Linux or FreeBSD, so some sections overdescribe basic procedures.

Platforms Discussed in This Manual

This manual only covers the Linux implementation, and the FreeBSD port of TinyCOBOL. TinyCOBOL has also been ported to Windows using Open Systems emulators. It has also been ported to BeOS. The Windows and BeOS ports are not covered in this manual.

Writing Conventions

System commands are written in mono spaced, sans serif, bold font. Object names are written in italics. So htcobol is the name of an executable program, and htcobol is the command that executes the htcobol program.

TinyCOBOL Contributors

Project Creator

Pragana, Rildo

Source Code

Bizzarri, Paolo - Several RTS patches

Bufford, Sean - Patch to fix indexed file index file I/O offset calculation

Cameron, Andrew - RTS file I/O, initial DB 1.85.4 for Win32 ports, lock server and client code

Colbert, Glen - Initial code for command line front end and for regression test suite

Connolly, Stephen

Cox, Alan - Initial code to generate GNU assembler

Essex, David - Preprocessor, math grammar generation, RTS

Giroud, Bernard - Intrinsic functions, finished CALL statement, many little clauses for Cobol 85, RTS fixes, test suite

Hollard, Gerard - Qualification problem fix

Lucari, Alain - Fixes for write with advancing

Mobach, Fred - Resident COBOL standard expert

Morcombe, Jim - External file MF compatibility option

Nishida, Keisuke - Grammar and miscellaneous fixes

Noeth, Jim - Move routines in RTS (Run Time System)

Pragana, Rildo - Scanner and parser code, RTS

Pegueroles, Ferran - RTS curses functionality for Screen I/O, DISPLAY and ACCEPT, majority of intrinsic functions

Smith, Jeff - RTS math

Stakaowski, Mariusz - INSPECT TALLYING

Tweedy, Laura - Initial lex code for preprocessor and cobf2f utility

Binary Packages

Billsbrough, David - Sample spec file for RPM version 4 format

Douthitt, David - libc6 RPM packages for releases

Essex, David - libc5 RPM packages, Win32 packages (MinGW, Cygwin)

Manzo, Luciano D. C. - Initial spec file to create RPMs

Pegueroles, Ferran - Debian packages

Takahashi, Keiichi - libc6 RPM packages

O/S Ports

Cameron, Andrew - Win32 Cygwin port

Cox, Alan - Initial Linux port

Essex, David - Win32 MinGW port

Gardella, Patrick - FreeBSD port and configuration

Verran, Matt - BeOS port and configuration

Documentation

Ball, Scott – TinyCOBOL User Manual

Giroud, Bernard -- French man files

Martínez, Juan J. - Spanish man files, Spanish version of Introduction to COBOL and TinyCOBOL

Reis, Hudson - Portuguese version of man files, Portuguese version of Introduction to COBOL and TinyCOBOL

Riddell, Jonathan - Introduction to COBOL and TinyCOBOL

Rizzini, Mario Lodi -- Italian version of man files

Teatini, Fabio -- Italian version of Introduction to COBOL and TinyCOBOL

Contents

User Manual	i

About This Manual	i

What is TinyCOBOL?	i

Who Should Use This Manual	i

Platforms Discussed in This Manual	i

Writing Conventions	i

TinyCOBOL Contributors	ii

Project Creator	ii

Source Code	ii

Binary Packages	ii

O/S Ports	iii

Documentation	iii

Introduction	1

GNU Software	1

Distribution License	1

TinyCOBOL language standards	1

How You Can Contribute to the TinyCOBOL Project	1

Where to Get Help	1

Where to Post TinyCOBOL Bugs	2

Note to BSD Users about make	2

Supported Environments	3

Hardware Architecture	3

Operating Systems	3

Runtime environment	4

Environment summary	4

Required libraries	4

Environment variables	4

Default directory structure from a tarball or FreeBSD sysinstall installation	4

Default directory structure from an RPM installation	5

Files	5

External programs	5

Environment details	5

libhtcobol.so, libhtcobol.so.0, libhtcobol.so.0.61.0	5

libc.so	5

libdl.so	5

libm.so	5

libdb.so	5

libncurses.so	5

ld-linux.so	6

TCOB_OPTIONS	6

TCOB_OPTIONS_PATH	6

TCOB_PP_PATH	6

TCOB_LD_LIBRARY_PATH	6

TEMP	6

htcobolrc	6

lockserver	6

Installation	7

Building TinyCOBOL	7

Compiler requirements	7

Installing flex	8

Installing yacc193	8

Berkeley DB	8

Installing gcc	9

Building TinyCOBOL from Source Code	9

Post Installation Tasks	10

Verifying the Compiler Build	11

Installation Using an RPM Binary	11

Uninstalling	11

Compiling	13

Compiler Environment and Options Setup	13

How to Compile—A Quick Introduction	13

Command Line Compiling	13

Shell Script Compiling	14

make File Compiling	14

Command Line Options	14

htcobolrc Options	15

Compile Errors	15

Troubleshooting	15

Running a Program	17

Command Line Execution	17

Script File Execution	17

make Files	17

lockserver	17

Troubleshooting	17

GNU Documentation License	18

Introduction

GNU Software

The TinyCOBOL compiler is licensed under the GPL license and the TinyCOBOL run-time library is licensed under the LGPL license. For more information about these licenses, see the GNU website at http://www.gnu.org

Distribution License

The TinyCOBOL run-time library is distributed under the LGPL, and does not impose license restrictions on compiled binaries.

The Berkeley DB is needed to run TinyCOBOL. Note that only Berkeley DB version 1.85.x and 1.86 are released under the LGPL. More recent releases of Berkeley DB have a more restrictive license requiring you to release your source code with your executables if you distribute your programs. If you use a more recent release of Berkeley DB and you do not want to release your source code, you must purchase a license from Sleepycat Software. See the licensing requirements at http://www.sleepycat.com

TinyCOBOL language standards

ISO IEC 1989:1995: Programming Languages – COBOL.

ISO IEC 1989/AMD1:1992: Programming Languages – COBOL. Amendment 1 – Intrinsic function module.

ANSI X3.23-1985: Programming Languages – COBOL.

ANSI X23a-1998: Programming Languages – COBOL. Amendment 1: Intrinsic function module.

X/Open XPG3: COBOL programming language extensions.

How You Can Contribute to the TinyCOBOL Project

The TinyCOBOL project can use your experience. The workplace for TinyCOBOL is sourceforge. The project can use developers, testers and technical writers. You don't need a lot of experience.

The easiest way to start is by opening the TinyCOBOL home page, http://www.tinycobol.org and then opening the mailing list link. Subscribe to the Tiny-cobol-users mailing list, spend some time looking through the archives to see what we people are doing, and then send note to introduce yourself.

Where to Get Help

The best source for help is the TinyCOBOL mailing list described above. This is a very active user list. Please check this user manual and the TinyCOBOL.org website before submitting questions to the user group. When sending a question to the user group, please give the name and version of your operating system, the TinyCOBOL version number.

Where to Post TinyCOBOL Bugs

Two places are available for posting TinyCOBOL bugs.

The TinyCOBOL bug tracker is available in sourceforge.net at http://sourceforge.net/tracker/?group_id=383&atid=100383

Bugs can also be posted in the TinyCOBOL users mailing list described above. An execution log can often be helpful. On most systems, an execution log can be generated by using the script command as follows:

$ script

$ [run your command or commands]

$ exit

This will generate a log file named typescript.. Attach typescript to your post in the TinyCOBOL users mailing list.

Note to BSD Users about make

BSD make is different from make on Linux and does not work the same. Where this User Manual refers to make, use gmake instead.

Supported Environments

Hardware Architecture

The current version of TinyCOBOL compiler creates GNU assembler and machine code for the Intel IA32 (x86) architecture. No other hardware platforms are supported at this time.

Operating Systems

Ports have been made to the following operating systems. All ports use gcc

• BeOS

• BSD

• Linux

• Win32 using MinGW (Mingw32) native Win32 compiler

• Win32 using Cygwin

Runtime environment

Environment summary

Required libraries

libhtcobol.so – Soft link to TinyCOBOL run-time

libhtcobol.so.0 – Soft link to TinyCOBOL run-time

libhtcobol.so.0.61.0 - TinyCOBOL run-time (version 0.61.0 )

libc.so - GNU C

libdl.so - Dynamic loader

libm.so - GNU C math

libdb.so - Berkeley's DB API (this is sometimes a soft link)

libncurses.so - Curses for screen I/O

ld-linux.so - Linux loader (Linux O/Ses only)

Environment variables

All environment variables are optional.

TCOB_OPTIONS - Resource options file name

TCOB_OPTIONS_PATH - Directory path to the resource options file

TCOB_PP_PATH - Preprocessor directory path

TCOB_LD_LIBRARY_PATH – Directory path to the dynamically loaded libraries

TEMP - Directory path to the temporary files

Default directory structure from a tarball or FreeBSD sysinstall installation

/usr/local/bin/ – Compiler location

/usr/local/lib/ – Runtime libraries location

/usr/local/share/htcobol/ – Preprocessor, resource file

/usr/local/share/htcobol/copybooks/ - Default copybook library

Default directory structure from an RPM installation

/usr/bin/ – Compiler location

/usr/lib/ – Runtime libraries location

/usr/share/htcobol/ – Preprocessor, resource files

/usr/share/htcobol/copybooks/ – Copybook default library

/usr/share/doc/tinycobol-0.61/ – Documentation, readme, release notes

Files

htcobolrc – Default runtime library

External programs

lockserver – A daemon for handling record locking

Environment details

libhtcobol.so, libhtcobol.so.0, libhtcobol.so.0.61.0

The TinyCOBOL run-time libraries.

libhtcobol.so.0.61.0 is the runtime library used by the 0.61.0 version of TC. libhtcobol.so and libhtcobol.so.0 are soft links to libhtcobol.so.0.61.0.

libc.so

The GNU C runtime library.

libdl.so

The dynamic loader library.

The compiler uses the dl program to dynamically load other programs. Parameters from htcobolrc are passed to dl. The parameters are modified under some circumstances.

libm.so

The GNU C math library.

libdb.so

The library for Berkeley DB. Use version 1.85.4 or newer. Version 1.85.4 is recommended.

On some systems, this will be a link to another library because the actual library was given another name. The TinyCOBOL INSTALL file has more information on this and so does the section in this User Manual titled “Berkeley DB.”

Berkeley DB handles indexed files.

libncurses.so

The PDcurses library which is used for screen I/O. Use version 2.4 or newer. A section on screen I/O is included in this manual. PDcurses is available through the TinyCOBOL.org download page.

ld-linux.so

The Linux loader .

TCOB_OPTIONS

The environment variable used to override the name of the resource options file.

If this variable is not defined, the name of the resource option file is htcobolrc.

TCOB_OPTIONS_PATH

The environment Directory path to the resource options file.

If this variable is not defined, the path to the resource options file is

/usr/local/share/htcobol/ for tarball and FreeBSD installations or

/usr/share/htcobol/ for RPM installations.

TCOB_PP_PATH

The path to the preprocessor.

If this variable is not defined, the path to the preprocessor is

/usr/local/share/htcobol/ for tarball and FreeBSD installations or

/usr/share/htcobol/ for RPM installations.

TCOB_LD_LIBRARY_PATH

The path to the dynamically loaded libraries.

If this variable is not defined, the path to the load library is

/usr/local/lib/ for tarball and FreeBSD installations or

/usr/lib/ for RPM installations.

TEMP

The path to the temporary files created by the TC compiler.

If this variable is not defined, the path to the temporary files is [?].

[What temporary files are produced?]

htcobolrc

The file containing the default values for the compiler options. A section on htcobolrc is included in this manual.

lockserver

A daemon which handles record locking services for indexed files. lockserver must be installed and running before TinyCOBOL programs can user record locking on indexed files. A section on the lockserver is included in this manual.

Installation

The TinyCOBOL compiler can be installed by compiling the source code or by using a prepackaged binary installation such as RPM on Redhat Linux.

An RPM binary installation can work for Linux, but only if the RPM is built specifically for the system that TinyCOBOL is being installed onto. An RPM installation can be challenging, if not impractical, because of software version dependencies.

People experienced with software installation on Linux and BSD recommend installing TinyCOBOL by compiling the source code. Compiling is the simpler installation method.

Building TinyCOBOL

Building TinyCOBOL by compiling the source can be a challenging task. The main challenge is putting the Berkeley DB files in the right directories. The TinyCOBOL configure script checks for the Berkeley DB libraries, libdb*.*, in the /usr/local directory. If they are located somewhere else on your system, you will modify, either to the configure script, the location of libdb*.*, or both, as described later in this section.

The configure script will also verify that your system's Berkeley DB is compatible with Berkeley DB version 1.85.4. If your system's Berkeley DB is not compatible, you will must either install a compatible version or reinstall your current version with a version 1.85 compatibility flag. The configure script will also check for a usable Berkeley DB header file. The header file must be in either /usr/include or /usr/include/db*, where * is “1”, “2”, “3”, or “4”.

BSD presents another small challenge. The configure and make scripts are designed to use the dynamic linker, dl, which is in libdl.so. BSD does not have dl or libdl.so. Fortunately, BSD does not need dl, because it uses a different dynamic linker. A few minor modifications are needed in the configure, Makefile, and post installation test scripts to work around this challenge. The modifications are described later in this section.

Compiler requirements

Most of the requirements for compiling TinyCOBOL are included in the installation notes that come with the TinyCOBOL source code package. This section will cover some of the basics, so people who are less experienced with Linux and BSD can do a compiled installation.

You will need:

• The TinyCOBOL v 0.61.0 source code package. The best version can be downloaded from the TinyCOBOL.org homepage. You can use either tinycobol-0.61.tar.gz or
tinycobol-0.61.src.rpm. This manual will only address tinycobol-0.61.tar.gz.

• flex the lexical analyzer must be installed on the target system. Another lexical analyzer can be substituted if you know what you are doing. This manual will only address flex. Verify that flex is installed by executing:

flex --version

• A special version of yacc version 1.9.3, the compiler compiler, must be installed. This is named yacc193 to avoid confusion with other yacc programs. This manual will only address yacc193. Other versions of yacc won't work with TinyCOBOL because they aren't robust enough for COBOL's syntax. bison may also work, but the TinyCOBOL developers found that yacc is more stable. yacc193 should be downloaded from the TinyCOBOL home page because the home page version is the same version used by the TinyCOBOL compiler developers.

• Berkeley DB is needed for reading and writing indexed files. The TinyCOBOL compiler requires the presence of a Berkeley DB has a C header file named db.h or db_185.h. The TinyCOBOL installer will verify that the appropriate header is installed.

• A C language compiler. While a number of C compilers might work, gcc is the default and is recommended. This manual will only address gcc.

• Miscellaneous utilities that should come with your O/S distribution.

• BSD users will need gmake. Where this documentation refers to make, BSD users should substitute gmake. BSD has a make utility, but it is different from the Linux make. BSD make and Linux make do not work the same way and are not compatible.

• The program lockserver is needed by TinyCOBOL programs that use record locking. lockserver is a server that must be started before a TinyCOBOL program can do record locking. Your system probably does not have lockserver installed on it. If you know your system will never use record locking, lockserver installation is not necessary. lockserver v 1.0 does not seem to work with FreeBSD. Installing lockserver on FreeBSD may make the compiler unusable.

Installing flex

If flex isn't already installed, locate and install an appropriate flex for your system. The installation of flex is outside of the scope of this user manual.

Installing yacc193

yacc193 is usually easy to install.

After downloading yacc-1.9.3-1.tar.gz from the TinyCOBOL.org Downloads page, from a command line cd into its directory and execute:

gunzip yacc-1.9.3-1.tar.gz

tar -xvf yacc-1.9.3-1.tar

This will unpack and unarchive the TinyCOBOL yacc193 source files and build files.

cd into the yacc-1.9.3 directory.

Read the installation instructions in the INSTALL.txt file, then read the following before installing.

You must have write permission to the system executables directory to install. If your user id doesn't have write permissions, su to root to install.

make install will put the yacc193 man files into directory /usr/man/man1. Verify that your system has a /usr/man/man1 directory.

If your system does not have have directory /usr/man/man1, find your system's man1 directory. It will be full of files with “.gz” extensions and you will see man2 through man9 directories beside man1 in its parent directory. Then edit the yacc193 Makefile, replacing /usr/man/man1 with your system's man1 directory.

make install will, among other things, put the yacc193 documentation files into
/usr/doc/yacc-1.9.3-1 by default. Verify that your system has a /usr/doc directory.

If your system does not have directory /usr/doc, either create it or modify the yacc193 Makefile replacing /usr/doc with your system's correct document directory.

Run make from the yacc-1.9.3 directory to build the object code. If using BSD, remember to use gmake instead of make.

Run make install from the yacc-1.9.3 directory to link the object code and install yacc193 and its documentation.

make install will put program yacc193 into directory /usr/local/bin. Verify that
/usr/local/bin is in your PATH environment variable. If it isn't, add /usr/local/bin to your PATH variable.

Berkeley DB

TinyCOBOL uses Berkeley DB to handle indexed files. Berkeley DB must be installed on your system before installing TinyCOBOL. Either Berkeley DB versions 1.85.4 or 1.86 must be installed, or version 2.1 or newer built with version 1.85 compatability must be installed.

Setting up Berkeley DB is often the most difficult part of the installation process. Less experienced Linux and BSD users should leave their Berkeley DB untouched if possible. Installing a version of Berkeley DB which is different from the version installed currently can mess up your system!

As of version 1.86, Berkeley DB uses a database format that is incompatible with earlier versions. Building version 2.1 or newer using

../dist/config --enable-compat185

will build Berkeley DB with an API for version 1.85. If you upgrade from 1.85 to a newer version, you will have to upgrade the database format even if you are using the 1.85 API.

If you install version 1.85.4, make sure you install the patches to the source code before compiling. Without the patch, the source will not compile and a runtime problem will be present.

The TinyCOBOL INSTALL file has some relevant developer's notes on installing TinyCOBOL with Berkeley DB. You may need to find where the Berkeley DB library, libdb*.so, is installed on your system. Berkeley DB is usually in /usr/lib, but could be installed elsewhere, such as
/usr/local/lib. The TinyCOBOL installer will search for libdb.so, libdb1.so, libdb2.so, libdb3.so and libdb-4.so. If your installation of Berkeley DB is named differently, you will need to create a copy or a hard link with an appropriate name. For example, if your Berkeley DB is version 4.1 and it is installed as /usr/local/lib/libdb41.so, you would create a hard link /usr/lib/libdb-4.so that points to /usr/local/lib/libdb41.so and, similarly, a hard link /usr/lib/libdb-4.a that points to
/usr/local/lib/libdb41.a.

The TinyCOBOL installer searches for Berkeley DB in /usr/lib by default. If your Berkeley DB is installed in a different directory, you will either have to create hard links from /usr/lib to your Berkeley DB library, or you will have to copy your libdb* files to the /usr/lib directory, or you will have to modify the TinyCOBOL installer so it uses your Berkeley DB library directory.

If your libdb* files aren't in /usr/lib, the simplest fix is probably creating hard links from /usr/lib to your system's Berkeley DB libdb* directory.

The TinyCOBOL installer searches for the Berkekely DB header files (db.h or db_185.h) in
/usr/include or /usr/include/db*, where * is “1”, “2”, “3” or “4”. If your system's Berkeley DB header files are not in one of these directories, you must apply a fix similar to the fix for the library files. If /usr/include/db* is not present, you may want to create it before linking to your installation's db.h and db_185.h files.

Unless you are building a specialized application for distribution, you should be able to use your default Berkeley DB installation.

The Berkeley DB license for versions more recent than 1.8x requires you to provide copies of your source code when you sell or give away your TinyCOBOL programs unless you purchase a license from Sleepycat Software.

Berkeley DB installation is outside of the scope of this user manual. Sleepycat Software distributes Berkeley DB and has the necessary installation notes. IBiblio.org has older versions of Berkeley DB.

Installing gcc

If gcc isn't already installed, locate and install gcc for your system. gcc installation is outside of the scope of this user manual.

Building TinyCOBOL from Source Code

Download tinycobol-0.61.tar.gz from the TinyCOBOL.org Downloads page. cd into the directory containing tinycobol-0.61 and execute:

gunzip tinycobol-0.61.tar.gz

tar -xvf tinycobol-0.61.tar

This will unpack and unarchive the TinyCOBOL source files and build files.

cd to the tinycobol-0.61 directory.

Read the README file and the installation instructions in the INSTALL file.

Make any changes to the configure script for Berkeley DB described previously in the Berkeley DB section of this manual.

The configure script will set up some parameters for building TinyCOBOL. The configure script will examine your system to set up options for the make program. configure uses the bison compiler compiler by default, but this manual uses the yacc193 compiler compiler , so use the command line option --with-yacc=yacc193.

Depending on how your system's Berkeley DB is set up, you might also need to use the option that specifies your version of Berkeley DB, the --with-libdb=[your Berkeley DB version number]. If your systemlibrary directory contains libdb.so and libdb.a, this option is not needed. Otherwise, with libdb1.* use --with-libdb=1, with libdb2.* use --with-libdb=2, with libdb3.* use --with-libdb=3, and with libdb-4.* use --with-libdb=4. Check the INSTALL file and the configure script for more information.

Other configuration options are available. The INSTALL file and the configure script provide more information.

The configure script will set up the system to use the libdl.so library by default. BSD doesn't usually have or need libdl.so, so in BSD, the following two changes are needed in the configure script:

1. define_with_dl must be assigned the value “no”. One way of ensuring this is by commenting the code that would set the value to “yes”.

2. Change htg_ld_args_dl=”-ldl” to htg_ld_args_dl=“” Change this in two places in the file.

Review the options in configure to determine what options you will need. A common option is --enable-lockserv. Create the configuration options by running the appropriate command:

./configure --with-yacc=yacc193 [your options]

or

./configure --with-yacc=yacc193 --with-libdb=# [your options]

If you received a message about “library db” not found, review the previous section on Berkeley DB.

In BSD, remove -ldl from the LIBS variable in the ./lib/Makefile file.

Make sure the INSTMAN1 variable in the tinycobol-0.61/info/Makefile file points to your system's man directory. If necessary, edit the tinycobol-0.61/info/Makefile file and change the INSTMAN1 variable to point to the appropriate man directory.

You must have write permission to the system executables directory to install. If your user id doesn't have write permissions, su to root to install and then execute the two commands:

make

make install

If using BSD, remember to use gmake instead of make.

Reboot if necessary and run the command:

htcobol -V

Post Installation Tasks

In BSD, the /usr/local/share/htcobol/htcobolrc file will need a minor modification. Two variables refer to the dynamic loader, dl. Because BSD does not have dl, all references to dl must be removed. Change

LD_EXTRA_LIBS: -ldl
LD_DCALL_LIBS: -ldl

to

LD_EXTRA_LIBS:
LD_DCALL_LIBS:

The htcobol program uses a variable, LD_PATH, in the htcobolrc file to point to the linker libraries. The installer assigns a value which is useful for building and testing the compiler. Change this variable to point to your library directories. Normally, you will change the variable as follows:

LD_PATH: -L. -L/usr/lib -L/usr/local/lib

If your installation will use statically linked libraries, you must install the static libraries. To install the statically linked libraries, cd to the TinyCOBOL ./lib directory and run:

make devel

make install-static

If you are using lockserver, build it now if you have not already done so. Please be aware that lockserver may not work with FreeBSD.

Verifying the Compiler Build

After building TinyCOBOL, test it to ensure that it works correctly. Run the test suites included in the TinyCOBOL tar file. Running the test suites is relatively easy.

cd to the test_suite directory. If you are using BSD, the main testing script cobol_test.pl, must be modified because it uses dl, which is not normally installed on BSD. A variable must be modified to prevent the test script from crashing. Remove -ldl from the line:

$LIBS=$g_libraries . " -L../../lib -lhtcobol " . $LIBDBNAME . " -ldl" . " -lm";

like so:

$LIBS=$g_libraries . " -L../../lib -lhtcobol " . $LIBDBNAME . " -lm";

Execute make. You should get almost all PASSed messages in the log file. A few COBOL verbs are not fully implemented at this time, so a handful of tests will fail. That is expected.

Compile and run the dyntest program in test.code/t33 to verify dynamic linking. On some systems, such as BSD, the rt.sh script may need conversion from bash to csh. If you get strange errors running rt.sh, verify the path to the shell.

Installation Using an RPM Binary

RPM installation is not recommended unless you know that the RPM was built specifically for your system. Even if the RPM was built for your O/S distribution, RPM still may not work. If you use an RPM installation, RPM is simple so this manual will not discuss how to us it. If you attempt an RPM install and RPM can't install because of numerous library dependencies, you probably should build TinyCOBOL from the source code.

Uninstalling

Uninstalling a TinyCOBOL RPM is trivial and will not be addressed in this manual.

To uninstall from a compiled version, cd to the tinycobol-0.61 directory and execute the two commands:

make cleanall

make distclean

Compiling

Compiler Environment and Options Setup

The compiler uses three levels of controls for compile options.

The first level is the compiler environment. The term “compiler environment” refers to the directories and files htcobol uses to compile a COBOL program. By default, htcobol reads the file htcobolrc from directory /usr/local/share/htcobol to determine the default compile options. The default dynamically loaded libraries are normally in /usr/local/lib. The default location of the preprocessor, htcobolpp, is /usr/local/share/htcobol. These defaults can be overriden by setting environment variables, TCOB_OPTIONS, TCOB_OPTIONS_PATH, TCOB_LD_LIBRARY_PATH, and TCOB_PP_PATH to the file or path you want to use.

The second level of control is the compiler options contained in htcobolrc. The options are documented in the htcobolrc file. Some of the htcobolrc options can be commented out and the compiler will use a default value. The compiler defaults are documented in the htcobolrc file.

BSD users must change the LD_EXTRA_LIBS, and LD_DCALL_LIBS options before using the compiler. The installer will default these two options to refer to the dl dynamic linker, which is not normally used by BSD. BSD users should delete “-ldl” from the LD_EXTRA_LIBS and LD_DCALL_LIBS options.

The third level of control is the command line options. The command line options override the compile options in htcobolrc. The compile options are documented fully in the htcobol man file.

Unlike many other COBOL compilers, TinyCOBOL does not have compile options which are put in the source code.

How to Compile—A Quick Introduction

Experienced Linux and BSD users can skip this section. This section is a simple tutorial to get absolute beginners started.

The TinyCOBOL compiler is named htcobol. The command line options are documented in the htcobol man pages. The general format is:

htcobol [options] [your program name]

The simplest way to get started compiling is through the command line. Shell scripts containing the command line statements can be used. Experienced developers usually use make files.

Command Line Compiling

If you are just getting started, create the following simple program in file and name it hello.cob:

IDENTIFICATION DIVISION.

PROGRAM-ID. HELLO.

PROCEDURE DIVISION.

DISPLAY "Hello, world!"

STOP RUN.

From the command line, cd to the folder containing hello.cob and run the two commands:

htcobol hello.cob

./hello

This should display the message “Hello, world!”

Shell Script Compiling

Place the commands

htcobol hello.cob

./hello

in a file named hello.sh. Run the command

sh hello.sh

This should display the message “Hello, world!”

make File Compiling

A complete tutorial for using make files is outside the scope of this manual. Here is a simple example of using a make file. BSD users will need to substitute gmake for make.

Create a new directory and copy the hello.cob program into it. Create a new file named Makefile and put the following text into it:

# Starter example for hello.cob

SRC_FILE=hello.cob

hello.exe : ${SRC_FILE}

htcobol ${SRC_FILE}

Make sure that you put a tab in front of “htcobol ${SRC_FILE}”, not spaces, otherwise make will not work. Run the commands:

make

./hello

This should display the message “Hello, world!”

Command Line Options

The command line options override the options in the htcobolrc file. Most of the TinyCOBOL command line options are sufficiently documented in the htcobol man page.

-a Creates a static runtime library. [are these all subroutines that must be statically linked into a main module?]

-B [static | dynamic] [Determines if the libraries are being compiled into the object module or not.]

-c compiles into a statically linked module.

-g generate compiler debugging output

-l[library name] [list libraries included with the TC distribution]

-m create shared library. [does this combine the modules into a library or does a seperate utility do that?]

-S [is this mostly used for development?]

-t [what intermediary files are generated? Where are they normally located? Will assembler always be generated if the source is compiled directly into object code.?]

-x the default.

-C [how does this work with the -B static option?]

htcobolrc Options

Compile Errors

Troubleshooting

Problem:	Message -- cannot find -lhtcobol

Causes:	The libhtcobol.* library files are not in the linker's search path. The libhtcobol.* library files are normally located in the /usr/local/lib directory. Possible causes are :

*	the libraries are missing,

*	the libraries a located in an unexpected directory,

*	the LD_PATH variable in htcobolrc is not set correctly,

*	htcobolrc is not installed correctly,

*	the -B static htcobol command line option was used and the TinyCOBOL static libraries were not installed.

To fix:	Verify that the LD_PATH variable in htcobolrc points to the correct link directories. LD_PATH is typically set to:

LD_PATH: -L. -L/usr/lib -L/usr/local/lib

Verify that the libhtcobol.* libraries are located where you think they should be. Normally, they are in /usr/local/lib, but your system may have them in a different location. If they are in a different location, verify that LD_PATH is set correctly.

If LD_PATH is set correctly and the libhtcobol.* libraries are where they should be, check the installation of htcobolrc by running the htcobol compiler using the -L option to explicitly decribe where the libraries are located. If the -L option eliminates the error, htcobolrc is not set up correctly.

If the -B static option was used, the static libraries may not have been installed. cd to the TinyCOBOL ./lib directory. Run:

make devel

make install-static

Running a Program

Command Line Execution

xxx

Script File Execution

xxx

make Files

xxx

lockserver

xxx

Troubleshooting

xxx

GNU Documentation License

GNU Free Documentation License

Version 1.2, November 2002

Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.

59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

C. State on the Title page the name of the publisher of the Modified Version, as the publisher.

D. Preserve all the copyright notices of the Document.

E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

H. Include an unaltered copy of this License.

I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (c) YEAR YOUR NAME.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:

with the Invariant Sections being LIST THEIR TITLES, with the

Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

TinyCOBOL v 0.61 User Manual	Page 21

TinyCOBOL v 0.61 User Manual	Page 21

TinyCOBOL v 0.61 User Manual

2004-01-27T10:42:14