************* OpenCOBOL FAQ ************* .. Formatted for docutils, ReStructuredText. rst-buidhtml .. Texinfo form created using Pandoc .. Attention:: This is the 1.0 release candiate of the OpenCOBOL FAQ .. Sectnum:: :Authors: Brian Tiffin [btiffin]_, Joseph James Frantz [aoirthoir]_, Roger While [Roger]_ Keisuke Nishida [Keisuke]_ (with the invaluable assistance of many others) :Organization: The OpenCOBOL Project :Version: 1.0rc, August 24, 2008 :Status: Release Candidate :Copyright: |copyleft| :Changelog: changelog_ .. Contents:: FAQ Index ========= OpenCOBOL ========= ---------------------- Q. What is OpenCOBOL_? ---------------------- OpenCOBOL is an open-source COBOL_ compiler. OpenCOBOL implements a substantial part of the `COBOL 85`_ and `COBOL 2002`_ standards, as well as many extensions of the existent COBOL compilers. OpenCOBOL translates COBOL into C and compiles the translated code using the native C compiler. You can build your COBOL programs on various platforms, including Unix/Linux, Mac OS X, and Microsoft Windows. ------------------ Q. What is COBOL_? ------------------ COBOL is an acronym for COmmon Business Oriented Language. This author has always thought of it as "Common Business" Oriented more than Common "Business Oriented", but that emphasis is perhaps up to the readers point of view. ----------------------------- Q. How is OpenCOBOL licensed? ----------------------------- The compiler is licensed under `GNU General Public License`_. The run-time library is licensed under `GNU Lesser General Public License`_. All source codes are copyright by the respective authors. OpenCOBOL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. --------------------------------------------- Q. What platforms are supported by OpenCOBOL? --------------------------------------------- `OpenCOBOL 1.0`_ the current official release version, hosted on SourceForge.net, compiles on: * All 32-bit MS Windows (95/98/NT/2000/XP) * All POSIX (Linux/BSD/UNIX-like OSes) * OS/X `OpenCOBOL 1.1`_ also hosted on SourceForge.net, has been tested on * MS Windows * POSIX Systems * OS/X ----------------------------- Q. How complete is OpenCOBOL? ----------------------------- `OpenCOBOL 1.0`_ implements a substantial portion of `COBOL 85`_, supports many of the advances and clarifications of `COBOL 2002`_, and includes many extensions in common use from Micro Focus COBOL, ACUCOBOL and other exsistent compilers. `OpenCOBOL 1.1`_ implements a more substantial portion of the `COBOL 85`_ Dialect, `COBOL 2002`_ and a growing number of vendor extensions. Some proposed COBOL 2008 features have also been implemented. Compatibility support includes: * MF for Micro Focus * IBM for IBM compatibility * MVS * BS2000 OpenCOBOL also includes some advanced features allowing source code such as :: CALL "cfunction" USING BY REFERENCE ADDRESS OF VAR-IN-LINKAGE-SECTION. Passing the equivalent of char**, pointer to pointer to char. Just as a small example of the level of coverage provided by OpenCOBOL. --------------------------------- Q. Will I be amazed by OpenCOBOL? --------------------------------- This author believes so. For an open source implementation of COBOL, OpenCOBOL may surprise you in the depth and breadth of its COBOL standard feature support, usability and robustness. -------------------------------- Q. Who do I thank for OpenCOBOL? -------------------------------- Many people. In particular Keisuke Nishida and Roger While. See the THANKS file in the source code archive for more names of people that have worked on the OpenCOBOL project. Roger points out that the list is woefully incomplete. To quote:: The OC project would not have been where it is today without the significant/enormous help from many-many persons. The THANKS file does not even do justice to this. --------------------------------------- Q. Does OpenCOBOL include a Test Suite? --------------------------------------- Why yes it does. 74 syntax tests, 170 coverage tests, and 16 data representation tests at last count. From the development tarball, **$ make check** will evaluate and report on the test suite. ------------------------------------------- Q. Does OpenCOBOL pass the NIST Test Suite? ------------------------------------------- Many. OpenCOBOL achieves a very high level of COBOL 85 conformance. The National Institute of Standards and Technology, NIST, maintains a COBOL 85 implementation verification suite of tests. An archive of the tests can be found at http://www.itl.nist.gov/div897/ctg/cobol_form.htm Instructions for use of the NIST suite is included in the build archive under:: tests/cobol85/README Basically, it is a simple **uncompress** and **make** then sit back and relax. The scripts run OpenCOBOL over some 364 programs/modules and includes thousands of test passes. :: Test Modules ------------ Core tests: NC - COBOL nucleus tests SM - COPY sentence tests IC - CALL sentence tests File I-O tests: SQ - Sequential file I-O tests RL - Relative file I-O tests IX - Indexed file I-O tests ST - SORT sentence tests Advanced facilities: IF - Intrinsic Function tests The summary.log from a run in July 2008:: Module programs executed error crash details ------ -------- -------- ----- ----- ------- NC 92 92 0 0 4363,0,6,11/4380 SM 15 13 0 0 289,2,3,1/295 IC 24 21 3 0 240,0,4,0/244 SQ 81 81 0 0 512,0,6,81/599 RL 32 32 0 0 1827,0,5,0/1832 IX 39 39 0 0 507,0,1,0/508 ST 39 39 0 0 278,0,0,0/278 IF 42 42 0 0 732,0,0,0/732 ------ -------- -------- ----- ----- ------- Total 364 359 3 0 --------------------------------------- Q. What about OpenCOBOL and benchmarks? --------------------------------------- .. Attention:: Look into this --------------------------------- Q. Can OpenCOBOL be used for CGI? --------------------------------- Yes. Through standard IO redirection and the extended **ACCEPT ... FROM ENVIRONMENT ...** feature, OpenCOBOL is more than capable of supporting advanced CGI programming. ----------------------------------------------------- Q. Can OpenCOBOL by used for production applications? ----------------------------------------------------- Depends. OpenCOBOL is still in active development. Feature coverage is growing, and while the current implementation offers great coverage, applicability to any given situation would need to analyzed and risks evaluated before commitment to production use. The licensing allows for commercial use, but OpenCOBOL also ships with notice of indemnity, meaning that there are no guarantees when using OpenCOBOL, directly or indirectly. There may be a time when commercial support of OpenCOBOL is offered, but at the time of writing no known offering exists. *Search google just in case!* And yes, OpenCOBOL is used in production environments. From [Roger]_: :: Incidentally, OC has been (and still is) used in production environments since 2005. (This includes projects that I personally worked on plus other   projects reported to me; these worldwide) The OC project would not have been where it is today without the significant/enormous help from many-many persons. The THANKS file does not even do justice to this. .. Attention:: Look into this - need more entries ------------------------------------------------ Q. Where can I get more information about COBOL? ------------------------------------------------ The `COBOL FAQ`_ by William M Klein is a great place to start. A google of the search words "COBOL" or "OpenCOBOL" are bound to lead to enough days worth of reading of in-depth articles, opinions and technical information to satisfy the greatest of curiosities. The COBUG_ site *COBOL User Groups* is also a wonderful resource for OpenCOBOL developers. ---------------------------------------------------- Q. Where can I get more information about OpenCOBOL? ---------------------------------------------------- The opencobol.org_ website is probably the best place to find out more about the OpenCOBOL system. --------------------------------------------- Q. Can I help out with the OpenCOBOL project? --------------------------------------------- Absolutely. Visit the opencobol.org_ website and either post a message asking what needs to be done, or perhaps join the development mailing list to find out the current state of development. See `Q. Is there an OpenCOBOL mailing list?`_ for some details. OpenCOBOL is a GPL licensed open source project and while [Roger]_ is the lead developer he is quite open to code submissions. Having a central point of development allows for consistency and the very high level of quality control enjoyed by OpenCOBOL users. -------------------------------------- Q. Is there an OpenCOBOL mailing list? -------------------------------------- Yes. Visit opencobol.org_ for details. The OpenCOBOL development mailing list is graciously hosted by SourceForge. The ML archive is available at http://sourceforge.net/mailarchive/forum.php?forum_name=open-cobol-list and once you have subscribed, the list will accept messages at the open-cobol-list email destination at lists.sourceforge.net. ----------------------------------------------------------- Q. Where can I find more information about COBOL standards? ----------------------------------------------------------- The `COBOL 85`_ standard is documented in * ANSI X3.23-1985 * ISO 1989-1985 * ANSI X3.23a-1989 * ANSI X3.23b-1993 .. Attention:: Look into this ------------------------------ Q. Do you know any good jokes? ------------------------------ Maybe. * A computer without COBOL and Fortran is like a piece of chocolate cake without ketchup or mustard. *John Krueger* * A determined coder can write COBOL programs in any language. *Author: unknown* * Rumour has it that the object oriented specification for COBOL was code named *ADD 1 TO COBOL GIVING COBOL.* *Author: unknown* A less verbose, more concise version; *very unCOBOL that* *ADD 1 TO COBOL.* *Thanks to aoirthoir* * A common dis of COBOL jokes that the acronym is: Completely Obsolete Business Oriented Language. *Author unkown* We know better. The reality is: Can't Obsolesce Because Of Legacy. *Brian Tiffin* * Ruby on Rails? Don't forget COBOL ON COGS. http://www.coboloncogs.org/INDEX.HTM * Eat COBOL, 200 billion lines can't be wrong. *Brian Tiffin* * What did COBOL yell to the escaping thief? **STOP RUN RETURNING NOW.** *Brian Tiffin* * What did COBOL reply to the executive? *Why yes, I can* **PERFORM JUMPS THRU HOOPS.** *Brian Tiffin* * What did OpenCOBOL reply to the executive? *Sir, I can* **PERFORM JUMPS THRU FLAMING-HOOPS UNTIL HELL-FREEZES-OVER.** *And being COBOL, I have to show you how little code it takes:* :: identification division. program-id. freeze. data division. working-storage section. 01 hell pic 9. 88 hell-freezes-over value 1. procedure division. perform jumps thru flaming-hoops until hell-freezes-over. stop run. jumps. flaming-hoops. divide 1 by 0 giving hell. *Brian Tiffin* ======= History ======= ------------------------------------------------ Q. What is the development history of OpenCOBOL? ------------------------------------------------ OpenCOBOL was initially developed by Keisuke Nishida [Keisuke]_ from work on TinyCOBOL_ originally developed by Rildo Pragana. The first public release was version 0.9.0 on January 25th, 2002. Development continued apace, with version 0.30 released by Keisuke on August 8th, 2004. Roger While [Roger]_ then took up the role as lead developer on October 30th, 2004. Version 0.31 was released February 1st, 2005. Version 0.32 was released May 12th, 2005. Version 0.33 started on May 13th, 2005. Version 1.0 was released on December 27th, 2007. -------------------------------------------- Q. What is the current version of OpenCOBOL? -------------------------------------------- OpenCOBOL 1.0 was released December 27th, 2007 by Roger While [Roger]_. The decision to go 1.0 from the 0.33 version followed many incremental enhancements from 2005 through till late in 2007. OpenCOBOL 1.1 pre-release became active on December 27th, 2007 and is |currently| in active development. The pre-release source tar can be found at `OpenCOBOL 1.1`_ with installer instructions at `OpenCOBOL Install`_ and in the INSTALLING text file of the sources. ----------------------------------------- Q. Are there pre-built OpenCOBOL packages ----------------------------------------- Yes. Debian APT, and RPM packages exist. Packages for NetBSD. Many. Google *opencobol packages* for any late breaking news. A Debian apt binary package exists for OpenCOBOL 1.0 as **open-cobol** and lists dependencies of * libc6 (>= 2.7-1), * libcob1, * libcob1-dev (= 1.0-1), * libdb4.5 (>= 4.5.20-3), * libdb4.5-dev, * libgmp3-dev, * libgmp3c2, * libltdl3-dev, * libncurses5 (>= 5.6+20071006-3) Thanks to the gracious efforts of Bart Martens, bartm on Debian's .org domain. =============== Using OpenCOBOL =============== ------------------------------ Q. How do I install OpenCOBOL? ------------------------------ Installation instructions can be found at `OpenCOBOL Install`_. Debian The Debian binary package makes installing OpenCOBOL 1.0 a snap. From **root** or using sudo:: $ apt-get open-cobol Windows Build from sources under Cygwin or MinGW. Follow the instructions from the site listed above. ---------------------------------------------- Q. Does OpenCOBOL have any other dependencies? ---------------------------------------------- OpenCOBOL relies on a native C compiler with POSIX compatibility. GCC being a freely available compiler collection supported by most operating systems |currently| in use. OpenCOBOL requires the following external libraries to be installed: GNU MP (libgmp) 4.1.2 or later libgmp is used to implement decimal arithmetic. GNU MP is licensed under GNU Lesser General Public License. GNU Libtool (libltdl) libltdl is used to implement dynamic CALL statements. GNU Libtool is licensed under GNU Lesser General Public License. NOTE - Libtool is not required for Linux and Windows (including MinGW and Cygwin) The following libraries are optional: Berkeley DB (libdb) 1.85 or later libdb can be used to implement indexed file I/O and SORT/MERGE. Berkeley DB is licensed under the original BSD License (1.85) or their own open-source license (2.x or later). Note that, as of 2.x, if you linked your software with Berkeley DB, you must distribute the source code of your software along with your software, or you have to pay royalty to Oracle Corporation. For more information about Oracle Berkeley DB dual licensing go to : Oracle / Embedded / Oracle Berkeley DB Ncurses (libncurses) 5.2 or later libncurses can be used to implement SCREEN SECTION. Ncurses is licensed under a BSD-style license. ---------------------------------------- Q. How does the OpenCOBOL compiler work? ---------------------------------------- OpenCOBOL is a multi-stage command line driven compiler. Command line options control what stages are performed during processing. 1. Preprocess #. Translate #. Compile #. Assemble #. Link #. Build OpenCOBOL produces intermediate C source code that is then passed to a configured C compiler and other tools. the GNU C compiler, **gcc** being a standard. The main tool, **cobc**, by default, produces modules, linkable shared object files. Example :: $ cat hello.cob Original source code; :: 000100* HELLO.COB OpenCOBOL FAQ example 000200 IDENTIFICATION DIVISION. 000300 PROGRAM-ID. hello. 000400 PROCEDURE DIVISION. 000500 DISPLAY "Hello World!". 000600 STOP RUN. OpenCOBOL stages:: $ cobc -E hello.cob Preprocess only; For one thing, FIXED format becomes FREE format. For another COPY is processed. Displays :: # 1 "hello.cob" IDENTIFICATION DIVISION. PROGRAM-ID. hello. PROCEDURE DIVISION. DISPLAY "Hello World!". STOP RUN. to standard out. :: $ cobc -C hello.cob Translate only; preprocesses and then translates the COBOL sources into C. You can examine these files to get a good sense of how the OpenCOBOL environment interacts with the native C facilities. OpenCOBOL 1.1 produced **hello.c.h** and **hello.c**. :: $ cobc -S hello.cob Compile only; outputs assembly file. Produces **hello.s**. :: $ cobc -c hello.cob Compile and assemble, do not link. Produces **hello.o**. :: $ cobc -m hello.cob Build dynamically loadable module. The is the *default behaviour*. This example produces **hello.so** or **hello.dll**. :: $ cobcrun hello Will scan the DSO_ hello.so, and then link, load, and execute hello. .. Attention:: Need a little OS/X info here :: $ cobc -x hello.cob Build an executable program. This examples produces **hello** or **hello.exe**. **This is important**. *cobc* produces a *Dynamic Shared Object* by default. *To create executables*, you need to use **-x**. :: $ ./hello Hello World! OpenCOBOL also supports features for multiple source, multiple language programming, detailed in the FAQ at `Q. Does OpenCOBOL support modules?`_. ---------------- Q. What is cobc? ---------------- **cobc** is the OpenCOBOL compiler. See `Q. What compiler options are supported?`_ for more information. ------------------- Q. What is cobcrun? ------------------- **cobcrun** is the OpenCOBOL driver program that allows the execution of programs stored in OpenCOBOL modules. The **cobc** compiler, by default, produces modules (the *-m* option). These modules are linkable dynamic shared objects (DSO). Using GNU/Linux for example:: $ cobc -x hello.cob $ ./hello Hello World! $ cobc hello.cob $ cobcrun hello Hello World! The **cobc -x hello.cob** built an executable binary called hello. The **cobc hello.cob** produced a DSO_ hello.so, and cobcrun resolves the entry point and executes the code, right from the DSO_. **cobcrun** *is the compiler author's preferred way to manage OpenCOBOL development.* It alleviates knowing which source file needs *-x* while encouraging proper modular programming, a mainstay of OpenCOBOL. ---------------------- Q. What is cob-config? ---------------------- **cob-config** is a program that can be used to find the C compiler flags and libraries required for compiling. Using GNU/Linux for example:: $ cob-config Usage: cob-config [OPTIONS] Options: [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version] [--libs] [--cflags] $ cob-config --libs -L/usr/local/lib -lcob -lm -lgmp -lncurses -ldb $ cob-config --cflags -I/usr/local/include You may need to use these features during mixed source language development, usually by back-ticking the command output inline with other **gcc** commands. --------------------------------------- Q. What compiler options are supported? --------------------------------------- .. Note to maintainers. Build with $ cobc --help and indent 4 spaces. :: Usage: cobc [options] file... Options: --help Display this message --version, -V Display compiler version -v Display the programs invoked by the compiler -x Build an executable program -m Build a dynamically loadable module (default) -std= Compile for a specific dialect : cobol2002 Cobol 2002 cobol85 Cobol 85 ibm IBM Compatible mvs MVS Compatible bs2000 BS2000 Compatible mf Micro Focus Compatible default When not specified See config/default.conf and config/\*.conf -free Use free source format -fixed Use fixed source format (default) -O, -O2, -Os Enable optimization -g Produce debugging information in the output -debug Enable all run-time error checking -o Place the output into -b Combine all input files into a single dynamically loadable module -E Preprocess only; do not compile, assemble or link -C Translation only; convert COBOL to C -S Compile only; output assembly file -c Compile and assemble, but do not link -t Generate and place a program listing into -I Add to copybook search path -L Add to library search path -l Link the library -D Pass to the C compiler -conf= User defined dialect configuration - See -std= --list-reserved Display all reserved words -save-temps Do not delete intermediate files -MT Set target file used in dependency list -MF Place dependency list into -ext Add default file extension -Wall Enable all warnings -Wobsolete Warn if obsolete features are used -Warchaic Warn if archaic features are used -Wcolumn-overflow Warn if any text after column 72 -Wredefinition Warn incompatible redefinition of data items -Wconstant Warn inconsistent constant -Wparentheses Warn lack of parentheses around AND within OR -Wterminator Warn lack of scope terminator (END-XXX) -Wstrict-typing Warn type mismatch strictly -Wimplicit-define Warn implicitly defined data items -Wcall-params Warn non 01/77 items for CALL params (NOT set with -Wall) -Wtruncate Warn possible field truncation (NOT set with -Wall) -ftrace Generate trace code (Executed SECTION/PARAGRAPH) -ftraceall Generate trace code (Executed SECTION/PARAGRAPH/STATEMENTS) -fsyntax-only Syntax error checking only; don't emit any output -fdebugging-line Enable debugging lines ('D' in indicator column) -fsource-location Generate source location code (Turned on by -debug or -g) -fimplicit-init Do automatic initialization of the Cobol runtime system -fstatic-linkage Statically allocate non-USING LINKAGE parameters -fsign-ascii Numeric display sign ASCII (Default on ASCII machines) -fsign-ebcdic Numeric display sign EBCDIC (Default on EBCDIC machines) -fstack-check PERFORM stack checking (Turned on by -debug or -g) -ffold-copy-lower Fold COPY subject to lower case (Default no transformation) -ffold-copy-upper Fold COPY subject to upper case (Default no transformation) -fnotrunc Do not truncate binary fields according to PIC (ala MF) -fnull-param Pass extra NULL terminating pointers on CALL statements -------------------------------------------- Q. What dialects are supported by OpenCOBOL? -------------------------------------------- Using the **std=** compiler option, OpenCOBOL can be configured to compile using specific historical COBOL compiler features and quirks. Supported dialects include: * default * cobol85 * cobol2002 * ibm * mvs * mf * bs2000 For details on what options and switches are used to support these dialect compiles, see the **config/** directory of your OpenCOBOL installation. For Debian GNU/Linux, that will be **/usr/share/open-cobol/config/** if you used APT to install an OpenCOBOL package or **/usr/local/share/open-cobol/config/** after a build from the source archive. For example: the *bs2000.conf* file restricts data representations to 2, 4 or 8 byte binary while *mf.conf* allows data representations from 1 thru 8 bytes. *cobol85.conf* allows debugging lines, *cobol2002.conf* configures the compiler to warn that this feature is obsolete. ----------------------------------------- Q. What are the OpenCOBOL reserved words? ----------------------------------------- COBOL_ is a reserved word rich language. The OpenCOBOL compiler recognizes: .. Note to maintainers. Built with $ cobc --list-reserved, followed by a 74 column wide reformat and 4 space indent. The counts were calculated from $ wc and grepping for the literal "-1" in the cobc/reserved.c source. :: ACCEPT ACCESS ACTIVE-CLASS ADD ADDRESS ADVANCING AFTER ALIGNED ALL ALLOCATE ALPHABET ALPHABETIC ALPHABETIC-LOWER ALPHABETIC-UPPER ALPHANUMERIC ALPHANUMERIC-EDITED ALSO ALTER ALTERNATE AND ANY ANYCASE ARE AREA AREAS ARGUMENT-NUMBER ARGUMENT-VALUE ARITHMETIC AS ASCENDING ASSIGN AT ATTRIBUTE AUTO AUTOMATIC B-AND B-NOT B-OR B-XOR BACKGROUND-COLOR BASED BEFORE BELL BINARY BINARY-C-LONG BINARY-CHAR BINARY-DOUBLE BINARY-LONG BINARY-SHORT BIT BLANK BLINK BLOCK BOOLEAN BOTTOM BY BYTE-LENGTH CALL CANCEL CD CENTER CF CH CHAIN CHAINING CHARACTER CHARACTERS CLASS CLASS-ID CLASSIFICATION CLOSE CODE CODE-SET COL COLLATING COLS COLUMN COLUMNS COMMA COMMAND-LINE COMMIT COMMON COMMUNICATION COMP COMP-1 COMP-2 COMP-3 COMP-4 COMP-5 COMP-X COMPUTATIONAL COMPUTATIONAL-1 COMPUTATIONAL-2 COMPUTATIONAL-3 COMPUTATIONAL-4 COMPUTATIONAL-5 COMPUTATIONAL-X COMPUTE CONDITION CONFIGURATION CONSTANT CONTAINS CONTENT CONTINUE CONTROL CONTROLS CONVERTING COPY CORR CORRESPONDING COUNT CRT CURRENCY CURSOR CYCLE DATA DATA-POINTER DATE DAY DAY-OF-WEEK DE DEBUGGING DECIMAL-POINT DECLARATIVES DEFAULT DELETE DELIMITED DELIMITER DEPENDING DESCENDING DESTINATION DETAIL DISABLE DISK DISPLAY DIVIDE DIVISION DOWN DUPLICATES DYNAMIC EBCDIC EC EGI ELSE EMI ENABLE END END-ACCEPT END-ADD END-CALL END-COMPUTE END-DELETE END-DISPLAY END-DIVIDE END-EVALUATE END-IF END-MULTIPLY END-OF-PAGE END-PERFORM END-READ END-RECEIVE END-RETURN END-REWRITE END-SEARCH END-START END-STRING END-SUBTRACT END-UNSTRING END-WRITE ENTRY ENTRY-CONVENTION ENVIRONMENT ENVIRONMENT-NAME ENVIRONMENT-VALUE EO EOL EOP EOS EQUAL EQUALS ERASE ERROR ESCAPE ESI EVALUATE EXCEPTION EXCEPTION-OBJECT EXCLUSIVE EXIT EXPANDS EXTEND EXTERNAL FACTORY FALSE FD FILE FILE-CONTROL FILE-ID FILLER FINAL FIRST FLOAT-EXTENDED FLOAT-LONG FLOAT-SHORT FOOTING FOR FOREGROUND-COLOR FOREVER FORMAT FREE FROM FULL FUNCTION FUNCTION-ID GENERATE GET GIVING GLOBAL GO GOBACK GREATER GROUP GROUP-USAGE HEADING HIGH-VALUE HIGH-VALUES HIGHLIGHT I-O I-O-CONTROL ID IDENTIFICATION IF IGNORING IMPLEMENTS IN INDEX INDEXED INDICATE INHERITS INITIAL INITIALIZE INITIALIZED INITIATE INPUT INPUT-OUTPUT INSPECT INTERFACE INTERFACE-ID INTO INTRINSIC INVALID INVOKE IS JUST JUSTIFIED KEY LABEL LAST LC_ALL LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME LEADING LEFT LENGTH LESS LIMIT LIMITS LINAGE LINAGE-COUNTER LINE LINE-COUNTER LINES LINKAGE LOCAL-STORAGE LOCALE LOCK LOW-VALUE LOW-VALUES LOWLIGHT MANUAL MEMORY MERGE MESSAGE METHOD METHOD-ID MINUS MODE MOVE MULTIPLE MULTIPLY NATIONAL NATIONAL-EDITED NATIVE NEGATIVE NESTED NEXT NO NONE NORMAL NOT NULL NULLS NUMBER NUMBERS NUMERIC NUMERIC-EDITED OBJECT OBJECT-COMPUTER OBJECT-REFERENCE OCCURS OF OFF OMITTED ON ONLY OPEN OPTIONAL OPTIONS OR ORDER ORGANIZATION OTHER OUTPUT OVERFLOW OVERLINE OVERRIDE PACKED-DECIMAL PADDING PAGE PAGE-COUNTER PARAGRAPH PERFORM PF PH PIC PICTURE PLUS POINTER POSITION POSITIVE PRESENT PREVIOUS PRINTER PRINTING PROCEDURE PROCEDURE-POINTER PROCEDURES PROCEED PROGRAM PROGRAM-ID PROGRAM-POINTER PROMPT PROPERTY PROTOTYPE PURGE QUEUE QUOTE QUOTES RAISE RAISING RANDOM RD READ RECEIVE RECORD RECORDING RECORDS RECURSIVE REDEFINES REEL REFERENCE RELATION RELATIVE RELEASE REMAINDER REMOVAL RENAMES REPLACE REPLACING REPORT REPORTING REPORTS REPOSITORY REQUIRED RESERVE RESET RESUME RETRY RETURN RETURNING REVERSE-VIDEO REWIND REWRITE RF RH RIGHT ROLLBACK ROUNDED RUN SAME SCREEN SD SEARCH SECONDS SECTION SECURE SEGMENT SELECT SELF SEND SENTENCE SEPARATE SEQUENCE SEQUENTIAL SET SHARING SIGN SIGNED SIGNED-INT SIGNED-LONG SIGNED-SHORT SIZE SORT SORT-MERGE SOURCE SOURCE-COMPUTER SOURCES SPACE SPACES SPECIAL-NAMES STANDARD STANDARD-1 STANDARD-2 START STATEMENT STATUS STEP STOP STRING STRONG SUB-QUEUE-1 SUB-QUEUE-2 SUB-QUEUE-3 SUBTRACT SUM SUPER SUPPRESS SYMBOL SYMBOLIC SYNC SYNCHRONIZED SYSTEM-DEFAULT TABLE TALLYING TAPE TERMINAL TERMINATE TEST TEXT THAN THEN THROUGH THRU TIME TIMES TO TOP TRAILING TRUE TYPE TYPEDEF UCS-4 UNDERLINE UNIT UNIVERSAL UNLOCK UNSIGNED UNSIGNED-INT UNSIGNED-LONG UNSIGNED-SHORT UNSTRING UNTIL UP UPDATE UPON USAGE USE USER-DEFAULT USING UTF-16 UTF-8 VAL-STATUS VALID VALIDATE VALIDATE-STATUS VALUE VALUES VARYING WHEN WITH WORKING-STORAGE WRITE YYYYDDD YYYYMMDD ZERO ZEROES ZEROS 511 words in OC 1.1, 136 of which are marked not yet implemented. 375 functional reserved words, as of July 2008. ---------------------------------- Q. Does OpenCOBOL support modules? ---------------------------------- Yes. Quite nicely in fact. Dynamically! COBOL_ modules, and object files of many other languages are linkable. As OpenCOBOL uses intermediate C, linkage to other languages is well supported across many platforms. The OpenCOBOL CALL_ instruction maps COBOL USAGE_ to many common C stack frame data representations. Multipart, complex system development is well integrated in the OpenCOBOL model. :: $ cobc -b hello.cob goodbye.cob Combines both source files into a single dynamically loadable module. Example produces **hello.so**. Using the **-l** link library option, OpenCOBOL has access to most shared libraries supported on it's platforms. :: $ cobc -x -lcurl showcurl.cob Will link the /usr/lib/libcurl.so (*from the cURL project*) to showcurl. The OpenCOBOL CALL_ verb will use this linked library to resolve calls at runtime. Large scale systems are at the heart of COBOL development and OpenCOBOL is no exception. --------------------------------------------- Q. What is the OpenCOBOL LINKAGE SECTION for? --------------------------------------------- Argument passing in COBOL is normally accomplished through the **LINKAGE SECTION**. This section does not allocate or initialize memory as would definitions in the WORKING-STORAGE SECTION. Care must be taken to inform COBOL of the actual source address of these variables before use. Influences CHAINING and USING phrases. See CALL_ for more details. --------------------------------------------------------------- Q. What does the -fstatic-linkage OpenCOBOL compiler option do? --------------------------------------------------------------- Under normal conditions, the *LINKAGE SECTION* is unallocated and uninitialized. When a LINKAGE SECTION variable, that is not part of the *USING* phrase (not a named calling argument), any memory that has been addressed becomes unaddressable across calls. *-fstatic-linkage* creates static addressing to the LINKAGE SECTION. From [Roger]_:: This relates to LINKAGE items that are NOT referred to in the USING phrase of the PROCEDURE DIVISION. It also only has relevance when the program is CALL'ed from another prog. This means that the addressability of these items must be programmed (usually with SET ADDRESS) before reference. Per default, the item loses it's addressability on exit from the program. This option causes the module to retain the item's address between CALL invocations of the program. With some rumours that this may become the default in future releases of OpenCOBOL, and the *-fstatic-linkage* option may be deprecated. ----------------------------------------- Q. Does OpenCOBOL support SCREEN SECTION? ----------------------------------------- Yes. The OpenCOBOL 1.1 pre-release now includes support for SCREEN SECTIONs. Experimental release for this support occurred in early July, 2008. The compiler recognizes most (if not all) of the *Screen description entry* of the COBOL 2008 Draft standard. External variables that influence screen handling include COB_SCREEN_EXCEPTIONS=Y To enable exceptions during ACCEPT. COB_SCREEN_ESCAPE=Y To enable handling of the escape key. See `Q. Does OpenCOBOL support CRT STATUS?`_ for more information on key codes and exception handling. According to the standard a SCREEN SECTION ACCEPT does not need to be proceeded by a DISPLAY. The extra DISPLAY won't hurt, but is not necessary. ------------------------------------------------------- Q. What are the OpenCOBOL SCREEN SECTION colour values? ------------------------------------------------------- The FOREGROUND-COLOR and BACKGROUND-COLOR clauses will accept :: 78 black value 0. 78 blue value 1. 78 green value 2. 78 cyan value 3. 78 red value 4. 78 magenta value 5. 78 brown value 6. 78 white value 7. The display of these colours are also influenced by HIGHLIGHT, LOWLIGHT and REVERSE-VIDEO options. For instance, brown will display as yellow when HIGHLIGHT is used. ------------------------------------- Q. Does OpenCOBOL support CRT STATUS? ------------------------------------- Yes. :: ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES. CRT STATUS IS screen-status. DATA DIVISION. WORKING-STORAGE SECTION. COPY screenio. 01 screen-status pic 9(4). PROCEDURE DIVISION. ACCEPT screen-sample. IF screen-status = COB-SCR-F1 ... There is also a special OpenCOBOL variable, **COB-CRT-STATUS** which can be used instead of the CRT STATUS special name. There is also a COPY text that ships with OpenCOBOL, copy/screenio.cpy that can be included in the DATA DIVISION and provides 78 level constants for supported key status codes. Some values include: * COB-SCR-F1 thru * COB-SCR-F64 * COB-SCR-ESC examine the file to see the other values. ------------------------------------------ Q. Does OpenCOBOL implement Report Writer? ------------------------------------------ Not at this time. *July, 2008* But it does support LINAGE. See `Q. Does OpenCOBOL implement LINAGE?`_ ----------------------------------- Q. Does OpenCOBOL implement LINAGE? ----------------------------------- Yes. LINAGE sets up logical pages inside file descriptors enhancing the WRITE operations and enabling the END-OF-PAGE clause. :: FILE SECTION. FD A-REPORT LINAGE IS 13 LINES TOP 2 FOOTING 2 BOTTOM 3. LINAGE clauses can set:: TOP LINES FOOTING BOTTOM The LINAGE-COUNTER_ noun is maintained during writes to LINAGE output files. ---------------------------------------------------- Q. Does OpenCOBOL implement any Intrinsic Functions? ---------------------------------------------------- Yes, many. As of the July 2008 1.1 pre-release :: ABS, ACOS, ANNUITY, ASIN, ATAN, BYTE-LENGTH, CHAR, COS, CURRENT-DATE, DATE-OF-INTEGER, DATE-TO-YYYYMMDD, DAY-OF-INTEGER, DAY-TO-YYYYDDD, E, EXCEPTION-FILE, EXCEPTION-LOCATION, EXCEPTION-STATEMENT, EXCEPTION-STATUS, EXP, EXP10, FACTORIAL, FRACTION-PART, INTEGER, INTEGER-OF-DATE, INTEGER-OF-DAY, INTEGER-PART, LENGTH, LOCALE-DATE, LOCALE-TIME, LOG, LOG10, LOWER-CASE, MAX, MEAN, MEDIAN, MIDRANGE, MIN, MOD, NUMVAL, NUMVAL-C, ORD, ORD-MAX, ORD-MIN, PI, PRESENT-VALUE, RANDOM, RANGE, REM, REVERSE, SECONDS-FROM-FORMATTED-TIME, SECONDS-PAST-MIDNIGHT, SIGN, SIN, SQRT, STANDARD-DEVIATION, STORED-CHAR-LENGTH, SUM, TAN, TEST-DATE-YYYYMMDD, TEST-DATE-YYYYMMDD, TRIM, UPPER-CASE, VARIANCE, WHEN-COMPILED, YEAR-TO-YYYY .. Note: More TODO here ... ABS ... Absolute value of numeric argument. DISPLAY FUNCTION ABS(DIFFERENCE). .... ACOS .... The ACOS function returns a numeric value (in radians) that approximates the arccosine of the argument. The domain of the arccosine function is -1 to +1. Domain errors return a result of 0. The inverse cosine function returns a range of 0 thru |PI|. DISPLAY FUNCTION ACOS(-1). ....... ANNUITY ....... Compute the ratio of an annuity paid based on arguments of interest and number of periods. :: WORKING-STORAGE SECTION. 77 INTEREST PIC S9V9999 VALUE 0.08. 77 MONTHLY PIC S9V9999 VALUE ZERO. 77 PERIODS PIC 99 VALUE 36. 77 ANNUITY-VALUE PIC S9V9999 VALUE ZERO. PROCEDURE DIVISION. COMPUTE MONTHLY ROUNDED = INTEREST / 12 COMPUTE ANNUITY-VALUE ROUNDED = FUNCTION ANNUITY (MONTHLY PERIODS) DISPLAY "Monthly rate: " MONTHLY " Periods: " PERIODS " Annuity ratio: " ANNUITY-VALUE END-DISPLAY. Outputs:: Monthly rate: +0.0067 Periods: 36 Annuity ratio: +0.0314 .... ASIN .... The ASIN function returns a numeric value (in radians) that approximates the arcsine of the argument. The domain of the arcsine function is -1 to +1. Domain errors return a result of 0. The inverse sine function returns a range of -|PI|/2 thru |PI|/2. DISPLAY FUNCTION ASIN(-1). .... ATAN .... The ATAN function returns a numeric value (in radians) that approximates the arctangent of the argument. The domain of the arctangent function is all real numbers. The inverse tangent function returns a range of -|PI|/2 thru |PI|/2. DISPLAY FUNCTION ATAN(1). ........... BYTE-LENGTH ........... The BYTE-LENGTH function returns an integer that is the internal storage length of the given argument. :: >>SOURCE FORMAT IS FIXED ****************************************************************** * Purpose: demonstrate intrinsic FUNCTION BYTE-LENGTH ****************************************************************** identification division. program-id. bytelength. data division. working-storage section. 01 char-var usage binary-char. 01 short-var usage binary-short. 01 long-var usage binary-long. 01 double-var usage binary-double. 01 num1-var pic 9. 01 num4-var pic 99v99. 01 num9-var pic s9(9). 01 num18-var pic s9(18). 01 num18c-var pic s9(18) usage comp. 01 num18p-var pic s9(18) usage comp-3. 01 edit-var pic $zzzz9.99. 01 string-var pic x(10) value "abc". 01 newline pic x value x'0a'. procedure division. display "num1-var len = " function byte-length(num1-var) newline "num4-var len = " function byte-length(num4-var) newline "num9-var len = " function byte-length(num9-var) newline "num18-var len = " function byte-length(num18-var) newline "num18c-var len = " function byte-length(num18c-var) newline "num18p-var len = " function byte-length(num18p-var) newline "edit-var len = " function byte-length(edit-var) newline "12 len = " function byte-length(12) newline "12.12 len = " function byte-length(12.12) newline "1234567890.123 = " function byte-length(1234567890.123) newline "string-var len = " function byte-length(string-var) newline "trim string = " function byte-length(function trim(string-var)) newline "char-var len = " function byte-length(char-var) newline "short-var len = " function byte-length(short-var) newline "long-var len = " function byte-length(long-var) newline "double-var len = " function byte-length(double-var) end-display goback. exit program. Outputs:: num1-var len = 1 num4-var len = 4 num9-var len = 9 num18-var len = 18 num18c-var len = 8 num18p-var len = 10 edit-var len = 9 12 len = 2 12.12 len = 4 1234567890.123 = 13 string-var len = 10 trim string = 00000003 char-var len = 1 short-var len = 2 long-var len = 4 double-var len = 8 .... CHAR .... The CHAR function returns a ONE character alphanumeric field whose value is the character in the current collating sequence having the ordinal position equal to the value of the integer argument. The argument must be greater than 0 and less than or equal to the number of positions in the collating sequence. Errors in the argument range return 0 (the LOW-VALUE by default). See ASCII_ or EBCDIC_ and details of the ALPHABET_ clause. DISPLAY FUNCTION CHAR(66). Would output **A** in the ASCII character set. Note this may be different than what some expect. OpenCOBOL CHAR is 1 thru 128 not 0 thru 127 as a C programmer may be used to. *And to add a little confusion, most personal computers use an extended character set, usually erroneously called ASCII with a range of 0 to 255. A more appropriate name may be ISO-8859-1 Latin 1.* See ASCII_ for more accurate details. This author is often guilty of this misnomer of the use of the term ASCII. ... COS ... The COS function returns a numeric value that approximates the cosine of the argument (in radians). The domain of the cosine function is all real numbers, with a nominal domain of 0 thru |PI| with a zero returned at |PI|/2. The cosine function returns a range of -1 thru +1. DISPLAY FUNCTION COS(1.5707963267949). ............ CURRENT-DATE ............ Returns an alphanumeric field of length 21 with the current date, time and timezone information in the form YYYYMMDDhhmmsscc\ |plusminus|\ tznn. DISPLAY FUNCTION CURRENT-DATE. Example Output:: 2008080921243796-0400 ............... DATE-OF-INTEGER ............... Converts an integer date, days on the Gregorian since December 31 1600 to YYYYMMDD form. DISPLAY DATE-OF-INTEGER(1) DISPLAY DATE-OF-INTEGER(50000) 16010101 17371123 50,000 days after December 31, 1600 being November 23rd, 1737. ................ DATE-TO-YYYYMMDD ................ Converts a two digit year date format to four digit year form using a sliding window pivot of the optional second argument. The pivot defaults to 50. The OpenCOBOL implementation of DATE-TO-YYYYMMDD also accepts an optional third argument, replacing the default century value of 1900 and is treated as the years added to the given year portion of the first argument and modified by the sliding 100 window pivot. Domain errors occur for year values less than 1600 and greater than 999,999. There is no validation of the input date. Because of the sliding window, this function is dependent on the date of evaluation. DISPLAY FUNCTION DATE-TO-YYYYMMDD(000101) DISPLAY FUNCTION DATE-TO-YYYYMMDD(500101) DISPLAY FUNCTION DATE-TO-YYYYMMDD(610101) DISPLAY FUNCTION DATE-TO-YYYYMMDD(990101) DISPLAY FUNCTION DATE-TO-YYYYMMDD(990101, 50, 1900) DISPLAY FUNCTION DATE-TO-YYYYMMDD(990101, -10, 1900) DISPLAY FUNCTION DATE-TO-YYYYMMDD(990101, 50, 2000) DISPLAY FUNCTION DATE-TO-YYYYMMDD(990101, 50, 2100) When run in August, 2008 produces:: 20000101 20500101 19610101 19990101 18990101 17990101 19990101 20990101 .............. DAY-OF-INTEGER .............. Converts a Gregorian integer date form to Julian date form (YYYDDD) based on days since December 31, 1600. Errors return 0. DISPLAY FUNCTION DAY-OF-INTEGER(97336). :: 1867182 97,336 days after 16001231 being the 182nd day of the year 1867. Canada's date of Confederation and recognized birthday. .............. DAY-TO-YYYYDDD .............. Converts a Julian 2 digit year and three digit dat integer to a four digit year form. See DATE-TO-YYYYMMDD_ for some of the details of the calculations involved. ---------------------------------------------------- Q. Can you clarify the use of FUNCTION in OpenCOBOL? ---------------------------------------------------- Yes. This information is from [Roger]_, posted to the opencobol_ forums. :: Just to clarify the use of FUNCTION. (Applies to 0.33) FUNCTION (generally speaking, there are exceptions) can be used anywhere where a source item is valid. It always results in a new temporary field. This will have the desired characteristics dependant on the parameters. eg. FUNCTION MIN (x, y, z) with x PIC 99 y PIC 9(8) COMP z PIC 9(6)V99 will result in returning a field that has at least 8 positions before the (implied) decimal point and 2 after. It does NOT ever change the contents of parameters to the function. FUNCTION's are nestable. eg. DISPLAY FUNCTION REVERSE (FUNCTION UPPER-CASE (myfield)). One clarification to the above quote was pointed out by Roger. The line:: be used anywhere where a source item is valid. should be:: be used anywhere where a sending field is valid. ---------------------------------------------------------------------- Q. What is the difference between the LENGTH verb and FUNCTION LENGTH? ---------------------------------------------------------------------- From [Roger]_:: The standard only defines FUNCTION LENGTH. The LENGTH OF phrase is an extension (from MF) --------------------------------------------------- Q. What standard CALL library does OpenCOBOL offer? --------------------------------------------------- OpenCOBOL 1.0 ships with quite a few callable features. See CALL_ Looking through the source code, you'll find the current list of service calls in:: libcob/system.def With the 1.1 pre-release of July 2008, that list included:: /* COB_SYSTEM_GEN (external name, number of parameters, internal name) */ COB_SYSTEM_GEN ("SYSTEM", 1, SYSTEM) COB_SYSTEM_GEN ("CBL_ERROR_PROC", 2, CBL_ERROR_PROC) COB_SYSTEM_GEN ("CBL_EXIT_PROC", 2, CBL_EXIT_PROC) COB_SYSTEM_GEN ("CBL_OPEN_FILE", 5, CBL_OPEN_FILE) COB_SYSTEM_GEN ("CBL_CREATE_FILE", 5, CBL_CREATE_FILE) COB_SYSTEM_GEN ("CBL_READ_FILE", 5, CBL_READ_FILE) COB_SYSTEM_GEN ("CBL_WRITE_FILE", 5, CBL_WRITE_FILE) COB_SYSTEM_GEN ("CBL_CLOSE_FILE", 1, CBL_CLOSE_FILE) COB_SYSTEM_GEN ("CBL_FLUSH_FILE", 1, CBL_FLUSH_FILE) COB_SYSTEM_GEN ("CBL_DELETE_FILE", 1, CBL_DELETE_FILE) COB_SYSTEM_GEN ("CBL_COPY_FILE", 2, CBL_COPY_FILE) COB_SYSTEM_GEN ("CBL_CHECK_FILE_EXIST", 2, CBL_CHECK_FILE_EXIST) COB_SYSTEM_GEN ("CBL_RENAME_FILE", 2, CBL_RENAME_FILE) COB_SYSTEM_GEN ("CBL_GET_CURRENT_DIR", 3, CBL_GET_CURRENT_DIR) COB_SYSTEM_GEN ("CBL_CHANGE_DIR", 1, CBL_CHANGE_DIR) COB_SYSTEM_GEN ("CBL_CREATE_DIR", 1, CBL_CREATE_DIR) COB_SYSTEM_GEN ("CBL_DELETE_DIR", 1, CBL_DELETE_DIR) COB_SYSTEM_GEN ("CBL_AND", 3, CBL_AND) COB_SYSTEM_GEN ("CBL_OR", 3, CBL_OR) COB_SYSTEM_GEN ("CBL_NOR", 3, CBL_NOR) COB_SYSTEM_GEN ("CBL_XOR", 3, CBL_XOR) COB_SYSTEM_GEN ("CBL_IMP", 3, CBL_IMP) COB_SYSTEM_GEN ("CBL_NIMP", 3, CBL_NIMP) COB_SYSTEM_GEN ("CBL_EQ", 3, CBL_EQ) COB_SYSTEM_GEN ("CBL_NOT", 2, CBL_NOT) COB_SYSTEM_GEN ("CBL_TOUPPER", 2, CBL_TOUPPER) COB_SYSTEM_GEN ("CBL_TOLOWER", 2, CBL_TOLOWER) COB_SYSTEM_GEN ("\364", 2, CBL_XF4) COB_SYSTEM_GEN ("\365", 2, CBL_XF5) COB_SYSTEM_GEN ("\221", 2, CBL_X91) COB_SYSTEM_GEN ("C$NARG", 1, cob_return_args) COB_SYSTEM_GEN ("C$PARAMSIZE", 1, cob_parameter_size) COB_SYSTEM_GEN ("C$MAKEDIR", 1, cob_acuw_mkdir) COB_SYSTEM_GEN ("C$CHDIR", 2, cob_acuw_chdir) COB_SYSTEM_GEN ("C$SLEEP", 1, cob_acuw_sleep) COB_SYSTEM_GEN ("C$COPY", 3, cob_acuw_copyfile) COB_SYSTEM_GEN ("C$FILEINFO", 2, cob_acuw_file_info) COB_SYSTEM_GEN ("C$DELETE", 2, cob_acuw_file_delete) COB_SYSTEM_GEN ("C$TOUPPER", 2, CBL_TOUPPER) COB_SYSTEM_GEN ("C$TOLOWER", 2, CBL_TOLOWER) COB_SYSTEM_GEN ("C$JUSTIFY", 1, cob_acuw_justify) COB_SYSTEM_GEN ("CBL_OC_NANOSLEEP", 1, cob_oc_nanosleep) Note the "SYSTEM". This CALL sends a command string to the shell. It acts as a wrapper to the standard C library "system" call. "SYSTEM" removes any trailing spaces from the argument and appends the null terminator required for the C library "system" call. While shell access opens yet another powerful door for the OpenCOBOL programmer, diligent delevopers will need to pay heed to cross platform issues when calling the operating system. ------------------------------------------- Q. What are the XF4, XF5, and X91 routines? ------------------------------------------- From opencobol.org_ :: The CALL's X"F4", X"F5", X"91" are from MF. You can find them in the online MF doc under Library Routines. F4/F5 are for packing/unpacking bits from/to bytes. 91 is a multi-use call. Implemented are the subfunctions get/set cobol switches (11, 12) and get number of call params (16). Roger Use :: CALL X"F4" USING BYTE-VAR ARRAY-VAR RETURNING STATUS-VAR to pack the last bit of each byte in the 8 byte ARRAY-VAR into corresponding bits of the 1 byte BYTE-VAR. The X"F5" routine takes the eight bits of byte and moves them to the corresponding occurrence within array. X"91" is a multi-function routine. :: CALL X"91" USING RESULT-VAR FUNCTION-NUM PARAMETER-VAR RETURNING STATUS-VAR As mentioned by Roger, OpenCOBOL supports FUNCTION-NUM of 11, 12 and 16. 11 and 12 get and set the on off status of the 8 (eight) run-time OpenCOBOL switches definable in the SPECIAL-NAMES_ paragraph. ------------------------------------------------------ Q. What is CBL_OC_NANOSLEEP OpenCOBOL library routine? ------------------------------------------------------ CBL_OC_NANOSLEEP allows (upto) nanosecond sleep timing. It accepts a 64 bit integer value which may be in character or numeric data forms. :: CALL "CBL_OC_NANOSLEEP" USING 500000000 RETURNING STATUS END-CALL Would wait one-half second. *It may be easier to grok if the source code uses string catenation; "500" & "000000" for example.* ---------------------------------- Q. Can I use ctags with OpenCOBOL? ---------------------------------- Yes. Use the Exuberant version of ctags. Exhuberant ctags recognizes COBOL, producing a TAGS or tags file suitable for **emacs**, **vi**, **nedit** and other editors that support the ctags format. *ctags, by default, only supports the competition, C and Fortran.* After running ctags program.cob:: $ vi -t WORKING-STORAGE will open program.cob and start at the line defining the working-storage section. Note: tags are case-sensitive and for larger projects, the above vi command would start an edit of the *first* file with an occurrence of WORKING-STORAGE found in the tags. ------------------------------------------- Q. What about debugging OpenCOBOL programs? ------------------------------------------- OpenCOBOL internal runtime checks are enabled with **-debug**. Support for tracing is enabled with **-ftrace** and **-ftraceall**. Source line location is enabled with **-fsource-location**. Activation of FIXED format **D** indicator debug lines is enabled with **-fdebugging-line**. **-fstack-check** will perform stack checking when **-debug** or **-g** is used. **-fsyntax-only** will ask the compiler to only check for syntax errors, and not emit any output. Support for gdb_ is enabled with **-g**. :: $ gdb hello GNU gdb 6.7.1-debian Copyright (C) 2007 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "i486-linux-gnu"... Using host libthread_db library "/lib/i686/cmov/libthread_db.so.1". (gdb) break 106 Breakpoint 1 at 0xOBFUSCA: file hello.c, line 106. (gdb) break 109 Breakpoint 2 at 0xTETHESY: file hello.c, line 109. (gdb) run Starting program: /home/brian/writing/cobol/hello [Thread debugging using libthread_db enabled] [New Thread 0xSTEMADDR (LWP 5782)] [Switching to Thread 0xESSES6b0 (LWP 5782)] Breakpoint 1, hello_ (entry=0) at hello.c:106 106 cob_new_display (0, 1, 1, &c_1); (gdb) cont Continuing. Hello World! Breakpoint 2, hello_ (entry=0) at hello.c:109 109 cob_set_location ("hello", "hello.cob", 6, "MAIN SECTION", "MAIN PARAGRAPH", "STOP"); (gdb) cont Continuing. Program exited normally. (gdb) Setting a break at line 106 and 109 was found by a quick look through the C code from **$ cobc -C hello.cob** and seeing where the DISPLAY call and STOP RUN was located. Note: just because; the gdb displayed addresses were obfuscated from this listing. --------------------------------------- Q. Is there a C interface to OpenCOBOL? --------------------------------------- Most definitely. See http://www.opencobol.org/modules/bwiki/index.php?cmd=read&page=UserManual%2F2_3#content_1_0 for details. ---------------------------------------------------------------------- Q. What are some idioms for dealing with C char * data from OpenCOBOL? ---------------------------------------------------------------------- *Thanks to Frank Swarbrick for pointing these idioms out* To add or remove a null terminator, use the STRING verb. For example:: * Add a null for calling C STRING current-url DELIMITED BY SPACE X"00" DELIMITED BY SIZE INTO display-url MOVE display-url TO current-url * Remove a null for display STRING current-url DELIMITED BY LOW-VALUE INTO display-url. Or to make changes in place:: * Change nulls to spaces INSPECT current-url REPLACING ALL X"00" WITH SPACE. Or there is also modified references in OpenCOBOL:: * Assume IND is the first trailing space (or picture limit). * Note: OpenCOBOL auto initializes working-storage to SPACES or ZEROES * depending on numeric or non-numeric pictures. * Remove null MOVE SPACE TO current-url(IND:1). * Add a zero terminator MOVE X"00" TO current-url(IND:1). [Roger]_ While points out: *X"00" is almost always interchangeable with LOW-VALUE*. In all of the above snippets, the source code X"00" can be replaced by the COBOL noun **LOW-VALUE** or *LOW-VALUES*. *Except when a program collating sequence is active and where the first character is not X"00"*. .. Note to maintainers. The section below is just wrong. BASED is a different thing altogether and simply means the item does not have any permanent storage area. Entry commented out until corrected. .. When a parameter needs to be passed between C and OpenCOBOL, you can use .. the BASED optional clause in WORKING-STORAGE:: .. .. * Create a BASED allocation .. WORKING-STORAGE SECTION. .. 01 current-url PIC X(80) BASED. .. .. This may be a cleaner solution than:: .. .. LINKAGE SECTION. .. 01 current-url PIC X(80). .. .. And a SET ADDRESS OF CARG ... sequence. With the CALL verb, use ADDRESS OF and/or BY REFERENCE:: CALL "CFUNCTION" USING BY REFERENCE ADDRESS OF current-url. The above being equivalent to char** in C. COBOL, by it's nature, passes all arguments by reference. That can be overridden with the **BY VALUE** clause and the **BY CONTENT** clause. --------------------- Q. What is CobCurses? --------------------- CobCurses is a package designed to allow Open-Cobol programmers to create screens on open system platforms, or those (like Windows) that can use PDCurses. Since handcrafting screens can be tedious work, this package includes a "Screen Designer" utility. See http://sourceforge.net/projects/cobcurses for full details. This is a major piece of work by Warren Gay, ve3wwg. ---------------------------------------- Q. Does OpenCOBOL support COPY includes? ---------------------------------------- Yes. COPY is fully supported, all variations from the standards up to and including the proposed 2008 standards. The **-I** compiler option influences the copybook search path and **-E** can be used to examine the *after* COPY preprocessor output. There is also **-ffold-copy-upper** and **-ffold-copy-lower** compiler controls. ---------------------------------------- Q. Does OpenCOBOL support WHEN-COMPILED? ---------------------------------------- Both as a noun and as an intrinsic function. :: DISPLAY WHEN-COMPILED. DISPLAY FUNCTION WHEN-COMPILED. 07/05/0805.15.20 2008070505152000-0400 Note: The noun WHEN-COMPILED is non-standard and was deemed obsolete in the pre 85 standard. --------------------------- Q. What is PI in OpenCOBOL? --------------------------- With OpenCOBOL 1.1:: DISPLAY FUNCTION PI. 3.1415926535897932384626433832795029 DISPLAY FUNCTION E. 2.7182818284590452353602874713526625 Thats 34 digits after the decimal. Developers that need to know the tolerances for use in calculations are directed to poke around the freely available source code, and to read up on GMP_. ------------------------------------------------------------------- Q. Does OpenCOBOL support the Object features of the 2002 standard? ------------------------------------------------------------------- Not yet. *July 2008* --------------------------------------- Q. Does OpenCOBOL implement PICTURE 78? --------------------------------------- Yes. PICTURE 78 clauses can be used for constants, translated at compile time. This common non-standard extension is supported in OpenCOBOL. -------------------------------------- Q. Does OpenCOBOL implement CONSTANT? -------------------------------------- Current OC 1.1 has preliminary support for a subset of the standard conforming "CONSTANT" phrase. eg:: 01  MYCONST CONSTANT AS 1. Note: there is a syntax difference between 78 and CONSTANT. ------------------------------------------------- Q. What source formats are accepted by OpenCOBOL? ------------------------------------------------- Both FIXED and FREE COBOL source formats are supported. FIXED format follows the 1-6, 7, 8-72 special columns of the COBOL standards. The compiler directives: :: Column 12345678901234567890 >>SOURCE FORMAT IS FREE >>SOURCE FORMAT IS FIXED can be used. The directive must occur at column 8 or beyond if the ACTIVE scan format is FIXED. As per the 2002 standard this directive can be used to switch formats multiple times within a compilation unit. Continuation indicators in column 7 are not applicable to FREE format and are not supported in this mode of translation. String catenation can always be used; the **&** operator. The special \*> *till end of line* comment is supported in both FREE and FIXED forms, but by necessity will need to be placed at column 7 or greater in FIXED format sources. .. Note to readers. The comment operator is *> the backslash is for ReST The **-free** and **-fixed** options to **cobc** also influence the expected source formats, with the default being mandated by the standards as FIXED. --------------------------------------------- Q. Does OpenCOBOL support continuation lines? --------------------------------------------- Yes. A dash **-** in column 7 can be used for continuation lines. But, by necessity continuation lines only apply in FIXED format source code. FREE format COBOL does not support continuation as there is no real meaning to *column 7* in FREE form source. Note that in this example there is no terminating quote on the string continuations, but there is an extra starting quote following the dash:: 123456789012345678901234567890123456789012345678901234567890123456789012 identification division. program-id. longcont. data division. working-storage section. 01 longstr pic X(80) value "This will all be one string in FIXED forma -"t source code". 01 otherstr pic X(148) value "this -"string will have spaces between the words THIS and STRING, as -"continuation lines always fill to column 72.". procedure division. display longstr. display length longstr. display function length(function trim(longstr trailing)). display otherstr(1:72). display otherstr(73:75). display length otherstr. display function length(function trim(otherstr trailing)). goback. $ cobc longcont.cob $ cobcrun longcont This will all be one string in FIXED format source code 80 00000055 this string will have spaces between the words THIS and STRING, as continuation lines always fill to column 72. 148 00000139 *Note: The DISPLAY of* **otherstr** *was split to avoid any wide browser scrolling, not for any COBOL reasons.* *Also note that the rules for continuation lines are quite difficult to describe simply and concerned OpenCOBOL programmers are urged to read through the standards documents for full details.* ----------------------------------------------- Q. Does OpenCOBOL support string concatenation? ----------------------------------------------- Absolutely. Sources that need long strings, or those wishing to enhance source code readability, can use the **&** operator:: identification division. program-id. longstr. data division. working-storage section. 01 longstr pic X(80) value "This " & "will " & "all " & "be " & "one " & "string " & "in both FIXED and FREE" & " format source code". procedure division. display longstr. goback. Run this with:: $ cobc longstr.cob $ cobcrun longstr This will all be one string in both FIXED and FREE format source code $ cobc -free longstr.cob $ cobcrun longstr This will all be one string in both FIXED and FREE format source code -------------------------------------------------- Q. Does OpenCOBOL support D indicator debug lines? -------------------------------------------------- Yes, but only for FIXED FORMAT sources. As for continuation lines, column 7 has no meaning for SOURCE FORMAT IS FREE source code. Use **D** lines as a conditional include of a source code line. These debug lines will only be compiled if the *-fdebugging-line* compiler switch is used. From human on opencobol.org_ :: If you put a D in column 7 OC handles this as a comment. These lines are only compiled if you run cobc with -fdebugging-line. By using this you can put some test messages etc. into your program that are only used if necessary (and therefore build with -fdebugging-line). ------------------------------------------------- Q. Does OpenCOBOL support mixed case source code? ------------------------------------------------- Absolutely, kind of. Mixed case and mixed format, ASCII_ and EBCDIC_. Most COBOL compilers have not required uppercase only source code for quite a few years now. Still, most COBOL compilers including OpenCOBOL folds parts of the source to uppercase *with certain rules* before translating. The compiler is case insensitive to names:: 000100 identification division. 000200 program-id. mixcase. 000300 data division. 000400 working-storage section. 000500 01 SOMEUPPER pic x(9). 000600 01 SomeUpper pic x(9). 000700 01 someupper pic x(9). 000800 000900 procedure division. 001000 move "SOMEUPPER" to SOMEUPPER. 001100 move "SomeUpper" to SomeUpper. 001200 move "someupper" to someupper. 001300 display "SOMEUPPER: " SOMEUPPER end-display. 001400 display "SomeUpper: " SomeUpper end-display. 001500 display "someupper: " someupper end-display. 001600 stop run. $ cobc -x mixcase.cob mixcase.cob:10: Error: 'SOMEUPPER' ambiguous; need qualification mixcase.cob:5: Error: 'SOMEUPPER' defined here mixcase.cob:6: Error: 'SOMEUPPER' defined here mixcase.cob:7: Error: 'SOMEUPPER' defined here Note; that although the folded declarations conflict, the DISPLAY quoted strings will NOT be folded, and would display as expected. *Case sensitivity is also at the mercy of operating system conventions*. Under GNU/Linux, OpenCOBOL's dynamic link loader is case sensitive. :: CALL "C$JUSTIFY" USING center-string "C" END-CALL. is not the same as:: CALL "c$justify" USING center-string "C" END-CALL. In support of case folding and COPY libraries, OpenCOBOL supports *-ffold-copy-lower* and *-ffold-copy-upper*. For mixing and matching legacy sources. Trivia The expressions *uppercase* and *lowercase* date back to early moveable type. Typographers would keep two cases of metal casted letters, Capitalized and normal. Usually set on stacked shelves over the workbench. The small letters, being used more frequently, ended up on the lower shelf; the lower case letters. ------------------------------------------ Q. What is the shortest OpenCOBOL program? ------------------------------------------ All that is needed is a program-id. Doesn't do much. :: program-id. a. ------------------------------------------------------------------------- Q. How do I get those nifty sequential sequence numbers in a source file? ------------------------------------------------------------------------- FIXED format COBOL uses the first 6 positions of each line as a programmer defined **sequence** field. This field is stripped as part of the preprocessing and is not validated. Historically, the sequence numbers were used to verify that card punch cards were read into a card reader in the proper order. Many legacy COBOL programs have sequentially numbered sequence values. Here is a little **vi** trick to renumber the sequence field by 100s. Given :: 000005* HELLO.COB OpenCOBOL FAQ example 000010 IDENTIFICATION DIVISION. 000020 PROGRAM-ID. hello. 000030 PROCEDURE DIVISION. 000040 DISPLAY "Hello World!". 000100 STOP RUN. Running the following **ex** filter :%!perl -ne 'printf("\\%06d\\%s\\n", $. * 100, substr($_, 6, -1));' .. Note to readers of the plain text of this FAQ. ReStructuredText uses backslash to escape certain features. That line is actually :%!perl -ne 'printf("\%06d\%s\n", $. * 100, substr($_, 6, -1));' produces a nicely resequenced source file. :: 000100* HELLO.COB OpenCOBOL FAQ example 000200 IDENTIFICATION DIVISION. 000300 PROGRAM-ID. hello. 000400 PROCEDURE DIVISION. 000500 DISPLAY "Hello World!". 000600 STOP RUN. * Note: Only use this on already FIXED form source. If used on any FREE format COBOL, the first 6 columns will be damaged. This has no effect on the compilation process, it only effects the appearance of the sources. --------------------------------------------------------- Q. What is the shortest Hello World program in OpenCOBOL? --------------------------------------------------------- A short version of OpenCOBOL hello world, compiled -free:: program-id.hello.procedure division.display "Hello World!". Thanks to human and the opencobol.org_ forums. -------------------------------------------------------------------------- Q. Is there a way to count trailing spaces in data fields using OpenCOBOL? -------------------------------------------------------------------------- Yes. Quite a few. But instead of resorting to a PERFORM VARYING sequence try:: 01 B-COUNT PIC 999 VALUE 0. 01 TEST-CASE PIC X(80) VALUE "This is my string.". ONE-WAY. INSPECT FUNCTION REVERSE(TEST-CASE) TALLYING B-COUNT FOR LEADING ' '. DISPLAY B-COUNT. TWO-WAY. INSPECT TEST-CASE TALLYING B-COUNT FOR TRAILING SPACE. DISPLAY B-COUNT. THREE-WAY. IF TEST-CASE EQUAL SPACES COMPUTE B-COUNT = LENGTH OF TEST-CASE ELSE COMPUTE B-COUNT = LENGTH TEST-CASE - FUNCTION LENGTH(FUNCTION TRIM(TEST-CASE TRAILING)) END-COMPUTE END-IF DISPLAY B-COUNT. produces:: 062 124 062 The second value is 124 as TWO-WAY accumulates another 62 after ONE-WAY. The INSPECT verb does not initialize a TALLYING variable. Information modified from opencobol.org_ forum post. ===== Notes ===== .. These are the internal, non question information nodes. ---- CALL ---- The OpenCOBOL CALL verb accepts literal or identifier stored names when resolving the transfer address. The USING phrase allows argument passing and OpenCOBOL includes internal rules for the data representation of the call stack entities that depend on the COBOL PICTURE_ and USAGE_ clauses. Return values are captured with RETURNING identifier. See `Q. What standard CALL library does OpenCOBOL offer?`_. For more information see http://www.opencobol.org/modules/bwiki/index.php?cmd=read&page=UserManual%2F2_3#content_1_0 ------------- SPECIAL-NAMES ------------- OpenCOBOL supports a fair complete set of the SPECIAL-NAMES in common use. ------- PICTURE ------- Full standards support of all alpha, alphanumeric and numeric storage specifiers as well as full support for edit and numeric-edit clauses. ----- USAGE ----- OpenCOBOL uses standard big-endian_ internal storage by default. USAGE clauses influence the data representation. The INTEL architecture uses little-endian_ form and OpenCOBOL programmers developing for this common chipset may need to pay heed to this for performance purposes. As per the standards, OpenCOBOL supports COMPUTATIONAL-5 native usage. OpenCOBOL enables use of one to eight byte binary representations in both big and little endian forms. Along with full support of all common COBOL_ PICTURE_ clauses both storage and display, OpenCOBOL supports USAGE clauses of: * BINARY * COMPUTATIONAL, COMP * COMP-1 * COMP-2 * COMP-3 * COMP-4 * COMP-5 * COMP-X * DISPLAY * INDEX * PACKED-DECIMAL * POINTER * PROGRAM-POINTER * SIGNED-SHORT * SIGNED-INT * SIGNED-LONG * UNSIGNED-SHORT * UNSIGNED-INT * UNSIGNED-LONG * BINARY-CHAR SIGNED * BINARY-CHAR UNSIGNED * BINARY-CHAR * BINARY-SHORT SIGNED * BINARY-SHORT UNSIGNED * BINARY-SHORT * BINARY-LONG SIGNED * BINARY-LONG UNSIGNED * BINARY-LONG * BINARY-DOUBLE SIGNED * BINARY-DOUBLE UNSIGNED * BINARY-DOUBLE * BINARY-C-LONG SIGNED * BINARY-C-LONG UNSIGNED * BINARY-C-LONG -------------- LINAGE-COUNTER -------------- An internal OpenCOBOL noun, or *Special Register*. Value is readonly and is maintained during WRITEs to files that have a LINAGE clause. Useful for quick reports and logical page layouts. ---------- big-endian ---------- Binary values stored with the most significant byte at the lowest memory address. **Big End First**. See http://en.wikipedia.org/wiki/Endianness for more details. The OpenCOBOL compiler *default* storage format for USAGE_ BINARY and COMP. ------------- little-endian ------------- Binary values stored with the most significant byte at the highest memory address. **Little End First**. http://en.wikipedia.org/wiki/Endianness for more details. This is the common Intel architecture form, and USAGE_ clauses of COMPUTATIONAL-5, BINARY-CHAR, BINARY-SHORT, BINARY-LONG, BINARY-DOUBLE are a true performance boost on this hardware. See http://www.opencobol.org/modules/bwiki/index.php?cmd=read&page=UserManual%2F4#content_1_0 for some details. ------ EBCDIC ------ Extended Binary Coded Decimal Interchange Code. A character encoding common to mainframe systems, therefore COBOL, therefore OpenCOBOL. Different than ASCII_ and OpenCOBOL supports both through efficient mappings. See http://en.wikipedia.org/wiki/EBCDIC for more info. ----- ASCII ----- American Symbolic Code for Information Interchange. The character encoding common to personal computers and the Internet Age, therefore OpenCOBOL. OpenCOBOL also supports the EBCDIC_ character encoding so some data transfers and keyboard handling or console display programs may need programmer attention to detail. Although this is a rare case as OpenCOBOL operates using an intelligent choice of encoding for each platform build. See http://en.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange for more info. .. Attention:: Unicode? -------- ALPHABET -------- .. Attention:: Look into this --- DSO --- Dynamic Shared Objects. Similar to but subtlely different from *share libraries*. --- gdb --- The GNU symbolic debugger. Big, deep, wide. :: $ info gdb for the details. or visit http://www.gnu.org/software/gdb/documentation/ --- GMP --- GNU MP libgmp. GNU Library for decimal arithmetic. See http://gmplib.org/ for complete details on the library advertised as *Arithmetic without limitations*. ======= Authors ======= .. [Keisuke] Keisuke Nishida Initial developer and creator of OpenCOBOL. |KeisukeActive| was the primary developer and OpenCOBOL project lead. His efforts are greatly appreciated by the userbase of OpenCOBOL. .. [Roger] Roger While OpenCOBOL 1.1 is |currently| in development, and Roger is the lead programmer. |RogerActive|, Roger has been very active on the opencobol.org_ website, and is open to feature requests and clarifications to the implementation. Roger has, since January 2008, actively monitored an OpenCOBOL 1.1 wishlist on the opencobol.org_ OpenCOBOL forum. =========== Maintainers =========== .. [btiffin] Brian Tiffin Initial FAQ, sample programs for OpenCOBOL 1.1. .. [aoirthoir] Joseph James Frantz Hosting, support. ========= Changelog ========= 02-July-2008 Experimental version for commnent 06-July-2008 First 0.0 pre-alpha release 07-July-2008 Second 0.0 pre-alpha. 11-July-2008 Last 0.0 pre-alpha. Checked in for diffs. 13-July-2008 Last-last 0.0 pre-alpha. Verify DIFF functionality. 17-July-2008 Last-last-last 0.0 pre-alpha. Second DIFF. 20-July-2008 Corrections pass. 24-July-2008 Expanded the SCREEN SECTION questions. 28-July-2008 Another correction pass, with clarifications from Roger While 10-Aug-2008 Started in on the intrinsic functions. Dropped the pre from the alpha designation. Still some Look into this entries. 21-Aug-2008 Move to add1tocobol.com .. These are the external link substitutions. .. _OpenCOBOL: http://opencobol.org/ .. _opencobol.org: http://opencobol.org/ .. _`OpenCOBOL 1.0`: http://opencobol.org/modules/mydownloads/singlefile.php?cid=1&lid=3 .. _`OpenCOBOL 1.1`: http://www.opencobol.org/modules/mydownloads/singlefile.php?cid=1&lid=2 .. _COBOL: http://en.wikipedia.org/wiki/COBOL .. _`COBOL 85`: http://www.cobolstandards.com/ .. _`COBOL 2002`: http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=28805 .. _`COBOL FAQ`: http://home.comcast.net/~wmklein/FAQ/COBOLFAQ.htm .. _COBUG: http://www.cobug.com/ .. _`OpenCOBOL Install`: http://www.opencobol.org/modules/bwiki/index.php?InstallGuide .. _`OpenCOBOL Wiki`: http://www.opencobol.org/modules/bwiki/ .. _`OpenCOBOL Forum`: http://www.opencobol.org/modules/newbb/ .. _`OpenCOBOL News`: http://www.opencobol.org/modules/news/ .. _`GNU General Public License`: http://www.gnu.org/licenses/gpl.html .. _`GNU Lesser General Public License`: http://www.gnu.org/licenses/lgpl.html .. _TinyCOBOL: http://tiny-cobol.sourceforge.net/index.php .. This section holds replacements and special symbols. .. |copysym| unicode:: 0xA9 .. |copyleft| replace:: Copyright |copysym| 2008 The OpenCOBOL Project .. |PI| unicode:: 0x03C0 .. |plusminus| unicode:: 0xB1 .. |currently| replace:: currently *(August 2008)* .. |KeisukeActive| replace:: From the 1990s through 2004 .. |RogerActive| replace:: From early 2004 up till today, and tomorrow