GnuCOBOL
GnuCOBOL Programmer’s Guide
1. Introduction
This document describes the syntax, semantics and use of the COBOL programming language as implemented by GnuCOBOL, formerly known as OpenCOBOL.
The original principal developers of GnuCOBOL were Keisuke Nishida and Roger While. Since then, many members of the community have been involved in its development.
This document is intended to serve as a fully functional reference and user’s guide, suitable for both those readers learning COBOL for the first time as a training tool, as well as those already familiar with another dialect of COBOL.
A separate manual — containing only the details of the GnuCOBOL implementation and designed for experienced COBOL programmers — has been taken from this guide. That document (GnuCOBOL Quick Reference) contains no training subject matter.
Other documents that should be read is the gnucobol.pdf found in the doc directory of the compiler sources and the file NEWS supplied with the source code of the GnuCOBOL compiler, in the top-level directory. There you will find the latest COBOL language features that have been added, some of which may not be in this document due to time constraints. If you find any, please report it as a bug for the Programmer’s Guide so that it can be fixed.
Yet another document which delves deeper in to the compiler that is a must read, is the FAQ available via the GnuCOBOL Manuals and Guides, although it could do with a wee clean up to ease reading and finding required information.
1.1. Additional Reference Sources
For those wishing to learn COBOL for the first time, Gary can strongly recommend the following resources.
If you like to hold a book in your hands, I strongly recommend Murach’s Structured COBOL, by Mike Murach, Anne Prince and Raul Menendez (2000) - ISBN 9781890774059. Mike Murach and his various writing partners have been writing outstanding COBOL textbooks for decades. It’s an excellent book for those familiar with the concepts of programming in other languages, but unfamiliar with COBOL.
Would you prefer a web-based tutorial? Try the University of Limerick (Ireland) - COBOL web site.
In addition there is the GnuCOBOL FAQ — which has now exceeded 1,400 pages — available as HTML or a downloadable .pdf file.
Along with every release of the compiler sources is the file NEWS. It contains up to the minute updates regarding the compiler and additional COBOL language elements which may well not be yet included in this manual.
1.2. Introducing COBOL
If you already know a programming language other than COBOL, chances are that language is Java, C or C++. You will find COBOL much different from those; sometimes the differences are a good thing and sometimes they aren’t. The thing to remember about COBOL is this: it was designed to solve business problems.
COBOL, first introduced to the programming public in 1959, was the very first programming language to become standardized (in 1960). This meant that a standard-compliant COBOL program written on computer “A” made by company “B” would be able to be compiled and executed on computer “X” made by company “Y” with very few, if any, changes. This may not seem like such a big deal today, but it was a radical departure from all programming languages that came before it and even many that came after it.
The name COBOL actually says it all — COBOL is an acronym that stands for “(CO)mmon (B)usiness (O)riented (L)anguage”. Note the fact that the word “common” comes before all others. The word “business” is a close second. Therein lies the key to COBOL’s success.
1.2.1. Why YOU Should Learn COBOL
Despite statements from industry “insiders”, the COBOL programming language is not dead, even though newer and so-called “modern” languages like Java, C#, .NET, Ruby on Rails and so on appear to have become the languages of choice in the Information Technology world. These languages have become popular because they address the following desired requirements for “modern” programming:
Just because COBOL doesn’t traditionally support objects, classes, and the like doesn’t mean that its “procedural” approach to computing isn’t valuable — after all, it runs 70% of the worlds business transactions, and does so:
- Using programs that, for the most part, are much more self-documenting than would be the case with any other programming language.
- Effortlessly providing arithmetic accuracy to 31 digits, with performance approaching that of well-written assembly-language programs. Don’t think this isn’t critically important to banks, investment houses and any business interested in tracking revenues, expenses and profits (duh - like ALL of them).
- Integrating well with non-COBOL infrastructures such as XML, SOA, MQ, almost any DBMS, Transaction Processing platforms, Queue-Management facilities and other programming languages.
- By running on almost as many different computing platforms as Java can. You can’t run COBOL programs in your smart phone, but desktops, workstations, midframes/servers, mainframes and supercomputers are all fair game.
Today’s IT managers and business leaders are faced with a challenging dilemma — how do you maintain the enormous COBOL code base that is still running their businesses when academia has all but abandoned the language they need their people to use to keep the wheels rolling? The problem is compounded by the fact that those programmers that are skilled in COBOL are retiring and taking their knowledge with them. In some markets, this appears to be having an inflationary effect on the cost of resources (COBOL programmers) whose supply is becoming smaller and smaller. The pressure to update applications to make use of more up-to-date graphical user interfaces is also perceived as a reason to abandon COBOL in favour of GUI-friendly languages such as Java.
Businesses are addressing the COBOL challenge in different ways:
- By undertaking so-called “modernization projects”, where existing applications are either rewritten in “modern” languages or replaced outright with purchased packages. Most of these businesses are using such activities as an excuse to abandon “expensive” mainframes in favour of (presumably) less-expensive “open systems” (mid frame/server) solutions.
- Many times these businesses are finding the cost of the system/networking engineering, operational management and monitoring and risk management (i.e. disaster recovery) infrastructures necessary to support truly mission-critical applications to be so high that the “less-expensive” solution really isn’t; in these cases the mainframe may remain the best option, thus leaving COBOL in play and businesses seeking another solution for at least part of their application base.
- Training their own COBOL programmers. Since colleges, universities and technical schools have lost interest in doing so, many businesses have undertaken the task of “growing their own” new crop of COBOL programmers. Fear of being pigeon-holed into a niche technology is a factor inhibiting many of today’s programmers from willingly volunteering for such training.
- By moving the user-interface onto the desktop; such efforts involve running modern-language front-end clients on user desktops (or laptops or smart phones, etc.) with COBOL programs providing server functionality on mainframe or midframe platforms, providing all the database and file “heavy lifting” on the back-end. Solutions like this provide users with the user-interfaces they want/need while still leveraging COBOL’s strengths on (possibly) downsized legacy mainframe or midframe systems.
It’s probably a true that an IT professional can no longer afford to allow COBOL to be the only wrench in their toolbox, but with a massive code base still in production now and for the foreseeable future, adding COBOL to a multi-lingual curriculum vitae (CV) and/or resume (yes — they ARE different) is not a bad thing at all. Knowing COBOL as well as the language du-jour will make you the smartest person in the room when the discussion of migrating the current “legacy” environment to a “modern” implementation comes around.
You’ll find COBOL an easy language to learn and a FAR EASIER language to master than many of the “modern” languages.
The whole reason you’re reading this is that you’ve discovered GnuCOBOL — another implementation of COBOL in addition to those mentioned earlier. The distinguishing characteristic of GnuCOBOL versus those others is that GnuCOBOL is FREE open-source and therefore FREE to obtain and use. It is community-enhanced and community-supported. Later in this document (see So What is GnuCOBOL?), you’ll begin to learn more about this COBOL implementation’s capabilities.
1.2.2. Programmer Productivity
Throughout the history of computer programming, the search for new ways to improve of the productivity of programmers has been a major consideration. Other than hobbyists, programming is an activity performed for money, and businesses abhor spending anything more than is absolutely necessary; even government agencies try to spend as little money on projects as is absolutely necessary.
The amount of programming necessary to accomplish a given task — including rework needed by any errors found during testing (testing is sometimes jokingly defined as: that time during which an application is actually in production, allowing users to discover the problems) is the measure of programmer productivity. Anything that reduces that effort will therefore reduce the time spent in such activities therefore reducing the expense of same. When the expense of programming is reduced, programmer productivity is increased.
Sometimes the quest for improved programmer productivity (and therefore reduced programming expense) has taken the form of introducing new features in programming languages, or even new languages altogether. Sometimes it has resulted in new ways of using the existing languages.
While many technological and procedural developments have made evolutionary improvements to programmer productivity, each of the following three events has been responsible for revolutionary improvements:
- The development of so-called “higher-level” programming languages that enable a programmer to specify in a single statement of the language an action that would have required many more separate statements in a prior programming language. The standardization of such languages, making them usable on a wide variety of computers and operating systems, was a key aspect of this development. COBOL was a pioneering development in this area, being a direct descendant of the very first higher-level language (FLOW-MATIC, developed by US Naval Lieutenant Grace Hopper) and the first to become standardized.
- The establishment of programming techniques that make programs easier to read and therefore easier to understand. Not only do such techniques reduce the amount of rework necessary simply to make a program work as designed, but they also reduce the amount of time a programmer needs to study an existing program in order how to best adapt it to changing business requirements. The foremost development in this area was structured programming. Introduced in the late 1970’s, this approach to programming spawned new programming languages (PASCAL, ALGOL, PL/1 and so forth) designed around it. With the ANSI 85 standard, COBOL embraced the principles espoused by structured programming mavens as well as any of the languages designed strictly around it.
- The establishment of programming techniques AND the introduction of programming language capabilities to facilitate the re-usability of program code. Anything that supports code re-usability can have a profound impact to the amount of time it takes to develop new applications or to make significant changes to existing ones. In recent years, object-oriented programming (OOP) has been the industry “poster child” for code re-usability. By enabling program logic and the data structures that logic manipulates to be encapsulated into easily stored and retrieved (and therefore “reusable”) modules called classes, the object-oriented languages such as Java, C++ and C# have become the favourites of academia. Since students are being trained in these languages and only these, by and large, it’s no surprise that — today — object-oriented programming languages are the darlings of the industry.
The reality is, however, that good programmers have been practising code re-usability for more than a half-century. Up until recently, COBOL programmers have had some of the best code re-usability tools available — they’ve been doing it with copybooks and subprograms rather than classes, methods and attributes but the net results have been similar. With the COBOL2002 and the COBOL 2014 standards, the COBOL programming language has become just as “object-oriented” as the “modern” languages, while preserving the ability to support, modify, compile and execute “legacy” COBOL programs as well.
While GnuCOBOL supports few of the OOP programming constructs defined by the COBOL2002 and COBOL2014 standards, it supports every aspect of the ANSI 85 standard and therefore fully meets the needs of points #1 and #2, above. With its supported feature set (see So What is GnuCOBOL?), it provides significant programmer productivity capabilities.
1.3. So What is GnuCOBOL?
GnuCOBOL is a free and open sourced COBOL compiler and runtime environment, written using the C programming language. GnuCOBOL is typically distributed in source-code form, and must then be built for your computer’s operating system using the system’s C compiler and loader. While originally developed for the UNIX and Linux operating systems, GnuCOBOL has also been successfully built for computers running OSX and Windows utilizing the UNIX-emulation features of such tools as Cygwin and MinGW. Also see the GNU website for more information at.
The MinGW approach is a personal favourite with the author of this manual because it creates a GnuCOBOL compiler and runtime library that require only a single MinGW DLL to be available for the GnuCOBOL compiler, runtime library and user programs. That DLL is freely distributable under the terms of the GNU General Public License. A MinGW build of GnuCOBOL fits easily on and runs from a 128MB flash drive with no need to install any software onto the Windows computer that will be using it. Some functionality of the language, dealing with the sharing of files between concurrently executing GnuCOBOL programs and record locking on certain types of files, is sacrificed however as the underlying operating system routines needed to implement them aren’t available to Windows and aren’t provided by MinGW. The current version for MinGW is available at the download link along with various other platforms at the GnuCOBOL download website.
GnuCOBOL has also been built as a truly native Windows application utilizing Microsoft’s freely-downloadable Visual Studio Express package to provide the C compiler and linker/loader. This approach does not lend itself well to a “portable” distribution.
The GnuCOBOL compiler generates C code from your COBOL programs; that C code is then automatically compiled and linked using your system’s C compiler (typically, but not limited to, gcc
).
GnuCOBOL fully supports much of the ANSI 85 standard for COBOL (the only major exclusion is the Communications Module) and also supports some of the components of the COBOL2002 and COBOL2014 standards, such as the SCREEN SECTION
(see SCREEN SECTION), table-based SORT
(see Table SORT) and user-defined functions. There are others with more being added almost weekly.
2. COBOL Fundamentals
This chapter describes the syntax, semantics and usage of the COBOL programming language as implemented by the current version of GnuCOBOL. For the rest of this document the Language is spelt as COBOL to ease reading however the compiler name retains the mixed case of GnuCOBOL.
This document is intended to serve as a full-function reference and user’s guide suitable for both those readers learning COBOL for the first time as usage as a training tool, as well as those already familiar with some dialects of the COBOL language.
A separate manual exists that just contains the details of the Cobol grammar as implemented in GnuCOBOL, which is designed strictly for experienced COBOL programmers and this is taken from this guide. This does NOT contain any training subject matter.
These extra manuals are: GnuCOBOL Quick Reference containing just the COBOL semantics / grammar in a short document while the other, GnuCOBOL Sample Programs, shows detailed example Cobol programs with indication of syntax used in each program.
For each implementation of the GnuCOBOL compiler the supplied files NEWS should also be read for any last minute updates along with files README and INSTALL for building the compiler.
2.1. The COBOL Language - The Basics
2.1.1. Language Reserved Words
Cobol programs consist of a sequence of words and symbols. Words, which consist of sequences of letters (upper- and/or lower-case), digits, dashes (‘-’) and/or underscores (‘_’) may have a pre-defined, specific, meaning to the compiler or may be invented by the programmer for his/her purposes.
The GnuCOBOL language specification defines over 1130 Reserved Words — words to which the compiler assigns a special meaning. This list and number applies to the default list which covers many implementations and that it is possible to limit the list to either a specific implementation via -std=xyz[-strict] or to manually unreserve words if they are used in existing sources as user-defined words.
Programmers may use a reserved word as part of a word they are creating themselves, but may not create their own word as an exact duplicate (without regard to case) of a COBOL reserved word. Note that a reserved word includes all classes, such as intrinsic functions, mnemonics names, system routines and reserved words. The list of reserved words can be changed by adding or removing specific words for a given compile or as a default by use of the steering command -std and -conf. See the specific config files that are by default, held in /usr/local/share/gnucobol/config. Also using the option ‘FUNCTION ALL INTRINSIC’, will add another 100+ reserved words. These can be modified to match the requirements of a business or project team but be warned that these are updated when a new version of the compiler is built so might be more prudent to create your own configuation based on an existing one but with a different name.
In addition, you can add and/or remove reserved words by adding one of these options to cobc to add -freserved-words=value or -freserved=word or, to remove, -fnot-reserved=word. As well as -freserved=word:alias to create an alias for a word as well as -fnot-register=word or -fregister=word to remove or add, a special register word.
See Appendix B - Reserved Word List, for a complete list of GnuCOBOL reserved words .
For any given version of GnuCOBOL you can also list the full current set of reserved words by running cobc with --list-reserved, --list-intrinsic, --list-system as well as --list-mnemonics. Again subject to variation depending on usage of the --std line command.
2.1.2. User-Defined Words
When you write GnuCOBOL programs, you’ll need to create a variety of words to represent various aspects of the program, the program’s data and the external environment in which the program will run. This will include internal names by which data files will be referenced, data item names and names of executable logic procedures.
User-defined words may be composed from the characters ‘A’ through ‘Z’ (upper- and/or lower-case), ‘0’ through ‘9’, dash (‘-’) and underscore (‘_’). User-defined words may neither start nor end with hyphen or underscore characters.
Other programming languages provide the programmer with a similar capability of creating their own words (names) for parts of a program; COBOL is somewhat unusual when compared to other languages in that user-defined words may start with a digit.
With the exception of logic procedure names, which may consist entirely of nothing but digits, user-defined words must contain at least one letter.
2.1.3. Case Insensitivity
All COBOL implementations allow the use of both upper and lower case letters in program coding. GnuCOBOL is completely insensitive to the case used when writing reserved words or user-defined names. Thus, AAAAA
, aaaaa
, Aaaaa
and AaAaA
are all the same word as far as GnuCOBOL is concerned.
The only time the case used does matter is within quoted character strings, where character values will be exactly as coded.
By convention throughout this document, COBOL reserved words will be shown entirely in UPPER-CASE
while those words that were created by a programmer will be represented by tokens in mixed or lower case.
This isn’t a bad practice to use in actual programs, as it leads to programs where it is much easier to distinguish reserved words from user-defined ones!
2.1.4. Readability of Programs
Critics of COBOL frequently focus on the wordiness of the language, often citing the case of a so-called “Hello World” program as the “proof” that COBOL is so much more tedious to program in than more “modern” languages. This tedium is cited as such a significant impact to programmer productivity that, in their opinions, COBOL can’t go away quickly enough.
Here are two different “Hello World” applications, one written in Java and the second in GnuCOBOL. First, the Java version:
Class HelloWorld { public static void main(String[] args) { System.out.println("Hello World!"); } }
And here is the same program, written in GnuCOBOL:
IDENTIFICATION DIVISION. PROGRAM-ID. HelloWorld. PROCEDURE DIVISION. DISPLAY "Hello World!".
Both of the above programs could have been written on a single line, if desired, and both languages allow a programmer to use (or not use) indentation as they see fit to improve program readability. Sounds like a tie so far.
Let’s look at how much more “wordy” COBOL is than Java. Count the characters in the two programs. The Java program has 95 (not counting carriage returns and any indentation). The COBOL program has 89 (again, not counting carriage returns and indentation)! Technically, it could have been only 65 because the IDENTIFICATION DIVISION.
header is actually optional. Clearly, “Hello World” doesn’t look any more concise in Java than it does in COBOL.
Let’s look at a different problem. Surely a program that asks a user to input a positive integer, generates the sum of all positive integers from 1 to that number and then prints the result will be MUCH shorter and MUCH easier to understand when coded in Java than in COBOL, right?
You can be the judge. First, the Java version:
import java.util.Scanner; public class sumofintegers { public static void main(String[] arg) { System.out.println("Enter a positive integer"); Scanner scan=new Scanner(System.in); int n=scan.nextInt(); int sum=0; for (int i=1;i<=n;i++) { sum+=i; } System.out.println("The sum is "+sum); } }
And now for the COBOL version:
IDENTIFICATION DIVISION. PROGRAM-ID. SumOfIntegers. DATA DIVISION. WORKING-STORAGE SECTION. 01 n BINARY-LONG. 01 i BINARY-LONG. 01 sum BINARY-LONG VALUE 0. PROCEDURE DIVISION. DISPLAY "Enter a positive integer" ACCEPT n PERFORM VARYING i FROM 1 BY 1 UNTIL i > n ADD i TO sum END-PERFORM DISPLAY "The sum is " sum.
My familiarity with COBOL may be prejudicing my opinion, but it doesn’t appear to me that the Java code is any simpler than the COBOL code. In case you’re interested in character counts, the Java code comes in at 278 (not counting indentation characters). The COBOL code is 298 (274 without the IDENTIFICATION DIVISION.
header).
Despite what you’ve seen here, the more complex the programming logic being implemented, the more concise the Java code will appear to be, even compared to 2002-standard COBOL. That conciseness comes with a price though — program code readability. Java (or C or C++ or C#) programs are generally intelligible only to trained programmers. COBOL programs can, however, be quite understandable by non-programmers. This is actually a side-effect of the “wordiness” of the language, where COBOL statements use natural English words to describe their actions. This inherent readability has come in handy many times throughout my career when I’ve had to learn obscure business (or legal) processes by reading the COBOL program code that supports them.
The “modern” languages, like Java, also have their own “boilerplate” infrastructure overhead that must be coded in order to write the logic that is necessary in the program. Take for example the public static void main(String[] arg)
and import java.util.Scanner;
statements. The critics tend to forget about this when they criticize COBOL for its structural “overhead”.
When it first was developed, COBOL’s easily-readable syntax made it profoundly different from anything that had been seen before. For the first time, it was possible to specify logic in a manner that was — at least to some extent — comprehensible even to non-programmers. Take for example, the following code written in FORTRAN — a language developed only a year before COBOL:
EXT = PRICE * IQTY INVTOT = INVTOT + EXT
With its original limitation on the length of variable names (one- to six-character names comprised of a letter followed by up to five letters and/or digits), its implicit rule that variables were automatically created as real (floating-point) unless their name started with a letter in the range I-N, and its use of algebraic notation to express actions being taken, FORTRAN wasn’t a particularly readable language, even for programmers. Compare this with the equivalent COBOL code:
MULTIPLY price BY quantity GIVING extended-amount ADD extended-amount TO invoice-total
Clearly, even a non-programmer could at least conceptually understand what was going on! Over time, languages like FORTRAN evolved more robust variable names, and COBOL introduced a more formula-based syntactical capability for arithmetic operations, but FORTRAN was never as readable as COBOL.
Because of its inherent readability, I would MUCH rather be handed an assignment to make significant changes to a COBOL program about which I know nothing than to be asked to do the same with a C, C++, C# or Java program.
Those that argue that it is too boring / wasteful / time-consuming / insulting (pick one) to have to code a COBOL program “from scratch” are clearly ignorant of the following facts:
- Many systems have program-development tools available to ease the task of coding programs; those tools that concentrate on COBOL are capable of providing templates for much of the “overhead” verbiage of any program…
- Good programmers have — for decades — maintained their own skeleton “template” programs for a variety of program types; simply load a template into a text editor and you’ve got a good start to the program…
- Legend has it that there’s actually only been ONE program ever written in COBOL, and all programs ever “written” thereafter were simply derivatives of that one. Although this is clearly intended as a (probably) bad joke, it is nevertheless close to the very simple truth that many programmers“reuse” existing COBOL programs when creating new ones. There’s certainly nothing preventing this from happening with programs written in other languages, but it does seem to happen more in COBOL shops. It’s ironic that “code re-usability” is one of the arguments used to justify the existence of the “modern” languages.
2.1.5. Divisions Organize Programs
COBOL programs are structured into four major areas of coding, each with its own purpose. These four areas are known as divisions.
Each division may consist of a variety of sections and each section consists of one or more paragraphs. A paragraph consists of sentences, each of which consists of one or more statements.
This hierarchical structure of program components standardizes the composition of all COBOL programs. Much of this manual describes the various divisions, sections, paragraphs and statements that may comprise any COBOL program. COPY
statement (see COPY)
2.1.6. Copybooks
A Copybook is a segment of program code that may be utilized by multiple programs simply by having those programs use the COPY
statement to import that code. This code may define files, data structures or procedural code.
Today’s current programming languages have a statement (usually, this statement is named “import”, “include” or “#include”) that performs this same function. What makes the COBOL copybook feature different than the “include” facility in newer languages, however, is the fact that the COPY
statement can edit the imported source code as it is being copied. This capability makes copybook libraries extremely valuable to making code reusable. Also see section 3. Compiler Directing Facility commands COPY and REPLACE.
2.1.7. Structured Data
A contiguous area of storage within the memory space of a program that may be referenced, by name, in a COBOL program is referred to as a Data Item. Other programming languages use the term variable, property or attribute to describe the same thing.
COBOL introduced the concept of structured data. The principle of structured data in COBOL is based on the idea of being able to group related and contiguously-allocated data items together into a single aggregate data item, called a Group Item. For example, a 35-character ’Employee-Name’ group item might consist of a 20-character ’Last-Name’ followed by a 14-character ’First-Name’ and a 1-character ’Middle-Initial’.
A data item that isn’t itself formed from other data items is referred to in COBOL as an Elementary Item. In the previous example, ’Last-Name’, ’First-Name’ and ’Middle-Initial’ are all elementary items.
2.1.8. Files
One of COBOL’s strengths is the wide variety of data files it is capable of accessing. GnuCOBOL programs, like those created with other COBOL implementations, need to have the structure of any files they will be reading and/or writing described to them. The highest-level characteristic of a file’s structure is defined by specifying the organization of the file, as follows:
ORGANIZATION LINE SEQUENTIAL
-
These are files with the simplest of all internal structures. Their contents are structured simply as a series of identically- or differently-sized data records, each terminated by a special end-of-record delimiter character. An ASCII line-feed character (hexadecimal 0A) is the end-of-record delimiter character used by any UNIX or pseudo-UNIX (MinGW, Cygwin, OSX) GnuCOBOL build. A truly native Windows build would use a carriage-return, line-feed (hexadecimal 0D0A) sequence.
Records must be read from or written to these files in a purely sequential manner. The only way to read (or write) record number 100 would be to have read (or written) records number 1 through 99 first.
When the file is written to by a GnuCOBOL program, the delimiter sequence will be automatically appended to each data record as it is written to the file. A
WRITE
(see WRITE) to this type of file will be done as if aBEFORE ADVANCING 1 LINE
clause were specified on theWRITE
, if noADVANCING
clause is coded.When the file is read, the GnuCOBOL runtime system will strip the trailing delimiter sequence from each record. The data will be padded (on the right) with spaces if the data just read is shorter than the area described for data records in the program. If the data is too long, it will be truncated and the excess will be lost.
These files should not be defined to contain any exact binary data fields because the contents of those fields could inadvertently have the end-of-record sequence as part of their values — this would confuse the runtime system when reading the file, and it would interpret that value as an actual end-of-record sequence.
LINE ADVANCING
-
These are files with an internal structure similar to that of a line sequential file. These files are defined (without an explicit
ORGANIZATION
specification) using theLINE ADVANCING
clause on theirSELECT
statement (see SELECT).When this kind of file is written to by a GnuCOBOL program, an end-of-record delimiter sequence will be automatically added to each data record as it is written to the file. A
WRITE
to this type of file will be done as if anAFTER ADVANCING 1 LINE
clause were specified on theWRITE
, if noADVANCING
clause is coded.Like line sequential files, these files should not be defined to contain any exact binary data fields because the contents of those fields could inadvertently have the end-of-record sequence as part of their values — this would confuse the runtime system when reading the file, and it would interpret that value as an actual end-of-record sequence.
ORGANIZATION SEQUENTIAL
-
These files also have a simple internal structure. Their contents are structured simply as an arbitrarily-long sequence of data characters. This sequence of characters will be treated as a series of fixed-length records simply by logically splitting the sequence of characters up into fixed-length segments, each as long as the maximum record size defined in the program. There are no special end-of-record delimiter characters in the file and when the file is written to by a GnuCOBOL program, no delimiter sequence is appended to the data.
Records in this type of file are all the same physical length, except possibly for the very last record in the file, which may be shorter than the others. If variable-length logical records are defined to the program, the space occupied by each physical record in the file will occupy the space described by the longest record description in the program.
So, if a file contains 1275 characters of data, and a program defines the structure of that file as containing 100-character records, then the file contents will consist of twelve (12) 100-character records with a final record containing only 75 characters.
It would appear that it should be possible to locate and process any record in the file directly simply by calculating its starting character position based upon the program-defined record size. Even so, however, records must be still be read or written to these files in a purely sequential manner. The only way to read (or write) record number 100 would be to have read (or written) records number 1 through 99 first.
When the file is read, the data is transferred into the program exactly as it exists in the file. In the event that a short record is read as the very last record, that record will be padded (to the right) with spaces.
Care must be taken that programs reading such a file describe records whose length is exactly the same as that used by the program that created the file. For example, the following shows the contents of a
SEQUENTIAL
file created by a program that wrote five 6-character records to it. The ‘A’, ‘B’, … values reflect the records that were written to the file:‘AAAAAA’‘BBBBBB’‘CCCCCC’‘DDDDDD’‘EEEEEE’Now, assume that another program reads this file, but describes 10-character records rather than 6. Here are the records that program will read:
‘AAAAAABBBB’‘BBCCCCCCDD’‘DDDDEEEEEE’There may be times where this is exactly what you were looking for. More often than not, however, this is not desirable behaviour. Suggestion: use a copybook to describe the record layouts of any file; this guarantees that multiple programs accessing that file will “see” the same record sizes and layouts by coding a
COPY
statement (see COPY) to import the record layout(s) rather than hand-coding them.These files can contain exact binary data fields. Because there is no character sequence that constitutes an end-of-record delimiter, the contents of record fields are irrelevant to the reading process.
ORGANIZATION RELATIVE
-
The contents of these files consist of a series of fixed-length data records prefixed with a four-byte record header. The record header contains the length of the data, in bytes. The byte-count does not include the four-byte record header.
Records in this type of file are all the same physical length. If variable-length logical records are defined to the program, the space occupied by each physical record in the file will occupy the maximum possible space, and the logical record length field will contain the number of bytes of data in the record that are actually in use.
This file organization was defined to accommodate either sequential or random processing. With a
RELATIVE
file, it is possible to read or write record 100 directly, without having to have first read or written records 1-99. The GnuCOBOL runtime system uses the program-defined maximum record size to calculate a relative byte position in the file where the record header and data begin, and then transfers the necessary data to or from the program.When the file is written by a GnuCOBOL program, no delimiter sequence is appended to the data, but a record-length field is added to the beginning of each physical record.
When the file is read, the data is transferred into the program exactly as it exists in the file.
Care must be taken that programs reading such a file describe records whose length is exactly the same as that used by the programs that created the file. It won’t end well if the GnuCOBOL runtime library interprets a four-byte ASCII character string as a record length when it transfers data from the file into the program!
Suggestion: use a copybook to describe the record layouts of any file; this guarantees that multiple programs accessing that file will “see” the same record sizes and layouts by coding a
COPY
statement (see COPY) to import the record layout(s) rather than hand-coding them.These files can contain exact binary data fields. The contents of record fields are irrelevant to the reading process as there is no end-of-record delimiter.
ORGANIZATION INDEXED
-
This is the most advanced file structure available to GnuCOBOL programs. It’s not possible to describe the physical structure of such files because that structure will vary depending upon which advanced file-management facility was included into the GnuCOBOL build you will be using (Berkeley Database [BDB], VBISAM, etc.). We will — instead — discuss the logical structure of the file.
There will be multiple structures stored for an
INDEXED
file. The first will be a data component, which may be thought of as being similar to the internal structure of a relative file. Data records may not, however, be directly accessed by their record number as would be the case with a relative file, nor may they be processed sequentially by their physical sequence in the file.The remaining structures will be one or more index components. An index component is a data structure that (somehow) enables the contents of a field, called a primary key, within each data record (a customer number, an employee number, a product code, a name, etc.) to be converted to a record number so that the data record for any given primary key value can be directly read, written and/or deleted. Additionally, the index data structure is defined in such a manner as to allow the file to be processed sequentially, record-by-record, in ascending sequence of the primary key field values. Whether this index structure exists as a binary-searchable tree structure (b-tree), an elaborate hash structure or something else is pretty much irrelevant to the programmer — the behaviour of the structure will be as it was just described. The actual mechanism used will depend upon the advanced file-management package was included into your GnuCOBOL implementation when it was built.
The runtime system will not allow two records to be written to an indexed file with the same primary key value.
The capability exists for an additional field to be defined as what is known as an alternate key. Alternate key fields behave just like primary keys, allowing both direct and sequential access to record data based upon the alternate key field values, with one exception. That exception is the fact that alternate keys may be allowed to have duplicate values, depending upon how the alternate key field is described to the GnuCOBOL compiler.
There may be any number of alternate keys, but each key field comes with a disk space penalty as well as an execution time penalty. As the number of alternate key fields increases, it will take longer and longer to write and/or modify records in the file.
These files can contain exact binary data fields. The contents of record fields are irrelevant to the reading process as there is no end-of-record delimiter.
All files are initially described to a GnuCOBOL program using a SELECT
statement (see SELECT). In addition to defining a name by which the file will be referenced within the program, the SELECT
statement will specify the name and path by which the file will be known to the operating system along with its organization, locking and sharing attributes.
A file description in the FILE SECTION
(see FILE SECTION) will define the structure of records within the file, including whether or not variable-length records are possible and, if so, what the minimum and maximum length might be. In addition, the file description entry can specify file I/O block sizes.
2.1.9. Table Handling
Other programming languages have arrays; COBOL has tables. They’re basically the same thing. There are two special statements that exist in the COBOL language — SEARCH
and SEARCH ALL
— that make finding data in a table easy.
SEARCH
searches a table sequentially, stopping only when either a table entry matching one of any number of search conditions is found, or when all table entries have been checked against the search criteria and none matched any of those criteria.
SEARCH ALL
performs an extremely fast search against a table sorted by a key field contained in each table entry. The algorithm used for such a search is a binary search. The algorithm ensures that only a small number of entries in the table need to be checked in order to find a desired entry or to determine that the desired entry doesn’t exist in the table. The larger the table, the more effective this search becomes. For example, a binary search of a table containing 32,768 entries will locate a particular entry or determine the entry doesn’t exist by looking at no more than fifteen (15) entries! The algorithm is explained in detail in the documentation of the SEARCH ALL
statement (see SEARCH ALL).
Finally, COBOL has the ability to perform in-place sorts of the data that is found in a table.
2.1.10. Sorting and Merging Data
The COBOL language includes a powerful SORT
statement that can sort large amounts of data according to arbitrarily complex key structures. This data may originate from within the program or may be contained in one or more external files. The sorted data may be written automatically to one or more output files or may be processed, record-by-record in the sorted sequence.
A companion statement — MERGE
— can combine the contents of multiple files together, provided those files are all pre-sorted in a similar manner according to the same key structure. The resulting output will consist of the contents of all of the input files, merged together and sequenced according to the common key structure(s). The output generated by a MERGE
statement may be written automatically to one or more output files or may be processed internally by the program.
A special form of the SORT
statement also exists just to sort the data that resides in a table. This is particularly useful if you wish to use SEARCH ALL
against the table.
2.1.11. String Manipulation
There have been programming languages designed specifically for the processing of text strings, and there have been programming languages designed for the sole purpose of performing high-powered numerical computations. Most programming languages fall somewhere in the middle.
COBOL is no exception, although it does include some very powerful string manipulation capabilities; GnuCOBOL actually has even more string-manipulation capabilities than many other COBOL implementations. The following summarizes GnuCOBOL’s string-processing capabilities:
- Concatenate two or more strings
-
-
CONCATENATE
intrinsic function (see CONCATENATE). -
STRING
statement (see STRING).
-
- Conversion of a numeric time or date to a formatted character string
-
-
LOCALE-TIME
intrinsic function (see LOCALE-TIME). -
LOCALE-DATE
intrinsic function (see LOCALE-DATE).
-
- Convert a binary value to its corresponding character in the program’s character set
-
-
CHAR
intrinsic function (see CHAR). Add 1 to argument before invoking the function; the description of theCHAR
intrinsic function presents a technique utilizing theMOVE
statement that will accomplish the same thing without the need of adding 1 to the numeric argument value first.
-
- Convert a character string to lower-case
-
-
LOWER-CASE
intrinsic function (see LOWER-CASE). -
C$TOLOWER
built-in system subroutine (see C$TOLOWER). -
CBL_TOLOWER
built-in system subroutine (see CBL_TOLOWER).
-
- Convert a character string to upper-case
-
-
UPPER-CASE
intrinsic function (see UPPER-CASE). -
C$TOUPPER
built-in system subroutine (see C$TOUPPER). -
CBL_TOUPPER
built-in system subroutine (see CBL_TOUPPER).
-
- Convert a character string to only printable characters
-
-
C$PRINTABLE
built-in system subroutine (see C$PRINTABLE).
-
- Convert a character to its numeric value in the program’s character set
-
-
ORD
intrinsic function (see ORD). Subtract 1 from the result; the description of theORD
intrinsic function presents a technique utilizing theMOVE
statement that will accomplish the same thing without the need of adding 1 to the numeric argument value first.
-
- Count occurrences of sub strings in a larger string
-
-
INSPECT
statement (see INSPECT) with theTALLYING
clause.
-
- Decode a formatted numeric string back to a numeric value
- Determine the length of a string or data-item capable of storing strings
-
-
LENGTH
intrinsic function (see LENGTH). -
BYTE-LENGTH
intrinsic function (see BYTE-LENGTH).
-
- Extract a sub string from a string based on its starting character position and length
-
- Use of a reference modifier on the string field - See Reference Modifiers.
- Format a numeric item for output, including thousands-separators (‘,’ in the USA), currency symbols (‘$’ in the USA), decimal points, credit/Debit Symbols, Leading Or Trailing Sign Characters
-
-
MOVE
statement (see MOVE) with picture-symbol editing applied to the receiving field:
-
- Justification (left, right or centred) of a string field
-
-
C$JUSTIFY
built-in system subroutine (see C$JUSTIFY).
-
- Monoalphabetic substitution of one or more characters in a string with different characters
-
-
INSPECT
statement (see INSPECT) with theCONVERTING
. -
TRANSFORM
statement (see TRANSFORM). -
SUBSTITUTE
intrinsic function (see SUBSTITUTE). -
SUBSTITUTE-CASE
intrinsic function (see SUBSTITUTE-CASE).
-
- Parse a string, breaking it up into sub strings based upon one or more delimiting character sequences1
-
-
UNSTRING
statement (see UNSTRING).
-
- Removal of leading or trailing spaces from a string
-
-
TRIM
intrinsic function (see TRIM).
-
- Substitution of a single sub string with another of the same length, based upon the sub strings starting character position and length
-
-
MOVE
statement (see MOVE) with a reference modifier on the “receiving” field (see Reference Modifiers).
-
- Substitution of one or more sub strings in a string with replacement sub strings of the same length, regardless of where they occur
-
-
INSPECT
statement (see INSPECT) with aREPLACING
clause. -
SUBSTITUTE
intrinsic function (see SUBSTITUTE). -
SUBSTITUTE-CASE
intrinsic function (see SUBSTITUTE-CASE).
-
- Substitution of one or more sub strings in a string with replacement sub strings of a potentially different length, regardless of where they occur
-
-
SUBSTITUTE
intrinsic function (see SUBSTITUTE). -
SUBSTITUTE-CASE
intrinsic function (see SUBSTITUTE-CASE).
-
2.1.12. Screen Formatting Features
The COBOL2002 standard formalizes extensions to the COBOL language that allow for the definition and processing of text-based screens, as is a typical function on mainframe and midframe computers as well as on many point-of-sale (i.e. “cash register”) systems. GnuCOBOL implements virtually all the screen-handling features described by COBOL2002.
These features allow fields to be displayed at specific row/column positions, various colors and video attributes to be assigned to screen fields and the pressing of specific function keys (F1, F2, …) to be detectable. All of this takes place through the auspices of the SCREEN SECTION
(see SCREEN SECTION) and special formats of the ACCEPT
statement (see ACCEPT) and the DISPLAY
statement (see DISPLAY).
The COBOL2002 standard, and therefore GnuCOBOL, only covers textual user interface (TUI) screens (those comprised of ASCII characters presented using a variety of visual attributes) and not the more-advanced graphical user interface (GUI) screen design and processing capabilities built into most modern operating systems. There are subroutine-based packages available that can do full GUI presentation — most of which may be called by GnuCOBOL programs, with a moderate research time investment (Tcl/Tk, for example) — but none are currently included with GnuCOBOL.
2.1.12.1. A Sample Screen
A Sample Screen Produced by a GnuCOBOL Program:
================================================================================ GCic (2014/01/02 11:24) GnuCOBOL 2.1 23NOV2013 Interactive Compilation +------------------------------------------------------------------------------+ : Filename: GCic.cbl : : Folder: E:\Programs\GCic\2013-11-23 : +------------------------------------------------------------------------------+ Set/Clr Switches Via F1-F9; Set Config Via F12; ENTER Key Compiles; ESC Quits +------------------------------------------------------------------------------+ : F1 Assume WITH DEBUGGING MODE F6 >"FUNCTION" Is Optional : Current : : F2 Procedure+Statement Trace F7 >Enable All Warnings : Config: : : F3 Make a Library (DLL) F8 Source Is Free-Format : DEFAULT : : F4 Execute If Compilation OK F9 >No COMP/BINARY Truncation : : : F5 Listing Off : : +------------------------------------------------------------------------------+ Extra "cobc" Switches, If Any ("-save-temps=xxx" Prevents Listings): +------------------------------------------------------------------------------+ : ____________________________________________________________________________ : : ____________________________________________________________________________ : +------------------------------------------------------------------------------+ Program Execution Arguments, If Any: +------------------------------------------------------------------------------+ : ____________________________________________________________________________ : : ____________________________________________________________________________ : +------------------------------------------------------------------------------+ GCic for Windows/MinGW Copyright (C) 2009-2014, Gary L. Cutler, GPL ================================================================================
The above screen was produced by the GnuCOBOL Interactive Compiler, or GCic. See GCic in GnuCOBOL Sample Programs, for the source and cross-reference listing of this program. PDF versions of this document will include an actual graphical image of this sample screen.
Screens are defined in the screen section of the data division. Once defined, screens are used at run-time via the ACCEPT
and DISPLAY
statements.
2.1.12.2. Color Palette and Video Attributes
GnuCOBOL supports the following visual attribute specifications in the SCREEN SECTION
(see SCREEN SECTION):
- Color
-
Eight (8) different colors may be specified for both the background (screen) and foreground (text) color of any row/column position on the screen. Colors are specified by number, although a copybook supplied with all GnuCOBOL distributions (screenio.cpy) defines
COB-COLOR-xxxxxx
names for the various colors so they may be specified as a more meaningful name rather than a number. The eight colors, by number, with the constant names defined in screenio.cpy, are as follows:Black
-
COB-COLOR-BLACK
Blue
-
COB-COLOR-BLUE
Green
-
COB-COLOR-GREEN
Cyan
-
COB-COLOR-CYAN
Red
-
COB-COLOR-RED
Magenta
-
COB-COLOR-MAGENTA
Yellow
-
COB-COLOR-YELLOW
White
COB-COLOR-WHITE
- Text Brightness
-
There are three possible brightness levels supported for text — lowlight (dim), normal and highlight (bright). Not all GnuCOBOL implementations will support all three (some treat lowlight the same as normal). The deciding factor as to whether two or three levels are supported lies with the version of the curses package that is being used. This is a utility screen-IO package that is included into the GnuCOBOL run-time library when the GnuCOBOL software is built.
As a general rule of thumb, Windows implementations support two levels while Unix ones support all three.
- Blinking
-
This too is a video feature that is dependent upon the curses package built into your version of GnuCOBOL. If blinking is enabled in that package, text displayed in fields defined in the screen section as being blinking will endlessly cycle between the brightest possible setting (highlight) and an “invisible” setting where the text color matches that of the field background color. A Windows build, which generally uses the “pcurses” package, will uses a brighter-than-normal background color to signify “blinking”.
- Reverse Video
-
This video attribute simply swaps the foreground and background colors and display options.
- Field Outlining
-
It is possible, if supported by the curses package being used, to draw borders on the top, left and/or bottom edges of a field.
- Secure Input
-
If desired, screen fields used as input fields may defined as “secure” fields, where each input character (regardless of what was actually typed) will appear as an asterisk (*) character. The actual character whose key was pressed will still be stored into the field in the program, however. This is very useful for password or account number fields.
- Prompt Character
Input fields may have any character used as a fill character. These fill characters provide a visual indication of the size of the input field, and will automatically be transformed into spaces when the input field is processed by the program. If no such character is defined for an input field, an underscore (‘_’) will be assumed.
2.1.13. Report Writer Features
GnuCOBOL includes an implementation of the Report Writer Control System, or RWCS. The reportwriter module is now fully implemented as of version 3.0. This is a standardized, optional add-on feature to the COBOL language which automates much of the mechanics involved in the generation of printed reports by:
- Controlling the pagination of reports, including:
- The automatic production of a one-time notice on the first page of the report (report heading).
- The production of zero or more header lines at the top of every page of the report (page heading).
- The production of zero or more footer lines at the bottom of every page of the report (page footing).
- The automatic numbering of printed pages.
- The formatting of those report lines that make up the main body of the report (detail).
- Full awareness of where the “pen” is about to “write” on the current page, automatically forcing an eject to a new page, along with the automatic generation of a page footer to close the old page and/or a page header to begin the new one.
- The production of a one-time notice at the end of the last page of a report (report footing).
- Performing special reporting actions based upon the fact that the data being used to generate the report has been sorted according to one or more key fields:
- Automatically suppressing the presentation of one or more fields of data from the detail group when the value(s) of the field(s) duplicate those of the previously generated detail group. Fields such as these are referred to as group-indicate fields.
- Automatically causing suppressed detail group-indicate fields to re-appear should a detail group be printed on a new page.
- Recognizing when control fields on the report — fields tied to those that were used as
SORT
statement (see SORT) keys — have changed. This is known as a control break. The RWCS can automatically perform the following reporting actions when a control break occurs:- Producing a footer, known as a control footing after the detail lines that shared the same old value for the control field.
- Producing a header, known as a control heading before the detail lines that share the same new value for the control field.
- Perform data summarise, as follows:
- Automatically generating subtotals in control and/or report footings, summarizing values of any fields in the detail group.
- Automatically generating crossfoot totals in detail groups. These would be sums of two or more values presented in the detail group.
The REPORT SECTION
(see REPORT SECTION) documentation explores the description of reports and the PROCEDURE DIVISION
(see PROCEDURE DIVISION) chapter documents the various language statements that actually produce reports. Before reading these, you might find it helpful to read Report Writer Usage, which is dedicated to putting the pieces together for you.
2.1.14. Data Initialization
There are three ways in which data division data gets initialized.
- When a program or subprogram is first executed, much of the data in its data division will be initialized as follows:
- Alphanumeric and alphabetic (i.e. text) data items will be initialized to
SPACES
. - Numeric data items will be initialized to a value of
ZERO
. - Data items with an explicit
VALUE
(see VALUE) clause in their definition will be initialized to that specific value.
The various sections of the data division each have their own rules as to when the actions described above will occur — consult the documentation on those sections for additional information.
These default initialization rules can vary quite substantially from one COBOL implementation to another. For example, it is quite common for data division storage to be initialized to all binary zeros except for those data items where
VALUE
clauses are present. Take care when working with applications originally developed for another COBOL implementation to ensure that GnuCOBOL’s default initialization rules won’t prove disruptive. - Alphanumeric and alphabetic (i.e. text) data items will be initialized to
- A programmer may use the
INITIALIZE
statement (see INITIALIZE) to initialise any group or elementary data item at any time. This statement provides far more initialization options than just the simple rules stated above. - When the
ALLOCATE
statement (see ALLOCATE) statement is used to allocate a data item or to simply allocate an area of storage of a size specified on theALLOCATE
, that allocation may occur with or without initialization, as per the programmer’s needs.
2.1.15. Syntax Diagram Conventions
Syntax of the GnuCOBOL language will be described in special syntax diagrams using the following syntactical-description techniques:
MANDATORY-RESERVED-WORD
~~~~~~~~~~~~~~~~~~~~~~~
-
Reserved words of the COBOL language will appear in UPPER-CASE. When they appear underlined, as this one is, they are required reserved words.
OPTIONAL-RESERVED-WORD
-
When reserved words appear without underlining, as this one is, they are optional; such reserved words are available in the language syntax merely to improve readability — their presence or absence has no effect upon the program.
ABBREVIATION
~~~~
-
When only a portion of a reserved word is underlined, it indicates that the word may either be coded in its full form or may be abbreviated to the portion that is underlined.
substitutable-items
-
Generic terms representing user-defined substitutable items will be shown entirely in lower-case in syntax diagrams. When such items are referenced in text, they will appear as substitutable-items.
Complex-Syntax-Clause
-
Items appearing in Mixed Case within a syntax diagram represent complex clauses of other syntax elements that may appear in that position. Some COBOL syntax gets quite complicated, and using a convention such as this significantly reduces the complexity of a syntax diagram. When such items are referenced in text, they will appear as Complex-Syntax-Clause.
[ ]
-
Square bracket meta characters on syntax diagrams document language syntax that is optional. The [] characters themselves should not be coded. If a syntax diagram contains ‘a [b] c’, the ‘a’ and ‘c’ syntax elements are mandatory but the ‘b’ element is optional.
|
-
Vertical bar meta characters on syntax diagrams document simple choices. The | character itself should not be coded. If a syntax diagram contains ‘a|b|c’, exactly one of the items ‘a’, ‘b’ or ‘c’ must be selected.
{ xxxxxx }
{ yyyyyy }
{ zzzzzz }
-
A vertical list of items, bounded by multiple brace characters, is another way of signifying a choice between a series of items where exactly one item must be selected. This form is used to show choices when one or more of the selections is more complex than just a single word, or when there are too many choices to present horizontally with ‘|’ meta characters.
| xxxxxx |
| yyyyyy |
| zzzzzz |
-
A vertical list of items, bounded by multiple vertical bar characters, signifies a choice between a series of items where one or more of the choices could be selected.
...
-
The ... meta character sequence signifies that the syntax element immediately preceding it may be repeated. The ... sequence itself should not be coded. If a syntax diagram contains
a b... c
, syntax element ‘a’ must be followed by at least one ‘b’ element (possibly more) and the entire sequence must be terminated by a ‘c’ syntax element. { }
-
The braces (‘{’ and ‘}’) meta characters may be used to group a sequence of syntax elements together so that they may be treated as a single entity. The
{}
characters themselves should not be coded. These are typically used in combination with the ‘|’ or ‘...’ meta characters. $*^()-+=:"'<,>./
Any of these characters appearing within a syntax diagram are to be interpreted literally, and are characters that must be coded — where allowed — in the statement whose format is being described. Note that a ‘.’ character is a literal character that must be coded on a statement whereas a ‘...’ symbol is the meta character sequence described above.
2.1.16. Format of Program Source Lines
Prior to the COBOL2002 standard, source statements in COBOL programs were structured around 80-column punched cards. This means that each source line in a COBOL program consisted of five different “areas”, defined by their column number(s).
As of the COBOL2002 standard, a second mode now exists for COBOL source code statements — in this mode of operation, COBOL statements may each be up to 255 characters long, with no specific requirements as to what should appear in which columns.
Of course, in keeping with the long-standing COBOL tradition of maintaining backwards compatibility with older standards, programmers (and, of course, compliant COBOL compilers) are capable of working in either mode. It is even possible to switch back and forth in the same program. The terms Fixed Format Mode and Free Format Mode are used to refer to these two modes of source code formatting.
The GnuCOBOL compiler (cobc) supports both of these source line format modes, defaulting to Fixed Format Mode lacking any other information.
The compiler can be instructed to operate in either mode in any of the following four ways:
- Using a compiler option switch — use the -fixed switch to start in Fixed Format Mode (remember that this is the default) or the -free switch to start in Free Format Mode.
- You may use the
SOURCEFORMAT AS FIXED
andSOURCEFORMAT AS FREE
clauses of the>>SET
CDF directive (see >>SET) within your source code to switch to Fixed or Free Format Mode, respectively. - You may use the
>>FORMAT IS FIXED
andFORMAT IS FREE
clauses of the>>DEFINE
CDF directive (see >>DEFINE) within your source code to switch to Fixed or Free Format Mode, respectively. - You may use the
>>SOURCE
CDF directive (see >>SOURCE) to switch to Free Format Mode (>>SOURCE FORMAT IS FREE
) or Fixed Format Mode (>>SOURCE FORMAT IS FIXED
.
Using methods 2-4 above, you may switch back and forth between the two formats at will.
The last three options above are all equivalent; all three are supported by GnuCOBOL so that source code compatibility may be maintained with a wide variety of other COBOL implementations. With all three, if the compiler is currently in Fixed Format Mode, the >>
must begin in column 8 or beyond, provided no part of the directive extends past column 72. If the compiler is currently in Free Format Mode, the >>
may appear in any column, provided no part of the directive extends past column 255.
Depending upon which source format mode the compiler is in, you will need to follow various rules for the format mode currently in effect. These rules are presented in the upcoming paragraphs.
The following discussion presents the various components of every GnuCOBOL source line record when the compiler is operating in Fixed Format Mode. Remember that this is the default mode for the GnuCOBOL compiler.
- 1-6
-
Sequence Number Area
Historically, back in the days when punched-cards were used to submit COBOL program source to a COBOL compiler, this part of a COBOL statement was reserved for a six-digit sequence number. While the contents of this area are ignored by COBOL compilers, it existed so that a program actually punched on 80-character cards could — if the card deck were dropped on the floor — be run through a card sorter machine and restored to its proper sequence. Of course, this isn’t necessary today; if truth be told, it hasn’t been necessary for a long time.
See Marking Changes in Programs, for discussion of a valuable use to which the sequence number area may be put today.
- 7
-
Indicator Area
Column 7 serves as an indicator in which one of five possible values will appear — space,
D
(ord
),-
(dash),/
or*
. The meanings of these characters are as follows:- space
-
No special meaning — this is the normal character that will appear in this area.
- D/d
-
The line contains a valid GnuCOBOL statement that is normally treated as a comment unless the program is being compiled in debugging mode.
- *
-
The line is a comment.
- /
-
The line is a comment that will also force a page eject in the compilation listing. While GnuCOBOL will honour such a line as a comment, it will not form-feed any generated listing.
- -
The line is a continuation of the previous line. These are needed only when an alphanumeric literal (quoted character string), reserved word or user-defined word are being split across lines.
- 8-11
-
Area A
Language
DIVISION
,SECTION
and paragraph section headers must b egin in Area A, as must the level numbers 01, 77 in data description entries and theFD
andSD
file andSORT
description headers. - 12-72
-
Area B
All other COBOL programming language components are coded in these columns.
- 73-80
-
Program Name Area
This is another obsolete area of COBOL statements. This part of every statement also hails back to the day when programs were punched on cards; it was expected that the name of the program (or at least the first 8 characters of it) would be punched here so that — if a dropped COBOL source deck contained more than one program — that handy card sorter machine could be used to first separate the cards by program name and then sort them by sequence number. Today’s COBOL compilers (including GnuCOBOL) simply ignore anything past column 72.
See Marking Changes in Programs, for discussion of a valuable use to which the program name area may be put today.
2.1.17. Program Structure
Complete GnuCOBOL Program Syntax
[ IDENTIFICATION DIVISION. ] ~~~~~~~~~~~~~~~~~~~~~~~ PROGRAM-ID|FUNCTION-ID. name-1 [ Program-Options ] . ~~~~~~~~~~ ~~~~~~~~~~~ [ ENVIRONMENT DIVISION. ] ~~~~~~~~~~~ ~~~~~~~~ [ CONFIGURATION SECTION. ] ~~~~~~~~~~~~~ ~~~~~~~ [ SOURCE-COMPUTER. Compilation-Computer-Specification . ] ~~~~~~~~~~~~~~~ [ OBJECT-COMPUTER. Execution-Computer-Specification . ] ~~~~~~~~~~~~~~~ [ REPOSITORY. Function-Specification... . ] ~~~~~~~~~~ [ SPECIAL-NAMES. Program-Configuration-Specification . ] ~~~~~~~~~~~~~ [ INPUT-OUTPUT SECTION. ] ~~~~~~~~~~~~ ~~~~~~~ [ FILE-CONTROL. General-File-Description... . ] ~~~~~~~~~~~~ [ I-O-CONTROL. File-Buffering-Specification... . ] ~~~~~~~~~~~ [ DATA DIVISION. ] ~~~~~~~~~~~~~ [ FILE SECTION. Detailed-File-Description... . ] ~~~~~~~~~~~~ [ WORKING-STORAGE SECTION. Permanent-Data-Definition... . ] ~~~~~~~~~~~~~~~ ~~~~~~~ [ LOCAL-STORAGE SECTION. Temporary-Data-Definition... . ] ~~~~~~~~~~~~~ ~~~~~~~ [ LINKAGE SECTION. Subprogram-Argument-Description... . ] ~~~~~~~ ~~~~~~~ [ REPORT SECTION. Report-Description... . ] ~~~~~~ ~~~~~~~ [ SCREEN SECTION. Screen-Layout-Definition... . ] ~~~~~~ ~~~~~~~ PROCEDURE DIVISION [ { USING Subprogram-Argument... } ] ~~~~~~~~~ ~~~~~~~~ { ~~~~~ } { CHAINING Main-Program-Argument... } ~~~~~~~~ [ RETURNING identifier-1 ] . [ DECLARATIVES. ] ~~~~~~~~~ ~~~~~~~~~~~~ [ Event-Handler-Routine... . ] [ END DECLARATIVES. ] ~~~ ~~~~~~~~~~~~ General-Program-Logic [ Nested-Subprogram... ] [ END PROGRAM|FUNCTION name-1 ] ~~~ ~~~~~~~ ~~~~~~~~
Each program consists of up to four Divisions (major groupings of sections, paragraphs and descriptive or procedural coding that all relate to a common purpose), named Identification, Environment, Data and Procedure.
- Not all divisions are needed in every program, but they must be specified in the order shown when they are used.
- The following points pertain to the identification division
- The
IDENTIFICATION DIVISION.
header is always optional.
- The
- The following points pertain to the environment division:
- If both optional sections of this division are coded, they must be coded in the sequence shown.
- Each of these sections consists of a series of specific paragraphs (
SOURCE-COMPUTER
andOBJECT-COMPUTER
, for example). Each of these paragraphs serves a specific purpose. If no code is required for the purpose one of the paragraphs serves, the entire paragraph may be omitted. - If none of the paragraphs within one of the sections are coded, the section header itself may be omitted.
- The paragraphs within each section may only be coded in that section, but may be coded in any order.
- If none of the sections within the environment division are coded, the
ENVIRONMENT DIVISION.
header itself may be omitted.
- The following points pertain to the data division:
- The data division consists of six optional sections — when used, those sections must be coded in the order shown in the syntax diagram.
- Each of these sections consists of code which serves a specific purpose. If no code is required for the purpose one of those sections serves, the entire section, including its header, may be omitted.
- If none of the sections within the data division are coded (a highly unlikely, but theoretically possible circumstance), the
DATA DIVISION.
header itself may be omitted.
- The following points pertain to the procedure division:
- As with the other divisions, the procedure division may consist of sections and those sections may — in turn — consist of paragraphs. Unlike the other divisions, however, section and paragraph names are defined by the programmer, and there may not be any defined at all if the programmer so wishes.
- Each Event-Handler-Routine will be a separate section devoted to trapping a particular run-time event. If there are no such sections coded, the
DECLARATIVES.
andEND DECLARATIVES.
lines may be omitted.
- A single file of COBOL source code may contain:
- A portion of a program; these files are known as copybooks
- A single program. In this case, the
END PROGRAM
orEND FUNCTION
statement is optional. - Multiple programs, separated from one another by
END PROGRAM
orEND FUNCTION
statements. The final program in such a source code file need not have anEND PROGRAM
orEND FUNCTION
statement.
- Subprogram ‘B’ may be nested inside program ‘A’ by including program B’s source code at the end of program A’s procedure division without an intervening
END PROGRAM A.
orEND FUNCTION A.
statement. For now, that’s all that will be said about nesting. See Independent vs Contained vs Nested Subprograms, for more information. - Regardless of how many programs comprise a single GnuCOBOL source file, only a single output executable program will be generated from that source file when the file is compiled.
2.1.18. Comments
The following information describes how comments may be embedded into GnuCOBOL program source to provide documentation.
Comment Type | Source Mode — Description |
---|---|
Blank Lines |
FIXED — Blank lines may be inserted as desired. FREE — Blank lines may be inserted as desired. |
Full-line comments |
FIXED — An entire source line will be treated as a comment (and will be ignored by the compiler) by coding an asterisk (‘*’) in column seven (7). FREE — An entire source line will be treated as a comment (and will be ignored by the compiler) by coding the sequence ‘*>’, starting in any column, as the first non-blank characters on the line. |
Full-line comments with form-feed |
FIXED — An entire source line will be treated as a comment by coding a slash (‘/’) in column seven (7). Many COBOL compilers will also issue a form-feed in the program listing so that the ‘/’ line is at the top of a new page. The GnuCOBOL compiler does not support this form-feed behaviour. The GnuCOBOL Interactive Compiler, or GCic, does support this form-feed behaviour when it generates program source listings! See GCic in GnuCOBOL Sample Programs, for the source and cross-reference listing (produced by GCic) of this program — you can see the effect of ‘/’ there. FREE — There is no Free Source Mode equivalent to ‘/’. |
Partial-line comments |
FIXED — Any text following the character sequence ‘*>’ on a source line will be treated as a comment. The ‘*’ must appear in column seven (7) or beyond. FREE — Any text following the character sequence ‘*>’ on a source line will be treated as a comment. The ‘*’ may appear in any column. |
Comments that may be treated as code, typically for debugging purposes |
FIXED — By coding a ‘D’ in column 7 (upper- or lower-case), an otherwise valid GnuCOBOL source line will be treated as a comment by the compiler. FREE — By specifying the character sequence ‘>>D’ (upper- or lower-case) as the first non-blank characters on a source line, an otherwise valid GnuCOBOL source line will be treated as a comment by the compiler. Debugging statements may be compiled either by specifying the -fdebugging-line switch on the GnuCOBOL compiler or by adding the |
2.1.19. Literals
Literals are constant values that will not change during the execution of a program. There are two fundamental types of literals — numeric and alphanumeric.
2.1.19.1. Numeric LiteralsA numeric literal
- Integers such as 1, 56, 2192 or -54.
- Non-integer fixed point values such as 1.317 or -2.95.
- Floating-point values using ‘Enn’ notation such as
9.92E25
, representing 9.92 x 1025 (10 raised to the 25th power) or5.7E-14
, representing 5.7 x 10-14 (10 raised to the -14th power). Both the mantissa (the number before the ‘E’) and the exponent (the number after the ‘E’) may be explicitly specified as positive (with a ‘+’), negative (with a ‘-’) or unsigned (and therefore implicitly positive). A floating-point literals value must be within the range -1.7 x 10308 to +1.7 x 10308 with no more than 15 decimal digits of precision. - Hexadecimal numeric literals
- Null terminated literals
- Raw C string using
L"characters"
. - Binary using B#0 or 1.
- Octal using O#0 - 7. (That is the letter ‘O’).
- Hexadecimal number using
H#
orX#
‘0’ - ‘F’. - Boolean Literals (Standard)
B" character "
. - Boolean Literals (Hexadecimal)
BX" hex character "
. - National Literals (Standard)
N" character "
orNC" character "
. - National Literals (Hexadecimal)
NX" character "
.
2.1.19.2. Alphanumeric Literals
An alphanumeric literal
An alphanumeric literal is not valid for use in arithmetic expressions unless it is first converted to its numeric computational equivalent; there are three numeric conversion intrinsic functions built into GnuCOBOL that can perform this conversion — NUMVAL
(see NUMVAL), NUMVAL-C
(see NUMVAL-C) and NUMVAL-F
(see NUMVAL-F).
Alphanumeric literals may take any of the following forms:
- A sequence of characters enclosed by a pair of single-quote (‘'’)
- A literal formed according to the same rules as for a string literal (above), but prefixed with the letter ‘Z’ (upper- or lower-case) constitutes a zero-delimited string literal. These literals differ from ordinary string literals in that they will be explicitly terminated with a byte of hexadecimal value 00. These Zero-Delimited Alphanumeric Literals
- A Hexadecimal Alphanumeric Literal
Alphanumeric literals too long to fit on a single line may be continued to the next line in one of two ways:
- If you are using Fixed Format Mode, the alphanumeric literal can be run right up to and including column 72. The literal may then be continued on the next line anywhere after column 11 by coding another quote or apostrophe (whichever was used to begin the literal originally). The continuation line must also have a hyphen (-)
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
01 LONG-LITERAL-VALUE-DEMO PIC X(60) VALUE "This is a long l
- "ong literal that
- " must be continu
- "ed.".
- Regardless of whether the compiler is operating in Fixed or Free Format Mode, GnuCOBOL allows alphanumeric literals to be broken up into separate fragments. These fragments have their own beginning and ending quote/apostrophe characters and are “glued together” at compilation time using ‘&’
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
01 LONG-LITERAL-VALUE-DEMO PIC X(60) VALUE "This is a" &
" long literal that must " &
"be continued.".
If your program is using Free Format Mode, there’s less need to continue long alphanumeric literals because statements may be as long as 255 characters.
Numeric literals may be split across lines just as alphanumeric literals are, using either of the above techniques and both reserved and user-defined words can be split across lines too (using the first technique). The continuation of numeric literals and user-defined/reserved words is provided merely to provide compatibility with older COBOL versions and programs, but should not be used with new programs — it just makes for ugly-looking programs.
2.1.19.3. Figurative Constants
Figurative constants are reserved words that may be used as literals anywhere the figurative constants value could be interpreted as an arbitrarily long sequence of the characters in question. When a specific length is required, such as would be the case with an argument to a subprogram, a figurative constant may not be used. Thus, the following are valid uses of figurative constants:
05 FILLER PIC 9(10) VALUE ZEROS. ... MOVE SPACES TO Employee-Name
But this is not:
CALL "SUBPGM" USING SPACES
The following are the GnuCOBOL figurative constants and their respective equivalent values.
ZERO
-
This figurative constant has a value of numeric 0 (zero).
ZEROS
andZEROES
are both synonyms ofZERO
. SPACE
-
This figurative constant has a value of one or more space characters.
SPACES
is a synonym ofSPACE
. QUOTE
-
This figurative constant has a value of one or more double-quote characters (").
QUOTES
is a synonym ofQUOTE
. LOW-VALUE
-
This figurative constant has a value of one or more of whatever character occupies the lowest position in the program’s collating sequence as defined in the
OBJECT-COMPUTER
(see OBJECT-COMPUTER) paragraph or — if no such specification was made — in whatever default character set the program is using (typically, this is the ASCII character set).LOW-VALUES
is a synonym ofLOW-VALUE
.When the character set in use is ASCII with no collating sequence modifications, the
LOW-VALUES
figurative constant value is the ASCIINUL
character. Because character sets can be redefined, however, you should not rely on this fact. Use theNULL
figurative constant instead. HIGH-VALUE
-
This figurative constant has a value of one or more of whatever character occupies the highest position in the program’s collating sequence as defined in the
OBJECT-COMPUTER
paragraph or — if no such specification was made — in whatever default character set the program is using (typically, this is the ASCII character set).HIGH-VALUES
is a synonym ofHIGH-VALUE
. NULL
A character comprised entirely of zero-bits (regardless of the programs collating sequence).
Programmers may create their own figurative constants via the SYMBOLIC CHARACTERS
(see Symbolic-Characters-Clause) clause of the SPECIAL-NAMES
(see SPECIAL-NAMES) paragraph.
2.1.20. Punctuation
A comma (‘,’)
The use of comma characters can cause confusion to a COBOL compiler if the DECIMAL POINT IS COMMA
clause is used in the SPECIAL-NAMES
(see SPECIAL-NAMES) paragraph, as might be the case in Europe. The following statement, which calls a subroutine passing it two arguments (the numeric constants 1 and 2):
CALL "SUBROUTINE" USING 1,2
Would — with DECIMAL POINT IS COMMA
in effect — actually be interpreted as a subroutine call with 1 argument (the non-integer numeric literal whose value is 1 and 2 tenths). For this reason, it is best to always follow a comma with a space.
The period character (‘.’)
The rules for where and when periods are needed in the procedure division are somewhat complicated. See Use of Periods, for the details.
2.1.21. Interfacing to Other Environments
Through the CALL
statement, COBOL programs may invoke other COBOL programs serving as subprograms. This is quite similar to cross-program linkage capabilities provided by other languages. In GnuCOBOL’s case, the CALL
facility is powerful enough to be tailored to the point where a GnuCOBOL program can communicate with operating system, database management and run-time library APIs, even if they weren’t written in COBOL themselves. See GnuCOBOL Main Programs CALLing C Subprograms, for an example of how a GnuCOBOL program could invoke a C-language subprogram, passing information back and forth between the two.
The fact that GnuCOBOL supports a full-featured two-way interface with C-language programs means that — even if you cannot access a library API directly — you could always do so via a small C “wrapper” program that is CALL
ed by a GnuCOBOL program.
2.2. The COBOL Language - Advanced Techniques
2.2.1. Table References
COBOL uses parenthesis to specify the subscripts used to reference table entries (tables in COBOL are what other programming languages refer to as arrays).
For example, observe the following data structure which defines a 4 column by 3 row grid of characters:
01 GRID. 05 GRID-ROW OCCURS 3 TIMES. 10 GRID-COLUMN OCCURS 4 TIMES. 15 GRID-CHARACTER PIC X(1).
If the structure contains the following grid of characters:
A B C D E F G H I J K L
Then GRID-CHARACTER (2, 3)
references the ‘G’ and GRID-CHARACTER (3, 2)
references the ‘J’.
Subscripts may be specified as numeric (integer) literals, numeric (integer) data items, data items created with any of the picture-less integer USAGE
(see USAGE) specifications, USAGE INDEX
data items or arithmetic expressions resulting in a non-zero integer value.
In the above examples, a comma is used as a separator character between the two subscript values; semicolons (;
) are also valid subscript separator characters, as are spaces! The use of a comma or semicolon separator in such a situation is technically optional, but by convention most COBOL programmers use one or the other. The use of no separator character (other than a space) is not recommended, even though it is syntactically correct, as this practice can lead to programmer-unfriendly code. It isn’t too difficult to read and understand GRID-CHARACTER(2 3)
, but it’s another story entirely when trying to comprehend GRID-CHARACTER(I + 1 J / 3)
(instead of GRID-CHARACTER(I + 1, J / 3)
). The compiler accepts it, but too much of this would make my head hurt.
2.2.2. Qualification of Data Names
COBOL allows data names to be duplicated within a program, provided references to those data names may be made in such a manner as to make those references unique through a process known as qualification.
To see qualification at work, observe the following segments of two data records defined in a COBOL program:
01 EMPLOYEE. 01 CUSTOMER. 05 MAILING-ADDRESS. 05 MAILING-ADDRESS. 10 STREET PIC X(35). 10 STREET PIC X(35). 10 CITY PIC X(15). 10 CITY PIC X(15). 10 STATE PIC X(2). 10 STATE PIC X(2). 10 ZIP-CODE. 10 ZIP-CODE. 15 ZIP-CODE-5 PIC 9(5). 15 ZIP-CODE-5 PIC 9(5). 15 FILLER PIC X(4). 15 FILLER PIC X(4).
Now, let’s deal with the problem of setting the CITY
portion of an EMPLOYEE
s MAILING-ADDRESS
to ‘Philadelphia’. Clearly, MOVE 'Philadelphia' TO CITY
cannot work because the compiler will be unable to determine which of the two CITY
fields you are referring to.
In an attempt to correct the problem, we could qualify the reference to CITY
as MOVE 'Philadelphia' TO CITY OF MAILING-ADDRESS
.
Unfortunately that too is insufficient because it still insufficiently specifies which CITY
is being referenced. To truly identify which specific CITY
you want, you’d have to code MOVE 'Philadelphia' TO CITY OF MAILING-ADDRESS OF EMPLOYEE
.
Now there can be no confusion as to which CITY
is being changed. Fortunately, you don’t need to be quite so specific; COBOL allows intermediate and unnecessary qualification levels to be omitted. This allows MOVE 'Philadelphia' TO CITY OF EMPLOYEE
to do the job nicely.
If you need to qualify a reference to a table, do so by coding something like identifier-1 OF identifier-2 ( subscript(s) )
.
The reserved word IN
may be used in lieu of OF
.
2.2.3. Reference Modifiers
Reference Modifier (Format 1) Syntax
identifier-1 [ OF|IN identifier-2 ] [ (subscript...) ] (start:[ length ]) ~~ ~~
Reference Modifier (Format 2) Syntax
intrinsic-function-reference (start:[ length ])
The COBOL 1985 standard introduced the concept of a reference modifier to facilitate references to only a portion of a data item; GnuCOBOL fully supports reference modification.
The start value indicates the starting character position being referenced (character position values start with 1, not 0 as is the case in some programming languages) and length specifies how many characters are wanted.
If no length is specified, a value equivalent to the remaining character positions from start to the end of identifier-1 or to the end of the value returned by the function will be assumed.
Both start and length may be specified as integer numeric literals, integer numeric data items or arithmetic expressions with an integer value.
Here are a few examples:
CUSTOMER-LAST-NAME (1:3)
-
References the first three characters of
CUSTOMER-LAST-NAME
. CUSTOMER-LAST-NAME (4:)
-
References all character positions of
CUSTOMER-LAST-NAME
from the fourth onward. FUNCTION CURRENT-DATE (5:2)
-
References the current month as a 2-digit number in character form. See CURRENT-DATE, for more information.
Hex-Digits (Nibble + 1:1)
-
Assuming that
Nibble
is a numeric data item with a value in the range 0-15, and Hex-Digits is aPIC X(16)
item with a value of0123456789ABCDEF
, this converts that numeric value to a hexadecimal digit. Table-Entry (6) (7:5)
References characters 7 through 11 (5 characters in total) in the 6th occurrence of Table-Entry.
Reference modification may be used anywhere an identifier is legal, including serving as the receiving field of statements like MOVE
(see MOVE), STRING
(see STRING) and ACCEPT
(see ACCEPT), to name a few.
2.2.4. Arithmetic Expressions
Arithmetic-Expression Syntax
Unary-Expression-1 { **|^ } Unary-Expression-2 { *|/ } { +|- }
Unary-Expression Syntax
{ [ +|- ] { ( Arithmetic-Expression-1 ) } } { { [ LENGTH OF ] { identifier-1 } } } { { ~~~~~~ ~~ { literal-1 } } } { { { Function-Reference } } } { Arithmetic-Expression-2 }
Arithmetic expressions are formed using four categories of operations — exponentiation, multiplication & division, addition & subtraction, and sign specification.
In complex expressions composed of multiple operators and operands, a precedence of operation applies whereby those operations having a higher precedence are computed first before operations with a lower precedence.
As is the case in almost any other programming language, the programmer is always free to use pairs of parenthesis to enclose sub-expressions of complex expressions that are to be evaluated before other sub-expressions rather than let operator precedence dictate the sequence of evaluation.
In highest to lowest order of precedence, here is a discussion of each category of operation:
- Level 1 (Highest) — Unary Sign Specification (
+
and-
with a single argument) -
The unary “minus” (-) operator returns the arithmetic negation of its single argument, effectively returning as its value the product of its argument and -1.
The unary “plus” (+) operator returns the value of its single argument, effectively returning as its value the product of its argument and +1.
- Level 2 — Exponentiation (
**
or^
) -
The value of the left argument is raised to the power indicated by the right argument. Non-integer powers are allowed. The
^
and**
operators are both supported to provide compatibility with programs written for other COBOL implementations. - Level 3 — Multiplication (
*
) and division (/
) -
The
*
operator computes the product of the left and right arguments while the/
operator computes the value of the left argument divided by the value of the right argument. If the right argument has a value of zero, expression evaluation will be prematurely terminated before a value is generated. This may cause program failure at run-time.A sequence of multiple 3rd-level operations (
A * B / C
, for example) will evaluate in strict left-to-right sequence if no parenthesis are used to control the order of evaluation. - Level 4 — Addition (
+
) or subtraction (+
) -
The
+
operator calculates the sum of the left and right arguments while the-
operator computes the value of the right argument subtracted from that of the left argument.A sequence of multiple 4th-level operations (
A - B + C
, for example) will evaluate in strict left-to-right sequence if no parenthesis are used to control the order of evaluation.
The syntactical rules of COBOL, allowing a dash (-) character in data item names, can lead to some ambiguity.
01 C PIC 9 VALUE 5. 01 D PIC 9 VALUE 2. 01 C-D PIC 9 VALUE 7. 01 I PIC 9 VALUE 0. … COMPUTE I=C-D+1
The COMPUTE
(see COMPUTE) statement will evaluate the arithmetic expression C-D+1
and then save that result in I
.
What value will be stored in I
? The number 4, which is the result of subtracting the value of D
(2) from the value of C
(5) and then adding 1? Or, will it be the number 8, which is the value of adding 1 to the value of data item C-D
(7)?
The right answer is 8 — the value of data item C-D
plus 1! Hopefully, that was the intended result.
The GnuCOBOL compiler actually went through the following decision-making logic when generating code for the COMPUTE
Statement:
- Is there a data item named
C-D
defined? If so, use its value for the character sequenceC-D
. - If there is no
C-D
data item, then are thereC
andD
data items? If not, theCOMPUTE
statement is in error. If there are, however, then code will be generated to subtract the value ofD
fromC
and add 1 to the result.
Had there been at least one space to the left and/or the right of the -
, there would have been no ambiguity — the compiler would have been forced to use the individual C
and D
data items.
To avoid any possible ambiguity, as well as to improve program readability, it’s considered good COBOL programming practice to always code at least one space to both the left and right of every operator in arithmetic expressions as well as the =
sign on a COMPUTE.
Here are some examples of how the precedence of operations affects the results of arithmetic expressions (all examples use numeric literals, to simplify the discussion).
Expression | Result | Notes |
---|---|---|
3 * 4 + 1 | 13 | * has precedence over + |
4 * 2 ^ 3 - 10 | 22 | 2^3 is 8 (^ has precedence over *), times 4 is 32, minus 10 is 22. |
(4 * 2) ^ 3 - 10 | 502 | Parenthesis provide for a recursive application of the arithmetic expression rules, effectively allowing you to alter the precedence of operations. 4 times 2 is 8 (the use of parenthesis “trumps” the exponentiation operator, so the multiplication happens first); 8 ^ 3 is 512, minus 10 is 502. |
5 / 2.5 + 7 * 2 - 1.15 | 15.35 | Integer and non-integer operands may be freely intermixed |
Of course, arithmetic expression operands may be numeric data items (any USAGE except POINTER or PROGRAM POINTER) as well as numeric literals.
2.2.5. Conditional Expressions
Conditional expressions are expressions which identify the circumstances under which a program may take an action or cease taking an action. As such, conditional expressions produce a value of TRUE
or FALSE
.
There are seven types of conditional expressions, as discussed in the following sections.
2.2.5.1. Condition Names
These are the simplest of all conditions. Observe the following code:
05 SHIRT-SIZE PIC 99V9. 88 TINY VALUE 0 THRU 12.5 88 XS VALUE 13 THRU 13.5. 88 S VALUE 14, 14.5. 88 M VALUE 15, 15.5. 88 L VALUE 16, 16.5. 88 XL VALUE 17, 17.5. 88 XXL VALUE 18, 18.5. 88 XXXL VALUE 19, 19.5. 88 VERY-LARGE VALUE 20 THRU 99.9.
The condition names TINY
, XS
, S
, M
, L
, XL
, XXL
, XXXL
and VERY-LARGE
will have TRUE
or FALSE
values based upon the values within their parent data item (SHIRT-SIZE
).
A program wanting to test whether or not the current SHIRT-SIZE
value can be classified as XL
could have that decision coded as a combined condition (the most complex type of conditional expression), as either:
IF SHIRT-SIZE = 17 OR SHIRT-SIZE = 17.5 - or - IF SHIRT-SIZE = 17 OR 17.5
Or it could simply utilize the condition name XL as follows:
IF XL
2.2.5.2. Class Conditions
Class-Condition Syntax
identifier-1 IS [ NOT ] { NUMERIC } ~~~ { ~~~~~~~ } { ALPHABETIC } { ~~~~~~~~~~ } { ALPHABETIC-LOWER } { ~~~~~~~~~~~~~~~~ } { ALPHABETIC-UPPER } { ~~~~~~~~~~~~~~~~ } { OMITTED } { ~~~~~~~ } { class-name-1 }
Class conditions evaluate the type of data that is currently stored in a data item.
- The
NUMERIC
class test considers only the characters ‘0’, ‘1’, … , ‘9’ to be numeric; only a data item containing nothing but digits will pass aNUMERIC
class test. Spaces, decimal points, commas, currency signs, plus signs, minus signs and any other characters except the digit characters will all failNUMERIC
class tests. - The
ALPHABETIC
class test considers only upper-case letters, lower-case letters and spaces to be alphabetic in nature. - The
ALPHABETIC-LOWER
andALPHABETIC-UPPER
class conditions consider only spaces and the respective type of letters to be acceptable in order to pass such a class test. - The
NOT
option reverses theTRUE
/FALSE
value of the condition. - Note that what constitutes a “letter” (or upper/lower case too, for that manner) may be influenced through the use of
CHARACTER CLASSIFICATION
specifications in theOBJECT-COMPUTER
(see OBJECT-COMPUTER) paragraph. - Only data items whose
USAGE
(see USAGE) is either explicitly or implicitly defined asDISPLAY
may be used inNUMERIC
or any of theALPHABETIC
class conditions. - Some COBOL implementations disallow the use of group items or
PIC A
items withNUMERIC
class conditions and the use ofPIC 9
items withALPHABETIC
class conditions. GnuCOBOL has no such restrictions. - The
OMITTED
class condition is used when it is necessary for a subprogram to determine whether or not a particular argument was passed to it. In such class conditions, identifier-1 must be a linkage section item defined on theUSING
clause of the subprogramsPROCEDURE DIVISION
header. See PROCEDURE DIVISION USING, for additional information.
The class-name-1 option allows you to test for a user-defined class. Here’s an example. First, assume the following SPECIAL-NAMES
(see SPECIAL-NAMES) definition of the user-defined class ‘Hexadecimal’:
SPECIAL-NAMES. CLASS Hexadecimal IS '0' THRU '9', 'A' THRU 'F', 'a' THRU 'f'.
Now observe the following code, which will execute the 150-Process-Hex-Value
procedure if Entered-Value
contains nothing but valid hexadecimal digits:
IF Entered-Value IS Hexadecimal PERFORM 150-Process-Hex-Value END-IF
2.2.5.3. Sign Conditions
Sign-Condition Syntax
identifier-1 IS [ NOT ] { POSITIVE } ~~~ { ~~~~~~~~ } { NEGATIVE } { ~~~~~~~~ } { ZERO } ~~~~
Sign conditions evaluate the numeric state of a data item defined with a PICTURE
(see PICTURE) and/or USAGE
(see USAGE) that supports numeric values.
- A
POSITIVE
orNEGATIVE
class condition will beTRUE
only if the value of identifier-1 is strictly greater than or less than zero, respectively. - A
ZERO
class condition can be passed only if the value of identifier-1 is exactly zero. - The
NOT
option reverses theTRUE
/FALSE
value of the condition.
2.2.5.4. Switch-Status Conditions
In the SPECIAL-NAMES
paragraph, an external switch name can be associated with one or more condition names. These condition names may then be used to test the ON/OFF status of the external switch.
Here are the relevant sections of code in a program named testprog, which is designed to simply announce if SWITCH-1
is on:
… ENVIRONMENT DIVISION. SPECIAL-NAMES. SWITCH-1 ON STATUS IS Switch-1-Is-ON. … PROCEDURE DIVISION. … IF Switch-1-Is-ON DISPLAY "Switch 1 Is On" END-IF …
The following are two different command window sessions — the left on a Unix/Cygwin/OSX system and the right on a windows system — that will set the switch on and then execute the testprog program. Notice how the message indicating that the program detected the switch was set is displayed in both examples:
$ COB_SWITCH_1=ON C:>SET COB_SWITCH_1=ON $ export COB_SWITCH_1 C:>testprog $ ./testprog Switch 1 Is On Switch 1 Is On C:> $
2.2.5.5. Relation Conditions
Relation-Condition Syntax
{ identifier-1 } IS [ NOT ] RelOp { identifier-2 } { literal-1 } ~~~ { literal-2 } { arithmetic-expression-1 } { arithmetic-expression-2 } { index-name-1 } { index-name-2 }
RelOp Syntax
{ EQUAL TO } { ~~~~~ } { EQUALS } { ~~~~~~ } { GREATER THAN } { ~~~~~~~ } { GREATER THAN OR EQUAL TO } { ~~~~~~~ ~~ ~~~~~ } { LESS THAN } { ~~~~ } { LESS THAN OR EQUAL TO } { ~~~~ ~~ ~~~~~ } { = } { > } { >= } { < } { <= }
These conditions evaluate how two different values "relate" to each other.
- When comparing one numeric value to another, the
USAGE
(see USAGE) and number of significant digits in either value are irrelevant as the comparison is performed using the actual algebraic values. - When comparing strings, the comparison is made based upon the program’s collating sequence. When the two string arguments are of unequal length, the shorter is assumed to be padded (on the right) with a sufficient number of spaces as to make the two strings of equal length. String comparisons take place on a corresponding character-by-character basis, left to right, until the
TRUE
/FALSE
value for the relation test can be established. Characters are compared according to their relative position in the program’sCOLLATING SEQUENCE
(as defined inSPECIAL-NAMES
(see SPECIAL-NAMES)), not according to the bit-pattern values the characters have in storage. - By default, the program’s
COLLATING SEQUENCE
will, however, be based entirely on the bit-pattern values of the various characters. - There is no functional difference between using the wordy version (
IS EQUAL TO
,IS LESS THAN
, …) versus the symbolic version (=
,<
, …) of the actual relation operators.
2.2.5.6. Combined Conditions
Combined Condition Syntax
[ ( ] Condition-1 [ ) ] { AND } [ ( ] Condition-2 [ ) ] { ~~~ } { OR } { ~~ }
A combined condition is one that computes a TRUE
/FALSE
value from the TRUE
/FALSE
values of two other conditions (which could themselves be combined conditions).
- If either condition has a value of
TRUE
, the result ofOR
ing the two together will result in a value ofTRUE
.OR
ing twoFALSE
conditions will result in a value ofFALSE
. - In order for
AND
to yield a value ofTRUE
, both conditions must have a value ofTRUE
. In all other circumstances,AND
produces aFALSE
value. - When chaining multiple, similar conditions together with the same operator (OR/AND), and left or right arguments have common subjects, it is possible to abbreviate the program code. For example:
IF ACCOUNT-STATUS = 1 OR ACCOUNT-STATUS = 2 OR ACCOUNT-STATUS = 7
Could be abbreviated as:
IF ACCOUNT-STATUS = 1 OR 2 OR 7
- Just as multiplication takes precedence over addition in arithmetic expressions, so does
AND
take precedence overOR
in combined conditions. Use parenthesis to change this precedence, if necessary. For example:FALSE AND FALSE OR TRUE AND TRUE
-
Evaluates to
TRUE
(FALSE AND FALSE) OR (TRUE AND TRUE)
-
Evaluates to
TRUE
(since AND has precedence over OR) - this is identical to the previous example (FALSE AND (FALSE OR TRUE)) AND TRUE
Evaluates to
FALSE
2.2.5.7. Negated Conditions
Negated Condition Syntax
NOT Condition-1 ~~~
A condition may be negated by prefixing it with the NOT
operator.
- The
NOT
operator has the highest precedence of all logical operators, just as a unary minus sign (which “negates” a numeric value) is the highest precedence arithmetic operator. - Parenthesis must be used to explicitly signify the sequence in which conditions are evaluated and processed if the default precedence isn’t desired. For example:
NOT TRUE AND FALSE AND NOT FALSE
-
Evaluates to
FALSE AND FALSE AND TRUE
which evaluates toFALSE
NOT (TRUE AND FALSE AND NOT FALSE)
-
Evaluates to
NOT (FALSE)
which evaluates toTRUE
NOT TRUE AND (FALSE AND NOT FALSE)
Evaluates to
FALSE AND (FALSE AND TRUE)
which evaluates toFALSE
2.2.6. Use of Periods
All COBOL implementations distinguish between sentences and statements in the procedure division. A Statement is a single executable COBOL instruction. For example, these are all statements:
MOVE SPACES TO Employee-Address ADD 1 TO Record-Counter DISPLAY "Record-Counter=" Record-Counter
Some COBOL statements have a scope of applicability associated with them where one or more other statements can be considered to be part of or related to the statement in question. An example of such a situation might be the following, where the interest on a loan is being calculated and displayed at 4% interest if the loan balance is under $10,000, and 4.5% otherwise. (WARNING: the following code has an error!):
IF Loan-Balance < 10000 MULTIPLY Loan-Balance BY 0.04 GIVING Interest ELSE MULTIPLY Loan-Balance BY 0.045 GIVING Interest DISPLAY "Interest Amount = " Interest
In this example, the IF
statement actually has a scope that can include two sets of associated statements: one set to be executed when the IF
(see IF) condition is TRUE
, and another if it is FALSE
.
Unfortunately, there’s a problem with the above. A human being looking at that code would probably infer that the DISPLAY
(see DISPLAY) statement, because of its lack of indentation, is to be executed regardless of the TRUE
/FALSE
value of the IF
condition. Unfortunately, the compiler (any COBOL compiler) won’t see it that way because it really couldn’t care less what sort of indentation, if any, is used. In fact, any COBOL compiler would be just as happy to see the code written like this:
IF Loan-Balance < 10000 MULTIPLY Loan-balance BY 0.04 GIVING Interest ELSE MULTIPLY Loan-Balance BY 0.045 GIVING Interest DISPLAY "Interest Amount = " Interest
How then do we inform the compiler that the DISPLAY
statement is outside the scope of the IF
?
That’s where sentences come in.
A COBOL Sentence is defined as any arbitrarily long sequence of statements, followed by a period (.) character. The period character is what terminates the scope of a set of statements. Therefore, our example should have been coded like this:
IF Loan-Balance < 10000 MULTIPLY Loan-Balance BY 0.04 GIVING Interest ELSE MULTIPLY Loan-Balance BY 0.045 GIVING Interest. DISPLAY "Interest Amount = " Interest
See the period at the end of the second MULTIPLY
(see MULTIPLY)? That is what terminates the scope of the IF
, thus making the DISPLAY
statement’s execution completely independent of the TRUE
/FALSE
status of the IF
.
2.2.7. Use of VERB/END-VERB Constructs
Prior to the 1985 COBOL standard, using a period character was the only way to signal the end of a statement’s scope.
Unfortunately, this caused some problems. Take a look at this code:
IF A = 1 IF B = 1 DISPLAY "A & B = 1" ELSE *> This ELSE has a problem! IF B = 1 DISPLAY "A NOT = 1 BUT B = 1" ELSE DISPLAY "NEITHER A NOR B = 1".
The problem with this code is that indentation — so critical to improving the human-readability of a program — can provide an erroneous view of the logical flow. An ELSE
is always associated with the most-recently encountered IF
; this means the emphasized ELSE
will be associated with the IF B = 1
statement, not the IF A = 1
statement as the indentation would appear to imply.
This sort of problem led to a band-aid solution being added to the COBOL language: the NEXT SENTENCE
clause:
IF A = 1 IF B = 1 DISPLAY "A & B = 1" ELSE NEXT SENTENCE ELSE IF B = 1 DISPLAY "A NOT = 1 BUT B = 1" ELSE DISPLAY "NEITHER A NOR B = 1".
NEXT SENTENCE
informs the compiler that if the B = 1
condition is false, control should fall into the first statement that follows the next period.
With the 1985 standard for COBOL, a much more elegant solution was introduced. Any COBOL Verb (the first reserved word of a statement) that needed such a thing was allowed to use an END-verb
construct to end its scope without disrupting the scope of any other statement it might have been in. Any COBOL 85 compiler would have allowed the following solution to our problem:
IF A = 1 IF B = 1 DISPLAY "A & B = 1" END-IF ELSE IF B = 1 DISPLAY "A NOT = 1 BUT B = 1" ELSE DISPLAY "NEITHER A NOR B = 1".
This new facility made the period almost obsolete, as our program segment would probably be coded like this today:
IF A = 1 IF B = 1 DISPLAY "A & B = 1" END-IF ELSE IF B = 1 DISPLAY "A NOT = 1 BUT B = 1" ELSE DISPLAY "NEITHER A NOR B = 1" END-IF END-IF
COBOL (GnuCOBOL included) still requires that each procedure division paragraph contain at least one sentence if there is any executable code in that paragraph, but a popular coding style is now to simply code a single period right before the end of each paragraph.
The standard for the COBOL language shows the various END-verb
clauses are optional because using a period as a scope-terminator remains legal.
If you will be porting existing code over to GnuCOBOL, you’ll find it an accommodating facility capable of conforming to whatever language and coding standards that code is likely to use. If you are creating new GnuCOBOL programs, however, I would strongly counsel you to use the END-verb
structures in those programs.
2.2.8. Concurrent Access to Files
The manipulation of data files is one of the COBOL language’s great strengths. There are features built into COBOL to deal with the possibility that multiple programs may be attempting to access the same file concurrently. Multiple program concurrent access is dealt with in two ways — file sharing and record locking.
Not all GnuCOBOL implementations support file sharing and record-locking options. Whether they do or not depends upon the operating system they were built for and the build options that were used when the specific GnuCOBOL implementation was generated.
2.2.8.1. File Sharing
GnuCOBOL controls concurrent-file access at the highest level through the concept of file sharing, enforced when a program attempts to open a file. This is accomplished via a UNIX operating-system routine called fcntl
. That module is not currently supported by Windows and is not present in the MinGW Unix-emulation package. GnuCOBOL builds created using a MinGW environment will be incapable of supporting file-sharing controls — files will always be shared in such environments. A GnuCOBOL build created using the Cygwin environment on Windows would have access to fcntl
and therefore will support file sharing. Of course, actual Unix builds of GnuCOBOL, as well as OSX builds, should have no issues because fcntl
should be available.
Any limitations imposed on a successful OPEN
(see OPEN) will remain in place until your program either issues a CLOSE
(see CLOSE) against the file or the program terminates.
File sharing is controlled through the use of a SHARING
clause:
SHARING WITH { ALL OTHER } ~~~~~~~ { ~~~ } { NO OTHER } { ~~ } { READ ONLY } ~~~~ ~~~~
This clause may be used either in the file’s SELECT
statement (see SELECT), on the OPEN
statement (see OPEN) which initiates your program’s use of the file, or both. If a SHARING
option is specified in both places, the specifications made on the OPEN
statement will take precedence over those from the SELECT
statement.
Here are the meanings of the three options:
ALL OTHER
-
When your program opens a file with this sharing option in effect, no restrictions will be placed on other programs attempting to
OPEN
the file after your program did. This is the default sharing mode. NO OTHER
-
When your program opens a file with this sharing option in effect, your program announces that it is unwilling to allow any other program to have any access to the file as long as you are using that file;
OPEN
attempts made in other programs will fail with a file status of 37 (PERMISSION DENIED
) until such time as youCLOSE
(see CLOSE) the file. READ ONLY
Opening a file with this sharing option indicates you are willing to allow other programs to
OPEN
the file for input while you have it open. If they attempt any otherOPEN
, theirs will fail with a file status of 37. Of course, your program may fail if someone else got to the file first and opened it with a sharing option that imposed file-sharing limitations.
If the SELECT
of a file is coded with a FILE STATUS
clause, OPEN
failures — including those induced by sharing failures — will be detectable by the program and a graceful recovery (or at least a graceful termination) will be possible. If no such clause was coded, however, a runtime message will be issued and the program will be terminated.
2.2.8.2. Record Locking
Record-locking is supported by advanced file-management software built-in to the GnuCOBOL implementation you are using. This software provides a single point-of-control for access to files — usually ORGANIZATION INDEXED
files. One such runtime package capable of doing this is the Berkeley Database (BDB) package — a package frequently used in GnuCOBOL builds to support indexed files.
The various I/O statements your program can execute are capable of imposing limitations on access by other concurrently-executing programs to the file record they just accessed. These limitations are syntactically imposed by placing a lock on the record using a LOCK
clause. Other records in the file remain available, assuming that file-sharing limitations imposed at the time the file was opened didn’t prevent access to the entire file.
- If the GnuCOBOL build you are using was configured to use the Berkeley Database (BDB) package for indexed file I/O, record locking will be available by using the
DB_HOME
run-time environment variable. - If the
SELECT
(see SELECT) statement or fileOPEN
(see OPEN) specifiesSHARING WITH NO OTHER
, record locking will be disabled. - If the file’s
SELECT
contains aLOCK MODE IS AUTOMATIC
clause, every time a record is read from the file, that record is automatically locked. Other programs may access other records within the file, but not a locked record. - If the file’s
SELECT
contains aLOCK MODE IS MANUAL
clause, locks are placed on records only when aREAD
statement executed against the file includes aLOCK
clause (this clause will be discussed shortly). - If the
LOCK ON
clause is specified in the file’sSELECT
, locks (either automatically or manually acquired) will continue to accumulate as more and more records are read, until they are explicitly released. This is referred to as multiple record locking.Locks acquired vie multiple record locking remain in-effect until the program holding the lock…
- If the
LOCK ON
clause is not specified, then the next I/O statement your program executes, except forSTART
(see START), will release the lock. This is referred to as single record locking. - A
LOCK
clause, which may be coded on aREAD
(see READ),REWRITE
(see REWRITE) orWRITE
statement (see WRITE) looks like this:{ IGNORING LOCK } { ~~~~~~~~ ~~~~ } { WITH [ NO ] LOCK } { ~~ ~~~~ } { WITH KEPT LOCK } { ~~~~ ~~~~ } { WITH IGNORE LOCK } { ~~~~~~ ~~~~ } { WITH WAIT } ~~~~
The
WITH [ NO ] LOCK
option is the only one available toREWRITE
orWRITE
statements.The meanings of the various record locking options are as follows:
IGNORING LOCK
- WITH IGNORE LOCK
-
These options (which are synonymous) inform GnuCOBOL that any locks held by other programs should be ignored.
WITH LOCK
-
Access to the record by other programs will be denied.
WITH NO LOCK
-
The record will not be locked. This is the default for all statements.
WITH KEPT LOCK
-
When single record locking is in effect, as a new record is accessed, locks held for previous records are released. By using this option, not only is the newly accessed record locked (as
WITH LOCK
would do), but prior record locks will be retained as well. A subsequentREAD
without theKEPT LOCK
option will release all “kept” locks, as will theUNLOCK
statement. WITH WAIT
-
This option informs GnuCOBOL that the program is willing to wait for a lock held (by another program) on the record being read to be released.
Without this option, an attempt to read a locked record will be immediately aborted and a file status of 51 will be returned.
With this option, the program will wait for a preconfigured time for the lock to be released. If the lock is released within the preconfigured wait time, the read will be successful. If the preconfigured wait time expires before the lock is released, the read attempt will be aborted and a 51 file status will be issued.
3. CDF - Compiler Directing Facility
The Compiler Directing Facility, or CDF, is a means of controlling the compilation of GnuCOBOL programs. CDF provides a mechanism for dynamically setting or resetting certain compiler switches, introducing new source code from one or more source code libraries, making dynamic source code modifications and conditionally processing or ignoring source statements altogether. This is accomplished via a series of special CDF statements and directives that will appear in the program source code.
When the compiler is operating in Fixed Format Mode, all CDF statements must begin in column eight (8) or beyond.
There are two types of supported CDF statements in GnuCOBOL — Text Manipulation Statements and Compiler Directives.
The CDF text manipulation statements COPY
and REPLACE
are used to introduce new code into programs either with or without changes, or may be used to modify existing statements already in the program. Text manipulation statements are always terminated with a period.
CDF directives, denoted by the presence of a >>
character sequence as part of the statement name itself, influence the process of program compilation.
Compiler directives are never terminated with a period.
The compiler command-line option -D offers additional control (see cobc - The GnuCOBOL Compiler).
3.1. >>CALL-CONVENTION
CDF >>CALL-CONVENTION Syntax
>>CALL-CONVENTION { COBOL } ~~~~~~~~~~~~~~~~~ { EXTERN } { STDCALL } { STATIC }
This directive instructs the compiler how to treat references to program names and may be used to determine other details for interacting with a function or program. There are four options with COBOL being the default.
COBOL
-
The program name is treated as a COBOL word that maps to the externalised name program to be called, cancelled or referenced in the program-address-identifier, applying the same mapping rules as for a program name for which no
AS
phrase is specified. (The is the default.) EXTERN
-
The program name is treated as an external reference.
STDCALL
-
[more info needed]
STATIC
The program name is called as a included element and not dynamically which is the normal default.
3.2. COPY
CDF COPY Statement Syntax
COPY copybook-name ~~~~ [ IN|OF library-name ] ~~ ~~ [ SUPPRESS PRINTING ] ~~~~~~~~ [ REPLACING { Phrase-Clause | String-Clause }... ] . ~~~~~~~~~
CDF COPY Phrase-Clause Syntax
{ ==pseudo-text-1== } BY { ==pseudo-text-2== } { identifier-1 } ~~ { identifier-2 } { literal-1 } { literal-2 } { word-1 } { word-2 }
CDF COPY String-Clause Syntax
[ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2== ~~~~~~~ ~~~~~~~~ ~~
-
COPY
statements are used to import copybooks (see Copybooks) into a program. -
COPY
statements may be used anywhere within a COBOL program where the code contained within the copybook would be syntactically valid. - The optional
SUPPRESS
clause (with or without the optionalPRINTING
reserved word) is valid syntactically but is non-functional. It is supported to facilitate compatibility with source code written for other versions of COBOL. - There is no difference between the use of the word
IN
and the wordOF
— use the one you prefer. - A period is absolutely mandatory at the end of every
COPY
statement, even if the statement occurs within the scope of another one where a period might appear disruptive, such as within the scope of anIF
(see IF) statement. This mandatory period at the end of the statement does not, however, affect the statement scope in which theCOPY
occurs. - Both pseudo-text-2 and partial-word-2 may be null.
- All
COPY
statements are located and the contents of the corresponding copybooks inserted into the program source code before the actual compilation process begins. If a copybook contains aCOPY
statement, the copybook insertion process will be repeated to resolve the embeddedCOPY
. This will continue until no unresolvedCOPY
statements remain. At that point, actual program compilation will begin. - See Locating Copybooks, for the specific rules on how copybooks are located by the compiler.
- The optional
REPLACING
clause allows for one or more of either of the following kinds of text replacements to be made:- Phrase-Clause
-
Replacement of one or more complete reserved words, user-defined identifiers or literals; the following points apply to this option:
- This option cannot be used to replace part of a word, identifier or literal.
- Whatever precedes the
BY
will be referred to here as the search string. - Single-item search strings can be specified by coding the
identifier-1
,literal-1
orword-1
being replaced. - Multiple-item search strings can be specified using the
==pseudo-text-1==
option. For example, to replace all occurrences ofUPON PRINTER
, you would specify==UPON PRINTER==
. - The replacement string, which follows the
BY
, may be specified using any of the four options. - If the replacement string is a multiple-item phrase or is to be deleted altogether, you must use the
==pseudo-text-2==
option. Ifpseudo-text-2
is null (in other words, the replacement text is specified as====
), all encountered occurrences of the search string will be deleted.
- String-Clause
Using this, you may replace character sequences that occur at the beginning (see
LEADING
) or end (seeTRAILING
) of reserved or user-defined words. For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", codeLEADING ==0100-== BY ==020-==
. To simply remove all "0100-" prefixes from words, codeLEADING ==0100-== BY ====
.
3.3. REPLACE
CDF REPLACE Statement (Format 1) Syntax
REPLACE [ ALSO ] { Phrase-Clause | String-Clause }... . ~~~~~~~ ~~~~
CDF REPLACE Statement (Format 2) Syntax
REPLACE [ LAST ] OFF . ~~~~~~~ ~~~~ ~~~
CDF REPLACE Phrase-Clause Syntax
{ ==pseudo-text-1== } BY { ==pseudo-text-2== } ~~
CDF REPLACE String-Clause Syntax
[ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2== ~~~~~~~ ~~~~~~~~ ~~
- The
REPLACE
statement provides a mechanism for changing all or part of one or more GnuCOBOL statements. - A period is absolutely mandatory at the end of every
REPLACE
statement (either format), even if the statement occurs within the scope of another one where a period might appear disruptive (such as within the scope of anIF
(see IF) statement; the period will not, however, affect the statement scope in which theREPLACE
occurs. - The following points apply to Format 1 of the
REPLACE
statement:- Format 1 of the
REPLACE
statement can be used to make changes to program source code in much the same way as theREPLACING
option of theCOPY
statement can, via these options:- Phrase-Clause
-
Replace one or more complete reserved words, user-defined identifiers or literals; the following points apply to this option:
- This option cannot be used to replace part of a word, identifier or literal.
- Whatever precedes the
BY
will be referred to here as the search string. - Search strings on
REPLACE
are always specified using the==pseudo-text-1==
option. For example, to replace all occurrences ofUPON PRINTER
, you would specify==UPON PRINTER==
. - The replacement string, which follows the
BY
, is specified using the==pseudo-text-2==
option. Ifpseudo-text-2
is null (in other words, the replacement text is specified as====
), all encountered occurrences of the search string will be deleted.
- String-Clause
Using this, you may replace character sequences that occur at the beginning (see
LEADING
) or end (seeTRAILING
) of reserved or user-defined words. For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", codeLEADING ==0100-== BY ==020-==
. To simply remove all "0100-" prefixes from words, codeLEADING ==0100-== BY ====
.
- Once a Format 1
REPLACE
statement is encountered in the currently-compiling source file, Replace Mode becomes active, and the change(s) specified by that statement will be automatically made on all subsequent source statements the compiler reads from the file. - Replace Mode remains in-effect — continuing to make source code changes — until another Format 1
REPLACE
is encountered, the end of currently compiling program source file is reached or a Format 2REPLACE
statement is encountered. - When a Format 1
REPLACE
statement with theALSO
keyword is encountered without Replace Mode being currently active, the effect will be as if theALSO
had not been specified. If Replace Mode already was in effect, the effect will be to “push” the current change specification(s) onto the top of a stack and add the specification(s) of the new statement to those that were already in effect. - When a Format 1
REPLACE
without theALSO
keyword is encountered, any stacked change specification(s), if any, will be discarded and the currently in-effect change specification(s), if any, will be replaced by those of the new statement. - When the end of the currently-compiling source file is reached, Replace Mode is deactivated and any stacked replace specifications will be discarded — compilation of the next source file (if any) will begin with Replace Mode inactive and no change specification(s) on the stack.
- Format 1 of the
- The following points apply to Format 2 of the
REPLACE
statement:- If Replace Mode is currently inactive, the Format 2
REPLACE
statement will be ignored. - If Replace Mode is currently active, a
REPLACE OFF.
will deactivate Replace Mode and discard any replace specification(s) on the stack. The compiler will henceforth operate as if noREPLACE
had ever been encountered, until such time as another Format 1REPLACE
is encountered. - If Replace Mode is currently active, a
REPLACE LAST OFF.
will replace the current replace specification(s) with those popped off the top of the stack. If there were no replace specification(s) on the stack, the effect will be as if aREPLACE OFF.
had been coded.
- If Replace Mode is currently inactive, the Format 2
3.4. >>DEFINE
CDF >>DEFINE Directive Syntax
>>DEFINE [ CONSTANT ] cdf-variable-1 AS { OFF } ~~~~~~~~ ~~~~~~~~ { ~~~ } { literal-1 [ OVERRIDE ] } { ~~~~~~~~ } { PARAMETER [ OVERRIDE ] } ~~~~~~~~~ ~~~~~~~~
Use the >>DEFINE
CDF directive to create CDF variables and (optionally) assign them either literal or environment variable values.
- The reserved word
AS
is optional and may be included, or not, at the discretion of the programmer. The presence or absence of this word has no effect upon the program. - CDF variables defined in this way become undefined once an
END PROGRAM
orEND FUNCTION
directive is encountered in the input source. - The
>>DEFINE
CDF directive is one way to create CDF variables that may be processed by other CDF statements such as>>IF
(see >>IF). The>>SET
CDF directive (see >>SET) provides another way to create them. - CDF variable names follow the rules for standard GnuCOBOL user-defined names, and may not duplicate any CDF reserved word. CDF variable names may duplicate COBOL reserved words, provided the
CONSTANT
option is not specified, but such names are not recommended. - The
CONSTANT
option is valid only in conjunction with literal-1. WhenCONSTANT
is specified, the CDF variable that is created may be used within your regular COBOL code as if it were a literal value. Without this option, the CDF variable may only be referenced on other CDF statements. TheOFF
option is used to create a variable without assigning it any value. - The
PARAMETER
option is used to create a variable whose value is that of the environment variable of the same name. Note that this value assignment occurs at compilation time, not program execution time. - In the absence of the
OVERRIDE
option, cdf-variable-1 must not yet have been defined. When theOVERRIDE
option is specified, cdf-variable-1 will be created with the specified value, if it had not yet been defined. If it had already been defined, it will be redefined with the new value.
3.5. >>IF
CDF >>IF Directive Syntax
>>IF CDF-Conditional-Expression-1 ~~~~ [ Program-Source-Lines-1 ] [ >>ELIF CDF-Conditional-Expression-2 ~~~~~~ [ Program-Source-Lines-2 ] ]... [ >>ELSE ~~~~~~ [ Program-Source-Lines-3 ] ] >>END-IF ~~~~~~~~
CDF-Conditional-Expression Syntax
{ cdf-variable-1 } IS [ NOT ] { DEFINED } { literal-1 } ~~~ { ~~~~~~~ } { SET } { ~~~ } { CDF-RelOp { cdf-variable-2 } } { { literal-2 } }
CDF-RelOp Syntax
>= or GREATER THAN OR EQUAL TO ~~~~~~~ ~~ ~~~~~ > or GREATER THAN ~~~~~~~ <= or LESS THAN OR EQUAL TO ~~~~ ~~ ~~~~~ < or LESS THAN ~~~~ = or EQUAL TO ~~~~~ <> or EQUAL TO (with "NOT") ~~~~~
The >>IF
CDF directive causes the GnuCOBOL compiler to process or ignore COBOL source statements, CDF text-manipulation statements and/or CDF directives depending upon the value of one or more conditional expressions based upon CDF variables.
- The reserved words
IS
,THAN
andTO
are optional and may be omitted. The presence or absence of these words has no effect on the program. - Each
>>IF
directive must be terminated by an>>END-IF
directive. - There may be any number of
>>ELIF
clauses following an>>IF
, including zero. - There may no more than one
>>ELSE
clause following an>>IF
. When>>ELSE
is used, it must follow the>>IF
and all>>ELIF
clauses. - Only one of the Program-Source-Lines-n block of statements that lie within the scope of the
>>IF
…>>END-IF
may be processed by the compiler. Which one (if any) that gets processed will be decided as follows:- Each CDF-Conditional-Expression-n will be evaluated, in turn, in the sequence in which they are coded in the >>IF statement and any
>>ELIF
clauses that may be present until one evaluates toTRUE
. Once one of them evaluates toTRUE
, the Program-Source-Lines-n block of code that corresponds to theTRUE
CDF-Conditional-Expression-n will be one that is processed. All others within the>>IF
->>END-IF
scope will be ignored. - If no CDF-Conditional-Expression evaluates to
TRUE
, and there is an>>ELSE
clause, the Program-Source-Lines-3 block of statements following the>>ELSE
clause will be processed by the compiler and all others within the>>IF
->>END-IF
scope will be ignored. - If no CDF-Conditional-Expression-n evaluates to
TRUE
and there is no>>ELSE
clause, then none of the Program-Source-Lines-n block of statements within the>>IF
->>END-IF
scope will be processed by the compiler. - If the Program-Source-Lines-n> statement block selected for processing is empty, no error results — there will just be no code generated from the
>>IF
->>END-IF
structure.
- Each CDF-Conditional-Expression-n will be evaluated, in turn, in the sequence in which they are coded in the >>IF statement and any
- A Program-Source-Lines-n block may contain any valid COBOL or CDF code.
- The following points pertain to any CDF-Conditional-Expression-n:
- The
DEFINED
option tests for whether cdf-variable-1 has been defined, but not yet assigned a value (>>DEFINE … OFF
); use theNOT
option to test for the variable not being defined. - The
SET
option tests for whether cdf-variable-1 has been given a value, either via a>>SET
statement or via a>>DEFINE
without theOFF
option. - Two CDF variables, two literals or a single CDF variable and a single literal may be compared against each other using a relational operator. Unlike the standard GnuCOBOL
IF
statement (see IF), multiple comparisons cannot beAND
ed orOR
ed together; you may nest a second>>IF
inside the first, however, to simulate anAND
and anOR
may be simulated via the>>ELIF
option. - The
<>
symbol stands forNOT EQUAL TO
.
- The
3.6. >>SET
CDF >>SET Directive Syntax
>>SET { [ CONSTANT ] cdf-variable-1 literal-1 ] } ~~~~~ { ~~~~~~~~ } { SOURCEFORMAT AS FIXED|FREE } { ~~~~~~~~~~~~ ~~~~~ ~~~~ } { NOFOLDCOPYNAME } { ~~~~~~~~~~~~~~ } { FOLDCOPYNAME AS UPPER|LOWER } ~~~~~~~~~~~~ ~~~~~ ~~~~~
The >>SET
CDF directive provides an alternate means of performing the actions of the >>DEFINE
and >>SOURCE
directives, as well as a means of controlling the compiler’s -free switch, -fixed switch and -ffold-copy switch from within program source code.
- The reserved word
AS
is optional (only on theSOURCEFORMAT
andFOLDCOPYNAME
clauses) and may be included, or not, at the discretion of the programmer. The presence or absence of this word has no effect upon the program. - CDF variables defined in this way become undefined once an
END PROGRAM
orEND FUNCTION
directive is encountered in the input source. - The
FOLDCOPYNAME
option provides the equivalent of specifying the compiler -ffold-copy=xxx switch, wherexxx
is eitherUPPER
orLOWER
. - The
NOFOLDCOPYNAME
option turns off the effect of either the>>SET FOLDCOPYNAME
statement or the compiler -ffold-copy=xxx switch. - If the
CONSTANT
option is used, literal-1 must also be used. This option provides another means of defining constants that may be used anywhere in the program that a literal could be specified. - The remaining options of the
>>SET
CDF directive provide equivalent functionality to the>>DEFINE
and>>SOURCE
directives, as follows:>>SET cdf-variable-1
-
>>DEFINE cdf-variable-1 AS OFF
>>SET cdf-variable-1 AS literal-1
-
>>DEFINE cdf-variable-1 AS literal-1
>>SET CONSTANT cdf-variable-1 literal-1
-
>>DEFINE CONSTANT cdf-variable-1 literal-1
>>SET SOURCEFORMAT AS FIXED
-
>>SOURCE FORMAT IS FIXED
>>SET SOURCEFORMAT AS FREE
-
>>SOURCE FORMAT IS FREE
>>SET XFD literal-1
-
[to do]
>>SET Micro-Focus-Directive
[to do]
3.7. >>SOURCE
CDF >>SOURCE Directive Syntax
>>SOURCE FORMAT IS FIXED|FREE|VARIABLE ~~~~~~~~ ~~~~~ ~~~~ ~~~~~~~~
The >>SOURCE
CDF directive puts the compiler into FIXED
or FREE
source-code format mode. This, in effect, provides yet another mechanism for controlling the compiler’s -free switch and -fixed switch.
- The reserved words
FORMAT
andIS
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - You may switch between
FIXED
andFREE
mode as desired. - You may also use the
>>SET
CDF directive to perform this function. - If the compiler is already in the specified mode, this statement will have no effect.
3.8. >>TURN
CDF >>TURN Directive Syntax
>>TURN { exception-name-1 [ file-name-1 ]... }... ~~~~~~ { OFF } { ~~~ } { CHECKING ON [ WITH LOCATION ] } ~~~~~~~~ ~~ ~~~~~~~~
The directive will (de-)activate exception checks.
3.9. >>D
CDF >>D Directive Syntax
>>D ~~~
The directive removes all floating debug lines if debug mode not active. Otherwise will ignore the directive part of the line.
3.10. >>DISPLAY
CDF >>DISPLAY Directive Syntax
>>DISPLAY source-text [ VCS = version-string ] ~~~~~~~~~ ~~~
The directive is a v1.0 extension and will display messages during compilation.
3.11. >>PAGE
CDF >>PAGE Directive Syntax
>>PAGE ~~~~~~
The directive allows usage of the IBM paging controls EJECT
, SKIP1
, SKIP2
, SKIP3
and TITLE
.
3.12. >>LISTING
CDF >>LISTING Directive Syntax
>>LISTING {ON} ~~~~~~~~~ {OFF}
The directive allows the program listing to be de-(activated).
3.13. >>LEAP-SECONDS
CDF >>LEAP-SECONDS Directive Syntax
>>LEAP-SECONDS ~~~~~~~~~~~~~~
The >>LEAP-SECONDS
CDF directive is syntactically recognized but is otherwise non-functional.
Allows for more than 60 seconds per minute.
3.14. $ Directives
CDF $ Directive Syntax
$ (Dollar) Directives - Active. These directives are active and have the same function as ones starting with >>: $DEFINE $DISPLAY ON|OFF $IF $ELIF $ELSE $ELSE-IF $END $SET It is recommend to use the standard directives only instead of the MF directives (when possible) as these have a a higher chance for being portable. $ (Dollar) Directives - Not Active. These are NOT active and will produce a warning message: $DISPLAY VCS ... Recognised but otherwise ignored. @OPTIONS options-text Additional Micro-Focus directives accepted : ADDRSV | ADD-RSV literal-1 ADDSYN | ADD-SYN literal-1 = literal-2 ASSIGN "EXTERNAL" | "DYNAMIC" BOUND CALLFH literal-1 COMP1 | COMP-1 "BINARY" | "FLOAT" FOLDCOPYNAME | FOLD-COPY-NAME AS "UPPER" | "LOWER" MAKESYN | MAKE-SYN NOBOUND | NO-BOUND NOFOLDCOPYNAME | NOFOLD-COPY-NAME | NO-FOLD-COPY-NAME OVERRIDE literal-1 = literal-2 REMOVE literal-1 SOURCEFORMAT | SOURCE-FORMAT "FIXED" | "FREE" | "VARIABLE" SSRANGE "2" NOSSRANGE | NO-SSRANGE
Offers support for MF Compiler Directives.
3.15. Predefined compilation variables
GnuCOBOL defines compilation variables when various conditions are true. If the condition associated with a variable is false, the variable is not defined.
DEBUG
-
The -d debug flag is specified.
EXECUTABLE
-
Module being compiled contains the main program.
GCCOMP
-
The size of a
COMP
item is determined according to the GnuCOBOL scheme where for a picture of length:- 1 - 2
-
item = 1 byte
- 3 - 4
-
item = 2 bytes
- 5 - 9
-
item = 4 bytes
- 10 - 18
item = 8 bytes
GNUCOBOL
-
GnuCOBOL is compiling the source unit.
HOSTSIGNS
-
A signed packed decimal item’s value may be considered
NUMERIC
if sign =X"F"
. IBMCOMP
-
The size of a COMP item is determined according to the IBM scheme, where for a
PICTURE
of length:- 1 - 4
-
item = 2 bytes
- 5 - 9
-
item = 4 bytes
- 10 - 18
item = 8 bytes
MODULE
-
The element being compiled does not contain the main program.
NOHOSTSIGNS
-
A signed packed decimal item’s value may not be considered
NUMERIC
if sign =X"F"
. NOIBMCOMP
-
The size of a
COMP
item is not determined according to the IBM scheme. NOSTICKY-LINKAGE
-
Sticky linkage (linkage section items remaining allocated between invocations) is not active.
NOTRUNC
-
Numeric data items are truncated according to their internal representation.
P64
-
Pointers are greater than 32 bits.
STICKY-LINKAGE
-
Sticky linkage (linkage section items remaining allocated between invocations) is active.
TRUNC
-
Numeric data items are truncated according to their
PICTURE
clauses.While still supported, this may well be removed in the future and should not be used. See
GCCOMP
andGNUCOBOL
instead: OCCOMP
-
The size of a
COMP
item is determined according to the GnuCOBOL scheme, where for aPICTURE
of length:- 1 - 2
-
item = 1 byte
- 3 - 4
-
item = 2 bytes
- 5 - 9
-
item = 4 bytes
- 10 - 18
item = 8 bytes
OPENCOBOL
GnuCOBOL is compiling the source unit.
4. IDENTIFICATION DIVISION
IDENTIFICATION DIVISION Syntax
[{ IDENTIFICATION } DIVISION. ] { ~~~~~~~~~~~~~~ } ~~~~~~~~ { ID } ~~ { PROGRAM-ID. } { program name } . { ~~~~~~~~~~ } { literal-1 } [ AS { literal-2 } ] [ Type-clause ] . { FUNCTION-ID. } { literal-3 } [ AS literal-4 ] . ~~~~~~~~~~~ { function-name } . { OPTIONS. } ~~~~~~~ [ DEFAULT ROUNDED MODE IS {AWAY-FROM-ZERO } ~~~~~~~ ~~~~~~~ {NEAREST-AWAY-FROM-ZERO } {NEAREST-EVEN } {NEAREST-TOWARDS-ZERO } {PROHIBITED } {TOWARDS-GREATER } {TOWARDS-LESSER } {TRUNCATION }] [ ENTRY-CONVENTION IS {COBOL } ~~~~~~~~~~~~~~~~ {EXTERN } {STDCALL }] [ AUTHOR. comment-1. ] ~~~~~~ [ DATE-COMPILED. comment-2. ] ~~~~~~~~~~~~~ [ DATE-MODIFIED. comment-3. ] ~~~~~~~~~~~~~ [ DATE-WRITTEN. comment-4. ] ~~~~~~~~~~~~ [ INSTALLATION. comment-5. ] ~~~~~~~~~~~~ [ REMARKS. comment-6. ] ~~~~~~~ [ SECURITY. comment-7. ] ~~~~~~~~
The AUTHOR
, DATE-COMPILED
, DATE-MODIFIED
, DATE-WRITTEN
, INSTALLATION
, REMARKS
and SECURITY
paragraphs are supported by GnuCOBOL only to provide compatibility with programs written for the ANS1974 (or earlier) standards. As of the ANS1985 standard, these clauses have become obsolete and should not be used in new programs.
PROGRAM-ID Type Clause Syntax
IS [ COMMON ] [ INITIAL|RECURSIVE PROGRAM ] ~~~~~~ ~~~~~~~ ~~~~~~~~~
The identification division provides basic identification of the program by giving it a name and optionally defining some high-level characteristics via the eight pre-defined paragraphs that may be specified.
- The paragraphs shown above may be coded in any sequence.
- The reserved words
AS
,IS
andPROGRAM
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - A Type Clause may be coded only when
PROGRAM-ID
is specified. If one is coded, eitherCOMMON
,COMMON INITIAL
orCOMMON RECURSIVE
must be specified. - While the actual
IDENTIFICATION DIVISION
orID DIVISION
header is optional, thePROGRAM-ID
/FUNCTION-ID
paragraphs are not; only one or the other, however, may be coded. - The compiler’s -Wobsolete switch will cause the GnuCOBOL compiler to issue warnings messages if these (or any other obsolete syntax) is used in a program.
- If specified, literal-1 must be an actual alphanumeric literal and may not be a figurative constant.
- The
PROGRAM-ID
andFUNCTION-ID
paragraphs serve to identify the program to the external (i.e. operating system) environment. If there is noAS
clause present, the program-id will serve as that external identification. If there is anAS
clause specified, that specified literal will serve as the external identification. For the remainder of this document, that "external identification" will be referred to as the primary entry-point name. - The
INITIAL
,COMMON
andRECURSIVE
words are used only within subprograms serving as subroutines. Their purposes are as follows:-
COMMON
should be used only within subprograms that are nested subprograms. A nested subprogram declared asCOMMON
may be called from any nested program in the source file being compiled, not just those "above" it in the nesting structure. - The
RECURSIVE
clause, if any, will cause the compiler to generate different object code for the subprogram that will enable it to invoke itself and to properly return back to the program that invoked it.User-defined functions (i.e.
FUNCTION-ID
) are always recursive. - The
INITIAL
clause, if specified, guarantees the subprogram will be in its initial (i.e. compiled) state each and every time it is executed, not just the first time.
-
5. ENVIRONMENT DIVISION
ENVIRONMENT DIVISION Syntax
ENVIRONMENT DIVISION. ~~~~~~~~~~~ ~~~~~~~~ [ CONFIGURATION SECTION. ] ~~~~~~~~~~~~~ ~~~~~~~~ [ SOURCE-COMPUTER. Compilation-Computer-Specification . ] ~~~~~~~~~~~~~~~ [ OBJECT-COMPUTER. Execution-Computer-Specification . ] ~~~~~~~~~~~~~~~ [ SPECIAL-NAMES. Program-Configuration-Specification . ] ~~~~~~~~~~~~~ [ REPOSITORY. Function-Specification... . ] ~~~~~~~~~~ [ INPUT-OUTPUT SECTION. ] ~~~~~~~~~~~~ ~~~~~~~ [ FILE-CONTROL. General-File-Description... . ] ~~~~~~~~~~~~ [ I-O-CONTROL. File-Buffering Specification... . ] ~~~~~~~~~~~
This division defines the external computer environment in which the program will be operating. This includes defining any files that the program may be .
- If both optional sections of this division are coded, they must be coded in the sequence shown.
- The paragraphs within the sections may be coded in any order.
- These sections consist of a series of specific, pre-defined, paragraphs (
SOURCE-COMPUTER
andOBJECT-COMPUTER
, for example), each of which serves a specific purpose. If no code is required for the purpose one of the paragraphs serves, the entire paragraph may be omitted. - If any of the paragraphs within one of the sections are coded, the section header itself must be coded.
- If none of the paragraphs within one of the sections are coded, the section header itself may be omitted.
- If none of the sections within the environment division are coded, the
ENVIRONMENT DIVISION.
header itself may be omitted.
5.1. CONFIGURATION SECTION
CONFIGURATION SECTION Syntax
CONFIGURATION SECTION. ~~~~~~~~~~~~~ ~~~~~~~ [ SOURCE-COMPUTER. Compilation-Computer-Specification . ] ~~~~~~~~~~~~~~~ [ OBJECT-COMPUTER. Execution-Computer-Specification . ] ~~~~~~~~~~~~~~~ [ SPECIAL-NAMES. Program-Configuration-Specification . ] ~~~~~~~~~~~~~ [ REPOSITORY. Function-Specification... . ] ~~~~~~~~~~
This section defines the computer system upon which the program is being compiled and executed and also specifies any special environmental configuration or compatibility characteristics.
- The four paragraphs in this section may be specified in any order but if not in this order, a warning will be issued.
- The configuration section is not allowed in a nested subprogram. A nested program inherits the configuration section settings of its parent program.
- If none of the features provided by the configuration section are required by a program, the entire
CONFIGURATION SECTION.
header may be omitted from the program.
5.1.1. SOURCE-COMPUTER
SOURCE-COMPUTER Syntax
SOURCE-COMPUTER. computer-name [ WITH DEBUGGING MODE ] . ~~~~~~~~~~~~~~~ ~~~~~~~~~ ~~~~
This paragraph defines the computer upon which the program is being compiled and provides one way in which debugging code embedded within the program may be activated.
- The reserved word
WITH
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - This paragraph is not allowed in a nested subprogram. A nested program inherits the
SOURCE-COMPUTER
settings of its parent program. - The value specified for computer-name is irrelevant, provided it is a valid COBOL word that does not match any GnuCOBOL reserved word. The computer-name value may include spaces. This need not match the computer-name used with the
OBJECT-COMPUTER
paragraph, if any. - The
DEBUGGING MODE
clause, if present, will inform the compiler that debugging lines (those with a ‘D’ in column 7 if Fixed Source Mode is in effect, or those prefixed with a>>D
if Free Source Mode is in effect) — normally treated as comments — are to be compiled. - Even without the
DEBUGGING MODE
clause, it is still possible to compile debugging lines. Debugging lines may also be compiled by specifying the -fdebugging-line switch to the GnuCOBOL compiler.
5.1.2. OBJECT-COMPUTER
OBJECT-COMPUTER Syntax
OBJECT-COMPUTER. [ computer-name ] ~~~~~~~~~~~~~~~ [ MEMORY SIZE IS integer-1 WORDS|CHARACTERS ] ~~~~~~ ~~~~ ~~~~~ ~~~~~~~~~~ [ PROGRAM COLLATING SEQUENCE IS alphabet-name-1 ] ~~~~~~~~~ [ SEGMENT-LIMIT IS integer-2 ] ~~~~~~~~~~~~~ [ CHARACTER CLASSIFICATION IS { locale-name-1 } ] ~~~~~~~~~~~~~~ { LOCALE } { ~~~~~~ } { USER-DEFAULT } { ~~~~~~~~~~~~ } { SYSTEM-DEFAULT } ~~~~~~~~~~~~~~ .
The MEMORY SIZE
and SEGMENT-LIMIT
clauses are syntactically recognized but are otherwise non-functional.
This paragraph describes the computer upon which the program will execute.
- The computer-name, if specified, must immediately follow the
OBJECT-COMPUTER
paragraph name. The remaining clauses may be coded in any sequence. - The reserved words
CHARACTER
,IS
,PROGRAM
andSEQUENCE
are optional and may be omitted. The presence or absence of these words has no effect on the program. - The value specified for computer-name, if any, is irrelevant provided it is a valid COBOL word that does not match any GnuCOBOL reserved word. The computer-name may include spaces. This need not match the computer-name used with the
SOURCE-COMPUTER
paragraph, if any. - The
OBJECT-COMPUTER
paragraph is not allowed in a nested subprogram. A nested program inherits theOBJECT-COMPUTER
settings of its parent program. - The
COLLATING SEQUENCE
clause allows you to specify a customized character collating sequence to be used when alphanumeric values are compared to one another. Data will still be stored in the character set native to the computer, but the logical sequence in which characters are ordered for comparison purposes can be altered from that defined by the computer’s native character set. The alphabet-name-1 you specify needs to be defined in theSPECIAL-NAMES
(see SPECIAL-NAMES) paragraph. - If no
COLLATING SEQUENCE
clause is specified, the collating sequence implied by the character set native to the computer (usually ASCII) will be used. - The optional
CLASSIFICATION
clause may be used to specify a locale for the environment in which the program will execute, for the purpose of influencing the upper-case and lower-case mappings of characters for theUPPER-CASE
(see UPPER-CASE) andLOWER-CASE
(see LOWER-CASE) intrinsic functions and the classification of characters for theALPHABETIC
,ALPHABETIC-LOWER
andALPHABETIC-UPPER
class tests. The definitions of these classes is taken from the cultural convention specification (LC_CTYPE
) from the specified locale.The meanings of the four locale specifications are as follows:
- locale-name-1 references a
LOCALE
(see SPECIAL-NAMES) definition. - The keyword
LOCALE
refers to the current locale (in effect at the time the program is executed) - The keyword
USER-DEFAULT
references the default locale specified for the user currently executing this program. - The keyword
SYSTEM-DEFAULT
denotes the default locale specified for the computer upon which the program is executing.
- locale-name-1 references a
- Absence of a
CLASSIFICATION
clause will cause character classification to occur according to the rules for the computer’s native character set (ASCII, EBCDIC, etc.).
5.1.3. SPECIAL-NAMES
SPECIAL-NAMES Syntax
SPECIAL-NAMES. ~~~~~~~~~~~~~ [ CALL-CONVENTION integer-1 IS mnemonic-name-1 ] ~~~~~~~~~~~~~~~ [ CONSOLE IS CRT ] ~~~~~~~ ~~~ [ CRT STATUS IS identifier-1 ] ~~~ ~~~~~~ [ CURRENCY SIGN IS literal-1 ] ~~~~~~~~ ~~~~ [ CURSOR IS identifier-2 ] ~~~~~~ [ DECIMAL-POINT IS COMMA ] ~~~~~~~~~~~~~ ~~~~~ [ EVENT STATUS IS identifier-3 ] ~~~~~ ~~~~~~ [ LOCALE locale-name-1 IS literal-2 ]... ~~~~~~ [ NUMERIC SIGN IS TRAILING SEPARATE ] ~~~~~~~ ~~~~ ~~~~~~~~ ~~~~~~~~ [ SCREEN CONTROL IS identifier-4 ] ~~~~~~ ~~~~~~~ [ device-name-1 IS mnemonic-name-2 ]... [ feature-name-1 IS mnemonic-name-3 ]... [ Alphabet-Clause ]... [ Class-Definition-Clause ]... [ Switch-Definition-Clause ]... [ Symbolic-Characters-Clause ]... .
The EVENT STATUS
and SCREEN CONTROL
clauses are syntactically recognized but are otherwise non-functional.
The SPECIAL-NAMES
paragraph provides a means for specifying various program and operating environment configuration options.
- The various clauses that may be specified within the
SPECIAL-NAMES
paragraph may be coded in any order. - The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The
SPECIAL-NAMES
paragraph is not allowed in a nested subprogram. A nested program inherits theSPECIAL-NAMES
settings of its parent program. - Only the final clause specified within this paragraph should be terminated with a period.
- The
CALL-CONVENTION
clause allows a decimal integer, representing a series of ON/OFF switch settings, to be associated with a mnemonic name which may then be coded on aCALL
statement (see CALL). The switch settings defined by this mnemonic will then control how the linkage to a subroutine invoked by theCALL
statement that references mnemonic-name-1 will be handled. - The
CONSOLE IS CRT
clause, if specified, will cause aDISPLAY
statement lacking an explicitUPON
clause to be treated as aDISPLAY screen-data-item
statement (see DISPLAY screen-data-item), and anyACCEPT
statement lacking aFROM
clause to be treated as aACCEPT screen-data-item
statement (see ACCEPT screen-data-item). - If the
CRT STATUS
clause is not specified, an implicitCOB-CRT-STATUS
identifier (with aPICTURE 9(4)
) will be allocated for the purpose of receiving screenACCEPT
statuses. IfCRT STATUS
is specified, then identifier-1 must be defined in the program as aPICTURE 9(4)
field. - The
CURRENCY SIGN
clause may be used to redefine the character to be used as a currency sign in aPICTURE
(see PICTURE) clause. The default currency sign is a dollar-sign (‘$’). You may specify any character except0
-9
,A
-Z
,a
-z
,+
,-
,,
,.
,*
,/
,;
,(
,)
,=
,\\
, quote (‘"’) or space. - The
CURSOR IS
clause allows you to specify a 4- or 6-character data item into which the cursor screen location at the time a screenACCEPT
is satisfied. The value will be returned as rrcc or rrrccc, depending upon the length of the specified identifier-2, where rr and rrr represent the row number (starting at zero) and cc and ccc represent the column number (also starting at zero). There is no default data item allocated for this data if theCURSOR IS
clause is not specified, and it is the programmer’s responsibility to define identifier-2 if the clause is specified. - The
DECIMAL POINT IS COMMA
clause reverses the definition of the ‘,’ and ‘.’ characters when they are used asPICTURE
editing symbols and within numeric literals. This can have unwanted side-effects - see Punctuation. - The
LOCALE
clause may be used to associate external OS-defined locale names (literal-2) with an internal name (locale-name-1) that may then be referenced within the program. Locale names are defined by the Operating System and/or C compiler GnuCOBOL will be utilizing on your computer. - The following is the list of possible locale codes, for example, that would be available on a Windows computer running a GnuCOBOL version that was built utilizing the MinGW Unix-emulator and the GNU C compiler (gcc):
- A
-
af_ZA, am_ET, ar_AE, ar_BH, ar_DZ, ar_EG, ar_IQ, ar_JO, ar_KW, ar_LB, ar_LY, ar_MA, ar_OM, ar_QA, ar_SA, ar_SY, ar_TN, ar_YE, arn_CL, as_IN, az_Cyrl_AZ, az_Latn_AZ
- B
-
ba_R, be_BY, bg_BG, bn_IN bo_BT, bo_CN, br_FR, bs_Cyrl_BA, bs_Latn_BA
- C
-
ca_ES, cs_CZ, cy_GB
- D
-
da_DK, de_AT, de_CH, de_DE, de_LI, de_LU, dsb_DE, dv_MV
- E
-
el_GR, en_029, en_AU, en_BZ, en_CA, en_GB, en_IE, en_IN, en_JM, en_MY en_NZ, en_PH, en_SG, en_TT, en_US, en_ZA, en_ZW, es_AR, es_BO, es_CL, es_CO, es_CR, es_DO, es_EC, es_ES, es_GT, es_HN, es_MX, es_NI, es_PA, es_PE, es_PR, es_PY, es_SV, es_US, es_UY es_VE, et_EE, eu_ES
- F
-
fa_IR, fi_FI, fil_PH, fo_FO, fr_BE, fr_CA, fr_CH, fr_FR, fr_LU, fr_MC, fy_NL
- G
-
ga_IE, gbz_AF, gl_ES, gsw_FR, gu_IN
- H
-
ha_Latn_NG, he_IL, hi_IN, hr_BA, hr_HR, hu_HU, hy_AM
- I
-
id_ID, ig_NG, ii_CN, is_IS, it_CH, it_IT, iu_Cans_CA, iu_Latn_CA
- J
-
ja_JP
- K
-
ka_GE, kh_KH, kk_KZ, kl_GL, kn_IN, ko_KR, kok_IN, ky_KG
- L
-
lb_LU, lo_LA, lt_LT, lv_LV
- M
-
mi_NZ, mk_MK, ml_IN, mn_Cyrl_MN, mn_Mong_CN moh_CA, mr_IN, ms_BN, ms_MY, mt_MT
- N
-
nb_NO, ne_NP, nl_BE, nl_NL, nn_NO, ns_ZA
- O
-
oc_FR, or_IN
- P
-
pa_IN, pl_PL, ps_AF, pt_BR, pt_PT
- Q
-
qut_GT, quz_BO, quz_EC, quz_PE
- R
-
rm_CH, ro_RO, ru_RU, rw_RW
- S
-
sa_IN, sah_RU, se_FI, se_NO se_SE, si_LK, sk_SK, sl_SI, sma_NO, sma_SE, smj_NO, smj_SE, smn_FI, sms_FI, sq_AL, sr_Cyrl_BA, sr_Cyrl_CS, sr_Latn_BA, sr_Latn_CS, sv_FI, sv_SE, sw_KE syr_SY
- T
-
ta_IN, te_IN, tg_Cyrl_TJ, th_TH tk_TM, tmz_Latn_DZ, tn_ZA, tr_IN, tr_TR, tt_RU
- U
-
ug_CN, uk_UA, ur_PK, uz_Cyrl_UZ, uz_Latn_UZ
- V
-
vi_VN
- W
-
wen_DE, wo_SN
- X
-
xh_ZA
- Y
-
yo_NG
- Z
zh_CN, zh_HK, zh_MO, zh_SG, zh_TW, zu_ZA
- The
NUMERIC SIGN TRAILING SEPARATE
specification causes all signed numericUSAGE DISPLAY
data items to be created as if theSIGN IS TRAILING SEPARATE CHARACTER
clause was included in their definitions. - The
device-name-1 IS mnemonic-name-2
clause allows you to specify an alternate name (device-name-1) for one of the built-in GnuCOBOL device name mnemonic-name-2. The list of device names built-into GnuCOBOL, and the physical device associated with that name, are as follows:CONSOLE
-
This is the (screen-mode) display of the PC or Unix system.
STDIN
SYSIN
SYSIPT
-
These devices (they are all synonymous) represent standard system input (pipe 0). On a PC or UNIX system, this is typically the keyboard. The contents of a file may be delivered to a GnuCOBOL program for access via one of these device names by adding the sequence ‘0< filename’ to the end of the programs execution command.
PRINTER
STDOUT
SYSLIST
SYSLST
SYSOUT
-
These devices (they are all synonymous) represent standard system output (pipe 1). On a PC or UNIX system, this is typically the display. Output sent to one of these devices by a GnuCOBOL program can be sent to a file by adding the sequence ‘1> filename’ to the end of the programs execution command.
STDERR
SYSERR
-
These devices (they are synonymous) represent standard system error output (pipe 2). On a PC or UNIX system, this is typically the display. Output sent to one of these devices by a GnuCOBOL program can be sent to a file by adding the sequence ‘2> filename’ to the end of the programs execution command.
- The
feature-name-1 IS mnemonic-name-3
clause allow for mnemonic names to be assigned to up to the 13 printer channel (i.e. vertical page positioning) position feature namesCnn
(nn=01-12
) andCSP
. Once a channel position has been assigned a mnemonic name, statements of the formWRITE record-name AFTER ADVANCING mnemonic-name-3
may be coded to write the specified print record at the channel position assigned to mnemonic-name-3.Printers supporting channel positioning are generally mainframe-type line printers. When writing to printers that do not support channel positioning, a formfeed will be issued to the printer.
The
CSP
positioning option stands for “No Spacing”. Testing on a MinGW build of GnuCOBOL shows that this too results in a formfeed being issued.
5.1.3.1. Alphabet-Name-Clause
SPECIAL-NAMES Alphabet-Clause Syntax
ALPHABET alphabet-name-1 IS { ASCII } ~~~~~~~~ { ~~~~~ } { EBCDIC } { ~~~~~~ } { NATIVE } { ~~~~~~ } { STANDARD-1 } { ~~~~~~~~~~ } { STANDARD-2 } { ~~~~~~~~~~ } { Literal-Clause... }
SPECIAL-NAMES ALPHABET Literal-Clause Syntax
literal-1 [ { THRU|THROUGH literal-2 } ] { ~~~~ ~~~~~~~ } { {ALSO literal-3}... } ~~~~
The ALPHABET
clause relates alphabet-name-1 to a specified character code set or collating sequence, including one you define yourself using the literal-1 option.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved words
THRU
andTHROUGH
are interchangeable. - GnuCOBOL considers
ASCII
,STANDARD-1
andSTANDARD-2
to be interchangeable. -
NATIVE
specifies the system default character set. - The following points apply to using the literal-n specifications to compose a custom character set:
- The literal-n values are either integers or alphanumeric quoted characters. These represent a single character in the
NATIVE
character set, either by its actual text value (alphanumeric quoted character) or by ordinal position in theNATIVE
character set (integer), - The sequence in which characters are defined in this clause specifies the relative order those characters should have when comparisons are made using this alphabet.
- Character positions in this list do not affect the actual binary storage values used for the characters. Binary values will still be those of the
NATIVE
character set. - You may specify any of the figurative constants
SPACE
,SPACES
,ZERO
,ZEROS
,ZEROES
,QUOTE
,QUOTES
,HIGH-VALUE
,HIGH-VALUES
,LOW-VALUE
orLOW-VALUES
for any of the literal-1, literal-2 or literal-3 specifications.
- The literal-n values are either integers or alphanumeric quoted characters. These represent a single character in the
- Once you have defined an alphabet name, that alphabet name may be used on specifications in
CODE-SET
,COLLATING SEQUENCE
, orSYMBOLIC CHARACTERS
clauses elsewhere in the program.
5.1.3.2. Class-Definition-Clause
SPECIAL-NAMES Class-Definition-Clause Syntax
CLASS class-name-1 IS { literal-1 [ THRU|THROUGH literal-2 ] }... ~~~~~ ~~~~ ~~~~~~~
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved words
THRU
andTHROUGH
are interchangeable. - Both literal-1 and literal-2 must be alphanumeric literals of length 1.
- The literal(s) specified on this clause define the possible characters that may be found in a data item’s value in order to be considered part of the class.
- For example, the following defines a class called
Hexadecimal
, the definition of which specifies the only characters that may be present in an alphanumeric data item if that data item is to be part of theHexadecimal
class:CLASS Hexadecimal IS '0' THRU '9' 'A' THRU 'F' 'a' THRU 'f'
- Once class
Hexadecimal
has been defined, program code could then use a statement such asIF input-item IS Hexadecimal
to determine if the value of characters in a data item are valid according to that class.
5.1.3.3. Switch-Definition-Clause
SPECIAL-NAMES Switch-Definition-Clause Syntax
switch-name-1 [ IS mnemonic-name-1 ] [ ON STATUS IS condition-name-1 ] ~~ [ OFF STATUS IS condition-name-2 ] ~~~
The switch-definition clause associates a condition-name with a run-time execution switch so that the status of that switch may be tested from within a program.
- The reserved words
IS
andSTATUS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The valid switch-name-1 names are
SWITCH-n
(n
= 0-36). - If the program is compiled with the -fsyntax-extension switch, the switch names
SWn
(n
= 0-15) are also valid; they correspond toSWITCH-0
throughSWITCH-15
, respectively as well asSWITCH-16
throughSWITCH-36
,SWITCH 0
throughSWITCH 26
andSWITCH A
throughSWITCH Z
. - At execution time, each switch will be associated with a
COB_SWITCH_n
run-time environment variable, wheren
will have the value ‘0’ through ‘15’. Any of these sixteen environment variables that have the valueON
(regardless of upper- or lower-case value) will be considered to be set “on”. Any of these sixteen environment variables having no value at all or a value other thanON
will be consideredOFF
. - Each specified switch must have at least one of a
IS mnemonic-name-1
,ON STATUS
or anOFF STATUS
option defined for it, otherwise there will be no way to reference the switch from within a GnuCOBOL program. - The
IS mnemonic-name-1
syntax provides a means for setting the switch to either anON
orOFF
value via theSET
statement (see SET). - The
ON STATUS
andOFF STATUS
syntax provides a way of associating a condition-name with either the on or off status of the switch, so that status may be tested at execution time via theIF
statement (see IF).
5.1.3.4. Symbolic-Characters-Clause
SPECIAL-NAMES-Symbolic-Characters-Clause Syntax
SYMBOLIC CHARACTERS ~~~~~~~~ { symbolic-character-1... IS|ARE integer-1... }... [ IN alphabet-name-1 ] ~~
This clause may be used to define your own figurative constants.
- The reserved words
ARE
,CHARACTERS
andIS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. -
There must be exactly as many integer-1 values specified as there are symbolic-character-1 names.
- Each symbolic character name will be associated with the corresponding integer-1th character in the alphabet named in the
IN
clause. The integer values are selecting characters from the alphabet by their ordinal position and not by their numeric value; thus, an integer of 15 will select the 15th character in the specified alphabet, regardless of the actual numeric value of the bit pattern that constitutes that character. - If no alphabet-name-1 is specified, the systems native character set will be assumed.
- The following two code examples define the same set of figurative constant names for five ASCII control characters (assuming that ASCII is the system’s native character set). The two examples are identical in their effects, even though the way the figurative constants are defined is different.
- Individually
-
SYMBOLIC CHARACTERS NUL IS 1 SOH IS 2 BEL IS 8 DC1 IS 18 DC2 IS 19
- Respectively
-
SYMBOLIC CHARACTERS NUL SOH BEL DC1 DC2 ARE 1 2 8 18 19
5.1.4. REPOSITORY
REPOSITORY Syntax
REPOSITORY. ~~~~~~~~~~ FUNCTION { function-prototype-name-1 [ AS literal-1 ] }... ~~~~~~~~ { ~~ } { intrinsic-function-name-1 [ AS literal-2 ] } { ~~ } { intrinsic-function-name-2 INTRINSIC } { ALL INTRINSIC ~~~~~~~~~ } ~~~ ~~~~~~~~~
The REPOSITORY paragraph provides a way to control access to the various built-in intrinsic functions and any user defined functions that your program will be using.
- The
REPOSITORY
paragraph is not allowed in a nested subprogram. A nested program inherits theREPOSITORY
settings of its parent program. - The
INTRINSIC
clause allows you to flag one or more (orALL
) built-in intrinsic functions as being usable without the need to code the keywordFUNCTION
in front of the function names. - As an alternative to using the
ALL INTRINSIC
clause, you may instead compile your GnuCOBOL programs using the -fintrinsics=ALL switch. - The function-prototype-name-1 option is required to specify the name of a user-defined function your program will be using. Optionally, should you desire, you may specify an alias name by which you will reference that user-defined function. Should you wish, you may also use the
AS
clause to provide an alias name for a built-in intrinsic function. - The following example
- enables all intrinsic functions to be specified without the use of the
FUNCTION
keyword, - names two user-defined functions named
MY-FUNCTION-1
andMY-FUNCTION-2
that will be used by the program and - specifies the alias names
SIGMA
for the intrinsic functionSTANDARD-DEVIATION
andMF2
forMY-FUNCTION-2
.
REPOSITORY. FUNCTION ALL INTRINSIC. FUNCTION MY-FUNCTION-1. FUNCTION MY-FUNCTION-2 AS "MF2". FUNCTION STANDARD-DEVIATION AS "SIGMA".
- enables all intrinsic functions to be specified without the use of the
A special note about user-defined functions — because you must name a user-defined function that your program will be using in the REPOSITORY
paragraph, you may always reference that function from your program’s procedure division without needing to use the FUNCTION
keyword.
5.2. INPUT-OUTPUT SECTION
INPUT-OUTPUT SECTION Syntax
[ INPUT-OUTPUT SECTION. ] ~~~~~~~~~~~~ ~~~~~~~ [ FILE-CONTROL. ] ~~~~~~~~~~~~ [ SELECT-Statement... ] [ I-O-CONTROL. ] ~~~~~~~~~~~ [ MULTIPLE-FILE-Statement ] [ SAME-RECORD-Statement ]
The INPUT-OUTPUT
section provides for the definition of any files the program will be accessing as well as control of the I/O buffering process against those files through the FILE-CONTROL
and I-O-CONTROL
paragraphs, respectively.
- As the diagram shows, there are three types of statements that may occur in the two paragraphs of this section. If none of the statements are coded in a particular paragraph, the paragraph itself may be omitted, otherwise it is required.
- If neither paragraph is coded, the
INPUT-OUTPUT SECTION.
header itself may be omitted, otherwise it is normally required. - If the compiler configuration file (see Compiler Configuration Files) you are using has
relaxed-syntax-check
set to ‘yes’, theFILE-CONTROL
andI-O-CONTROL
paragraphs may be specified without theINPUT-OUTPUT SECTION
header having been coded. - If both statement types are coded in the
I-O-CONTROL
paragraph, the order in which those statements are coded is irrelevant.
5.2.1. SELECT
SELECT Statement Syntax
SELECT [ [ NOT ] OPTIONAL ] file-name-1 ~~~~~~ ~~~ ~~~~~~~~ [ ASSIGN { TO } [{ EXTERNAL }] [{ DISC|DISK }] [{ identifier-1 }] ] ~~~~~~ { USING } { ~~~~~~~~ } { ~~~~ ~~~~ } { word-1 } { DYNAMIC } { DISPLAY } { literal-1 } ~~~~~~~ { ~~~~~~~ } { KEYBOARD } { ~~~~~~~~ } { LINE ADVANCING } { ~~~~ ~~~~~~~~~ } { PRINTER } { ~~~~~~~ } { RANDOM } { ~~~~~~ } { TAPE } ~~~~ [ COLLATING SEQUENCE IS alphabet-name-1 ] ~~~~~~~~~ [ FILE|SORT ] STATUS IS identifier-2 [ identifier-3 ] ] ~~~~ ~~~~ ~~~~~~ [ LOCK MODE IS { MANUAL|AUTOMATIC } ] ~~~~ { ~~~~~~ ~~~~~~~~~ } { EXCLUSIVE [ WITH { LOCK ON MULTIPLE RECORDS } ] } ~~~~~~~~~ { ~~~~ ~~ ~~~~~~~~ ~~~~~~~ } { LOCK ON RECORD } { ~~~~ ~~ ~~~~~~ } { ROLLBACK } { ~~~~~~~~ } [ ORGANIZATION Clause ] ~~~~~~~~~~~~ [ ORGANISATION Clause ] ~~~~~~~~~~~~ [ RECORD DELIMITER IS STANDARD-1 ] ~~~~~~ ~~~~~~~~~ ~~~~~~~~~~ [ RESERVE integer-1 AREAS ] ~~~~~~~ [ SHARING WITH { ALL OTHER } ] ~~~~~~~ { ~~~ } { NO OTHER } { ~~ } { READ ONLY } ~~~~ ~~~~
The COLLATING SEQUENCE
, RECORD DELIMITER
, RESERVE
and ALL OTHER
clauses are syntactically recognized but are otherwise non-functional.
The SELECT
statement creates a definition of a file and links that COBOL definition to the external operating system environment.
- The reserved words
AREAS
,IS
,MODE
,OTHER
,SEQUENCE
,TO
,USING
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - After file-name-1, the various clauses may be coded in any sequence.
- A period must follow the last coded clause.
- The
OPTIONAL
clause, to be used only for files that will be used to provide input data to the program, indicates the file may or may not actually be available at run-time. Attempts toOPEN
anOPTIONAL
file when the file does not exist will receive a special non-fatal file status value (see status 05 in the list of file status values below) indicating the file is not available; a subsequent attempt toREAD
that file will return anAT END
(end-of-file) condition. Optionally, files may be designated asNOT OPTIONAL
, if desired. This is useful when specifying the compiler’s -foptional-file switch, which automatically makes all filesOPTIONAL
except for those explicitly declared asNOT OPTIONAL
. - The file-name-1 value that you specify will be the name by which you will reference the file within your program. This name should be formed according to the rules for user-defined names (see User-Defined Words).
- The optional
ASSIGN
clause specifies how — at runtime, when file-name-1 is opened — either a logical device (STDIN
,STDOUT
) or a file anywhere in one of the currently-mounted file systems will be associated with file-name-1, as follows:- There are three components to the
ASSIGN
clause:Type
-
EXTERNAL
,DYNAMIC
or neither Device
-
the list of device choices
Locator
shown as a choice between identifier-1, word-1 and literal-1.
-
ASSIGN TO DISC file-name-1
will be assumed if there is noASSIGN
clause on aSELECT
. - If an
ASSIGN
clause is coded without a Device, the deviceDISC
will be assumed. - If a Locator clause is coded, the COBOL file file-name-1 will be attached to a data file within any file system that is mounted and available to the executing program at the time file-name-1 is opened. How that file is identified varies, depending upon the specified Locator, as follows:
- If literal-1 is coded, the value of the literal will serve as the File Location String that will identify the data file.
- If identifier-1 is coded, the value of the identifier will serve as the File Location String that will identify the data file.
- If word-1 (a syntactically valid word not duplicating a reserved or user-defined word) is coded, and a Type is
EXTERNAL
, then word-1 itself will serve as the File Location String that will identify the data file. If, however, a Type ofEXTERNAL
was not specified, the compiler will create aPIC X(1024)
data item named word-1 within the program; the contents of that data item at the time the program opens file-name-1 will then serve as the File Location String that will identify the data file. - File Location Strings will be discussed shortly.
- If no Locator is coded, file-name-1 will be attached to a logical device or a file based upon the specified (or implied) Device, as follows:
-
DISC
orDISK
will assume an attachment to a file named file-name-1 in whatever directory is current at the time the file is opened. -
DISPLAY
will assume an attachment to theSTDOUT
logical device; these files should only be used for output. -
KEYBOARD
will assume an attachment to theSTDIN
logical device; these files should only be used for input. -
PRINTER
will assume an attachment to theLPT1
logical device/port; these files should only be used for output. -
RANDOM
orTAPE
will behave exactly asDISC
does. These two additional Devices are provided to facilitate the compilation of COBOL source from other COBOL implementations.
-
- The
LINE ADVANCING
device requires that a Locator be specified; these files should only be used for output. A COBOL Line Advancing file will allow carriage-control characters such as line-feeds and form-feeds to be written to the attached operating system file, via theADVANCING
clause of theWRITE
statement (see WRITE). - File Location Strings are used (at runtime) to identify the path and filename to the data file that must be attached to file-name-1 when that file is opened.
- If the compiler configuration file (see Compiler Configuration Files) you used to compile the program with had a
filename-mapping
value ofyes
, the GnuCOBOL runtime system will first attempt to identify a currently-defined environment variable whose value will serve as the data file’s path and filename, as follows:- If the compiler configuration file (see Compiler Configuration Files) (see Compiler Configuration Files) you used to compile the program specified
mf
as theassign-clause
value, then the File Locator String will be interpreted according to Microfocus COBOL rules — namely, everything before the last ‘-’ in the File Locator String will be ignored; the characters after the last ‘-’ will be treated as the base of an environment variable name. If there is no ‘-’ character in the File Locator String then the entire File Locator String will serve as the base of an environment variable name. This is the default behaviour for every config file exceptibm
. - If, on the other hand, the compiler configuration file (see Compiler Configuration Files) you used to compile the program specified
mf
as theassign-clause
value, then the File Locator String will be interpreted according to according to IBM COBOL rules — namely, the File Locator String is expected to be of the formS-xxx
orAS-xxx
, in which case the xxx will be treated as the base of an environment variable name. If there is no ‘-’ character in the File Locator String then the entire File Locator String will serve as the base of an environment variable name. - Once an environment variable name base (let’s refer to it as
bbbb
) has been determined, the runtime system will look for the first one of the following environment variables that exists, in this sequence:DD_bbbb
dd_bbbb
bbbb
Windows systems are case-insensitive with regard to environment variables, so there is no difference between the first two when using a GnuCOBOL implementation built for either Windows/MinGW or native Windows.
If an environment variable was found, its value will serve as the path and filename to the data file.
- If the compiler configuration file (see Compiler Configuration Files) (see Compiler Configuration Files) you used to compile the program specified
- If no environment variable was found, or the configuration file (see Compiler Configuration Files) used to compile the program had a
filename-mapping
value ofNO
, then the File Locator String value will serve as the path and filename to the data file. - Paths and file names may be specified on an absolute (
C:\\Data\\datafile.dat
,/Data/datafile.dat
, …) or relative to the current directory (Data\\datafile.dat
,Data/datafile.dat
, …) basis. If no directory name is included (datafile.dat
), the file must be in the current directory.
- There are three components to the
- The
FILE STATUS
orSORT STATUS
clause (they are both equivalent and only one or the other, if any, should be specified) is used to specify the name of a two-digit numeric data item into which an I/O status code will be saved after every I/O verb that is executed against the file. This does not actually allocate the data item — you must define the item yourself somewhere in the data division. Note that the following list is not definitive: more can be added and any tests should include one for non zeros as a catch all. Possible status codes that can be returned to aFILE STATUS
data item are as follows:00
-
Success
02
-
Success (Duplicate Record Key Written)
04
-
Success (Incomplete)
05
-
Success (Optional File Not Found)
07
-
Success (No Unit)
10
-
End of file reached if reading forward or beginning-of-file reached if reading backward
14
-
Out of key range
21
-
Key invalid
22
-
Key already exists
23
-
Key not found
24
-
Key boundary violation
30
-
Permanent I/O error
31
-
Inconsistent filename
34
-
Boundary violation
35
-
File not found
37
-
Permission denied
38
-
Closed with lock
39
-
Conflicting attribute
41
-
File already open
42
-
File not open
43
-
Read not done
44
-
Record overflow
46
-
Read error
47
-
OPEN INPUT
denied (insufficient permissions to read file) 48
-
OPEN OUTPUT
denied (insufficient permissions to write to file) 49
-
OPEN I-O
denied (insufficient permissions to read and/or write file) 51
-
Record locked
52
-
End of page
57
-
LINAGE
bad specification (I-O linage) 61
-
File sharing failure
71
-
Bad character
91
File not available
- The
SHARING
clause defines the conditions under which the program will be willing (or not) to allow other programs executing at the same time to access the file. See File Sharing, for the details. - The
LOCK
clause defines how concurrent access to the file will be managed on a record-by-record basis. See Record Locking, for the details. - For syntax details for the
ORGANIZATION
clause, see next group of paragraphs. - A
SELECT
statement without anORGANIZATION
explicitly coded will be handled as if the following ORGANIZATION clause had been specified:ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL
5.2.1.1. ORGANIZATION SEQUENTIAL
ORGANIZATION SEQUENTIAL Clause Syntax
[ ORGANIZATION|ORGANISATION IS ] RECORD BINARY SEQUENTIAL ~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~~~ [ ACCESS MODE IS SEQUENTIAL ] ~~~~~~ ~~~~~~~~~~
Files declared as ORGANIZATION SEQUENTIAL
will consist of records with no explicit end-of-record delimiter character sequences; records in such files are “delineated” by a calculated byte-offset (based on the maximum record length) into the file.
- The reserved words
BINARY
,IS
,MODE
andRECORD
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
ORGANIZATION
andORGANISATION
are interchangeable. - The phrase
ORGANIZATION IS
(and its internationalized alternative,ORGANISATION IS
) is optional to provide compatibility with those (few) COBOL implementations that considerORGANIZATION
to be optional. Most COBOL implementations do require the wordORGANIZATION
, so it should be used in new programs. - These files cannot be prepared with any standard text-editing or word processing software as all such programs will embed delimiter characters at the end of records (use
ORGANIZATION IS LINE SEQUENTIAL
instead). - These files may contain either
USAGE DISPLAY
orUSAGE COMPUTATIONAL
(of any variety) data since no binary data sequence can be accidentally interpreted as an end-of-record delimiter. - While records in a
ORGANIZATION SEQUENTIAL
file may be defined as having variable-length records, the file will be structured in such a manner as to reserve space for each record equal to the size of the largest possible record, based on the file’s description in theFILE SECTION
. - The
ACCESS MODE SEQUENTIAL
clause is optional because, if absent, it will be assumed anyway for this type of file. The internal structure of these files is such that they can only be processed in a sequential manner; in order to read the 100th record in such a file, for example, you first must read records 1 through 99. - Sequential files are processed using the following statements:
5.2.1.2. ORGANIZATION LINE SEQUENTIAL
ORGANIZATION LINE SEQUENTIAL Clause Syntax
[ ORGANIZATION|ORGANISATION IS ] LINE SEQUENTIAL ~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~ ~~~~~~~~~~ [ ACCESS MODE IS SEQUENTIAL ] ~~~~~~ ~~~~~~~~~~ [ PADDING CHARACTER IS literal-1 | identifier-1 ] ~~~~~~~
The PADDING CHARACTER
clause is syntactically recognized but is otherwise non-functional.
Files declared as ORGANIZATION LINE SEQUENTIAL
will consist of records terminated by an end-of-record delimiter character or character sequence.
- The reserved words
CHARACTER
,IS
andMODE
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
ORGANIZATION
andORGANISATION
are interchangeable. - The phrase
ORGANIZATION IS
(and its internationalized alternative,ORGANISATION IS
) is optional to provide compatibility with those (few) COBOL implementations that consider that word to be optional. Most COBOL implementations do require the wordORGANIZATION
, so it should be used in new programs. - This is the only
ORGANIZATION
valid for files that are assigned to thePRINTER
device. - These files may be created with any standard text-editing or word processing software capable of writing text files. Such files should not contain any
USAGE COMPUTATIONAL
orBINARY
(of any variety) data since such fields could accidentally contain byte sequences that could be interpreted as an end-of-record delimiter. - Both fixed- and variable-length record formats are supported.
- The end-of-record delimiter sequence will be
X‘0A’
(an ASCII line-feed character) or aX‘0D0A’
(an ASCII carriage-return + line-feed sequence). The former is used on Unix implementations of GnuCOBOL (including Windows/MinGW, Windows/Cygwin and OSX implementations) while the latter would be used with native Windows implementations. - When reading a
LINE SEQUENTIAL
file, records in excess of the size implied by the file’s description in theFILE SECTION
will be truncated while records shorter than that size will be padded to the right withSPACES
. - The
ACCESS MODE SEQUENTIAL
clause is optional because, if absent, it will be assumed anyway for this type of file. The internal structure of these files is such that the data can only be processed in a sequential manner; in order to read the 100th record in such a file, for example, you first must read records 1 through 99. - Files assigned to
PRINTER
orCONSOLE
should be specified asORGANIZATION LINE SEQUENTIAL
. - Line Sequential files are processed using the following statements:
5.2.1.3. ORGANIZATION RELATIVE
ORGANIZATION RELATIVE Clause Syntax
[ ORGANIZATION|ORGANISATION IS ] RELATIVE ~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~ [ ACCESS MODE IS { SEQUENTIAL } ] ~~~~~~ { ~~~~~~~~~~ } { DYNAMIC } { ~~~~~~~ } { RANDOM } ~~~~~~ [ RELATIVE KEY IS identifier-1 ] ~~~~~~~~
These files are files with an internal organization such that records may be processed in a sequential manner based upon their physical location in the file or in a random manner by allowing records to be read, written or updated by specifying the relative record number in the file.
- The reserved words
IS
,KEY
andMODE
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
ORGANIZATION
andORGANISATION
are interchangeable. - The phrase
ORGANIZATION IS
(and its internationalized alternative,ORGANISATION IS
) is optional to provide compatibility with those (few) COBOL implementations that consider that word to be optional. Most COBOL implementations do require the wordORGANIZATION
, so it should be used in new programs. -
ORGANIZATION RELATIVE
files cannot be assigned to theCONSOLE
,DISPLAY
,LINE ADVANCING
orPRINTER
devices. - The
RELATIVE KEY
clause is optional only ifACCESS MODE SEQUENTIAL
is specified. - While an
ORGANIZATION RELATIVE
file may be defined as having variable-length records, the file will be structured in such a manner as to reserve space for each record equal to the size of the largest possible record as defined by the file’s description in theFILE SECTION
. -
ACCESS MODE SEQUENTIAL
, the defaultACCESS MODE
if none is specified, indicates that the records of the file will be processed in a sequential manner, according to their physical sequence in the file. -
ACCESS MODE RANDOM
means that records will be processed in random sequence by specifying their record number in the file every time the file is read or written. -
ACCESS MODE DYNAMIC
indicates the program may switch back and forth betweenSEQUENTIAL
andRANDOM
mode during execution. The file starts out initially inSEQUENTIAL
mode when first opened but the program may use theSTART
statement (see START) to switch between sequential and random access. - The
RELATIVE KEY
data item is a numeric data item that cannot be defined as a field within records of this file. Its purpose is to return the current relative record number of a relative file that is being processed inSEQUENTIAL
access mode and to serve as a key that specifies the relative record number to be read or written when processing a relative file inRANDOM
access mode. - Relative files are processed using the following statements:
5.2.1.4. ORGANIZATION INDEXED
ORGANIZATION INDEXED Clause Syntax
[ ORGANIZATION|ORGANISATION IS ] INDEXED ~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~ [ ACCESS MODE IS { SEQUENTIAL } ] ~~~~~~ { ~~~~~~~~~ } { DYNAMIC } { ~~~~~~~ } { RANDOM } ~~~~~~ [ RECORD KEY IS { [ data-name-1 ] ~~~~~~ { [ record-key-name-1 ] [ =|{SOURCE IS} data-name-2 ] ... ] } ~~~~~~ [ ALTERNATE RECORD KEY IS { [ data-name-3 ] ~~~~~~~~~ ~~~~~~ { [ record-key-name-2 ] [ =|{SOURCE IS} data-name-4 ] ... ] } ~~~~~~ [ WITH DUPLICATES ] ]... ~~~~~~~~~~ [ SUPPRESS WHEN ALL literal ] ~~~~~~~~~~~~~~~~~ [ SUPPRESS WHEN SPACES | ZEROES ] ~~~~~~~~~~~~~~~~~~~~ ~~~~~~
Indexed files, like relative files, may have their records processed in either a sequential or random manner. Unlike relative files, however, the actual location of a record in an indexed file is calculated automatically based upon the value(s) of one or more alphanumeric fields within records of the file. For example, an indexed file containing product data might use the product identification code as a record key. This means you may read, write or update the A6G4328
th record or the Z8X7723
th record directly, based upon the product id value of those records!
- The reserved words
IS
,KEY
andMODE
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
ORGANIZATION
andORGANISATION
are interchangeable. - The phrase
ORGANIZATION IS
(and its internationalized alternative,ORGANISATION IS
) is optional to provide compatibility with those (few) COBOL implementations that consider that word to be optional. Most COBOL implementations do require the wordORGANIZATION
, so it should be used in new programs. -
ORGANIZATION INDEXED
files cannot be assigned toCONSOLE
,DISPLAY
,KEYBOARD
,LINE ADVANCING
orPRINTER
. -
ACCESS MODE SEQUENTIAL
, the defaultACCESS MODE
if none is specified, indicates that the records of the file will be processed in a sequential manner with respect to the values of theRECORD KEY
or theALTERNATE RECORD KEY
most-recently referenced on aSTART
statement (see START). -
ACCESS MODE RANDOM
means that records will be processed in random sequence by accessing the record with specific record key or alternate record key values. -
ACCESS MODE DYNAMIC
allows the file will be processed either inRANDOM
orSEQUENTIAL
mode; the program may switch between the two modes as needed. TheSTART
statement is used to make the switch between modes. - The
RECORD KEY
clause defines the field within the record used to provide the primary access to records within the file. No two records in the file will be allowed to have the samePRIMARY KEY
field value. TheSOURCE IS
clause is for use withSplit Keys
. - The
ALTERNATE RECORD KEY
clause, if used, defines an additional field within the record that provides an alternate means of directly accessing records or an additional field by which the file’s contents may be processed sequentially. You have the choice of allowing records to have duplicate alternate key values, if necessary. - There may be multiple
ALTERNATE RECORD KEY
clauses, each defining an additional alternate key for the file. - Usage of the
SUPPRESS WHEN
clause is used whenSparse Keys
are required which may take the form for a literal or spaces or zeroes. - Indexed files are processed using the following statements:
5.2.2. SAME RECORD AREA
I-O-CONTROL SAME AREA Syntax
SAME { SORT-MERGE } AREA FOR file-name-1... . ~~~~ { ~~~~~~~~~~ } { SORT } { ~~~~ } { RECORD } ~~~~~~
The SAME SORT-MERGE
and SAME SORT
clauses are syntactically recognized but are otherwise non-functional.
The SAME RECORD AREA
clause allows you to specify that multiple files should share the same input and output memory buffers.
- The reserved words
AREA
andFOR
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - This statement must be terminated with a period.
- While coding only a single file name (the repeated file-name-1 item) is syntactically valid, this statement will have no effect upon the program unless at least two files are specified.
- The effect of this statement will be to cause the specified files to share the same I/O buffer in memory. These buffers can sometimes get quite large, and by having multiple files share the same buffer memory you may significantly cut down the amount of memory the program is using (thus making “room” for more procedural code or data). If you do use this feature, take care to ensure that no more than one of the specified files are ever OPEN simultaneously.
5.2.3. MULTIPLE FILE
I-O-CONTROL MULTIPLE FILE Syntax
MULTIPLE FILE TAPE CONTAINS ~~~~~~~~ { file-name-1 [ POSITION integer-1 ] }... ~~~~~~~~ .
The MULTIPLE FILE TAPE
clause is obsolete and is therefore recognized but not functional.
6. DATA DIVISION
DATA DIVISION Syntax
DATA DIVISION. ~~~~ ~~~~~~~~ [ FILE SECTION. ~~~~ ~~~~~~~ { File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ] { { 01-Level-Constant } } { { 78-Level-Constant } } { 01-Level-Constant } { 78-Level-Constant } [ WORKING-STORAGE SECTION. ~~~~~~~~~~~~~~~ ~~~~~~~ [ { WORKING-STORAGE-SECTION-Data-Item } ]... ] { 01-Level-Constant } { 78-Level-Constant } [ LOCAL-STORAGE SECTION. ~~~~~~~~~~~~~ ~~~~~~~ [ { LOCAL-STORAGE-SECTION-Data-Item } ]... ] { 01-Level-Constant } { 78-Level-Constant } [ LINKAGE SECTION. ~~~~~~~ ~~~~~~~ [ { LINKAGE-SECTION-Data-Item } ]... ] { 01-Level-Constant } { 78-Level-Constant } [ REPORT SECTION. ~~~~~~ ~~~~~~~ { Report-Description [ { Report-Group-Definition } ]... }... ] { { 01-Level-Constant } } { { 78-Level-Constant } } { 01-Level-Constant } { 78-Level-Constant } [ SCREEN SECTION. ~~~~~~ ~~~~~~~ [ { SCREEN-SECTION-Data-Item } ]... ] { 01-Level-Constant } { 78-Level-Constant }
All data used by any COBOL program must be defined in one of the six sections of the data division, depending upon the purpose of the data.
- If no data will be described in one of the data division sections, that section header may be omitted.
- If no data division sections are needed, the
DATA DIVISION.
header itself may be omitted. - If more than one section is needed in the data division (a common situation), the sections must be coded in the sequence they are presented above.
6.1. Data Definition Principles
GnuCOBOL data items, like those of other COBOL implementations, are described in a hierarchical manner. This accommodates the fact that data items frequently need to be able to be broken up into subordinate items. Take for example, the following logical layout of a portion of a data item named Employee
:
Employee | Additional :----------------:----------------:--> Data Items ... | | Employee-name Employment-Dates | | :---------:-------------: :-------:-------: | | | | | Last-Name First-Name Middle-Initial From-Date To-Date | | :----:----: :----:----: | | | | | | Year Month Day Year Month Day
The Employee
data item consists of two subordinate data items — an Employee-Name
and an Employment-Dates
data item (presumably there would be a lot of others too, but we don’t care about them right now). As the diagram shows, each of those data items are, in turn, broken down into subordinate data items. This hierarchy of data items can get rather deep
, and GnuCOBOL, like other COBOL implementations, can handle up to 49 levels of such hierarchical structures.
As was presented earlier (see Structured Data), a data item that is broken down into other data items is referred to as a group item, while one that isn’t broken down is called an elementary item.
COBOL uses the concept of a level number to indicate the level at which a data item occurs in a data structure such as the example shown above. When these data items are defined, they are all defined together with a number in the range 1-49 specified in front of their names. Over the years, a convention has come to exist among COBOL programmers that level numbers are always coded as two-digit numbers — they don’t need to be specified as two-digit numbers, but every example you see in this document will take that approach!
The data item at the top, also referred to as a record, always has a level number of 01. After that, you may assign level numbers as you wish (01–02–03–04…, 01–05–10–15…, etc.), as long as you follow these simple rules:
- Every data item at the same level of a hierarchy diagram such as the one you see here (if you were to make one, which you rarely will, if ever, once you get used to this concept) must have the same level number.
- Every new level uses a level number that is strictly greater than the one used in the parent (next higher) level.
- When describing data hierarchies, you may never use a level number greater than 49 (except for 66, 77, 78 and 88 which have very special meanings (see Special Data Items).
So, the definition of these data items in a GnuCOBOL program would go something like this:
01 Employee 05 Employee-Name 10 Last-Name 10 First-Name 10 Middle-Initial 05 Employment-Dates 10 From-Date 15 Year 15 Month 15 Day 10 To-Date 15 Year 15 Month 15 Day
The indentation is purely at the discretion of the programmer to make things easier for humans to read (the compiler couldn’t care less). Historically, COBOL implementations that required Fixed Format Mode source programs required that the 01
level number begin in Area A and that everything else begins in Area B. GnuCOBOL only requires that all data definition syntax occur in columns 8-72. In Free Format Mode, of course, there aren’t even those limitations.
Did you notice that there are two each of Year
, Month
and Day
data names defined? That’s perfectly legal, provided that each can be uniquely qualified
so as to be distinct from the other. Take for example the Year
items. One is defined as part of the From-Date
data item while the other is defined as part of the To-Date
data item. In COBOL, we would actually code references to these two data items as either Year OF From-Date
and Year OF To-Date
or Year IN From-Date
and Year IN To-Date
(COBOL allows either IN
or OF
to be used). Since these references would clarify any confusion to us as to which Year
might be referenced, the GnuCOBOL compiler won’t be confused either.
The coding example shown above is incomplete; it only describes the data item names and their hierarchical relationships to one other. In addition, any valid data item definitions will also need to describe what type of data is to be contained in a data item (Numeric? Alphanumeric? Alphabetic?), how much data can be held in the data item and a multitude of other characteristics.
When group items are being defined, subordinate items may be assigned the “name” FILLER
. There may be any number of FILLER
items defined within a group item. A data item named FILLER
cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item. Note that it is possible that the name of the group item itself might be specified as FILLER
if there is no need to ever refer directly to the group structure itself.
6.2. FILE SECTION
FILE SECTION Syntax
[ FILE SECTION. ~~~~ ~~~~~~~ { File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ] { { 01-Level-Constant } } { { 78-Level-Constant } } { 01-Level-Constant } { 78-Level-Constant }
Every file that has been referenced by a SELECT
statement (see SELECT) must also be described in the file section of the data division.
Files destined for use as sort/merge work files must be described with a Sort/Merge File Description (SD
) while every other file is described with a File Description (FD
). Each of these descriptions will almost always be followed with at least one record description.
6.2.1. File/Sort-Description
File/Sort-Description Syntax
FD|SD file-name-1 [ IS EXTERNAL|GLOBAL ] ~~ ~~ ~~~~~~~~ ~~~~~~ [ BLOCK CONTAINS [ integer-1 TO ] integer-2 CHARACTERS|RECORDS ] ~~~~~ ~~ ~~~~~~~~~~ ~~~~~~~ [ CODE-SET IS alphabet-name-1 ] ~~~~~~~~ [ DATA { RECORD IS } identifier-1... ] ~~~~ { ~~~~~~ } { RECORDS ARE } ~~~~~~~ [ LABEL { RECORD IS } OMITTED|STANDARD ] ~~~~~ { ~~~~~~ } ~~~~~~~ ~~~~~~~~ { RECORDS ARE } ~~~~~~~ [ LINAGE IS integer-3 | identifier-2 LINES ~~~~~~ [ LINES AT BOTTOM integer-4 | identifier-3 ] ~~~~~~ [ LINES AT TOP integer-5 | identifier-4 ] ~~~ [ WITH FOOTING AT integer-6 | identifier-5 ] ] ~~~~~~~ [ RECORD { CONTAINS [ integer-7 TO ] integer-8 CHARACTERS } ] ~~~~~~ { ~~ } { IS VARYING IN SIZE } { ~~~~~~~ } { [ FROM [ integer-7 TO ] integer-8 CHARACTERS } { ~~ } { DEPENDING ON identifier-6 ] } ~~~~~~~~~ [ RECORDING MODE IS recording-mode ] ~~~~~~~~~ [ { REPORT IS } report-name-1... ] { ~~~~~~ } { REPORTS ARE } ~~~~~~~ [ VALUE OF implementor-name-1 IS literal-1 | identifier-7 ] . ~~~~~ ~~
The BLOCK CONTAINS
, DATA RECORD
, LABEL RECORD
, RECORDING MODE
and VALUE OF
clauses are syntactically recognized but are obsolete and non-functional. These clauses should not be coded in new programs.
- The reserved words
ARE
,AT
,CHARACTERS
(RECORD
clause only),CONTAINS
,FROM
,IN
,IS
,ON
andWITH
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - The terms
RECORD IS
andRECORDS ARE
are interchangeable. - The terms
REPORT IS
andREPORTS ARE
are interchangeable. - Only files intended for use as work files for either the
SORT
(see SORT) orMERGE
(see MERGE) statements should be coded with an SD — all others should be defined with a FD. - The sequence in which files are defined via
FD
orSD
, as compared to the sequence in which theirSELECT
statements were coded, is irrelevant. - The name specified as file-name-1 must exactly match the name specified on the file’s
SELECT
statement. - The
CODE-SET
clause allows a custom alphabet, defined in theSPECIAL-NAMES
(see SPECIAL-NAMES) paragraph, to be associated with a file. This clause is valid only when used with sequential or line sequential files. - The
LINAGE
clause may only be specified in theFD
of a sequential or line sequential file. If used with a sequential file, the organization of that file will be implicitly changed to line sequential. The various components of theLINAGE
clause define the layout of printed pages as follows:- LINES AT TOP
-
Number of unused (i.e. left blank) lines at the top of every page. The default if this if not specified is zero.
- LINES AT BOTTOM
-
Number of unused (i.e. left blank) lines at the bottom of every page. The default if this if not specified is zero.
- LINAGE IS n LINES
-
Total number of used/usable lines on the page.
- The sum of the previous three specifications should be the total number of possible lines available on one printed page.
- FOOTING AT
-
Line number beyond which nothing may be printed except for any footing that is to appear on every page. The default for this if not specified is zero, meaning there will be no footings. This value cannot be larger than the
LINAGE IS n LINES
value.
- This page structure — once defined — can be automatically enforced by the
WRITE
statement (see WRITE). - Specifying a
LINAGE
clause in anFD
will cause theLINAGE-COUNTER
special register to be created for the file. This automatically-created data item will always contain the current relative line number on the page being prepared which will serve as the starting point for aWRITE
statement. - The
RECORD CONTAINS
andRECORD IS VARYING
clauses are ignored (with a warning message issued) when used with line sequential files. With other file organizations, these mutually-exclusive clauses define the length of data records within the file. The data item specified as identifier-6 must be defined within one of the record descriptions of file-name-1. - The
REPORT IS
clause announces to the compiler that the file will be dedicated to the Report Writer Control System (RWCS); the clause names one or more reports, each to be described in the report section. The following special rules apply when theREPORT
clause is used:- The clause may only be specified in the
FD
of a sequential or line sequential file. If used with a sequential file, the organization of that file will be implicitly changed to line sequential. - The
FD
cannot be followed by record descriptions. Detailed descriptions of data to be printed to the file will be defined in theREPORT SECTION
(see REPORT SECTION). - If a
LINAGE
clause is also specified, Values specified forLINAGE IS
andFOOTING AT
will be ignored. The values ofLINES AT BOTTOM
andLINES AT TOP
, if any, will be honoured.
- The clause may only be specified in the
- The following special rules apply only to sort/merge work files:
- Sort/merge work files should be assigned to
DISK
(orDISC
) on theirSELECT
statements. - Sorts and merges will be performed in memory, if the amount of data being sorted allows.
- Should actual disk work files be necessary due to the amount of data being sorted or merged, they will be automatically allocated to disk in a folder defined by:
- The
TMPDIR
run-time environment variable (see Run Time Environment Variables) - The
TMP
run-time environment variable - The
TEMP
run-time environment variable
(in that order).
- The
- These disk files will be automatically purged upon
SORT
orMERGE
termination. They will also be purged if the program terminates abnormally before theSORT
orMERGE
finishes. Should you ever need to know, temporary sort/merge work files will be named cob*.tmp. - If you specify a specific filename in the sort/merge work file’s
SELECT
, it will be ignored.
- Sort/merge work files should be assigned to
- See Data Description Clauses, for information on the
EXTERNAL
andGLOBAL
options.
6.2.2. FILE-SECTION-Data-Item
FILE-SECTION-Data-Item Syntax
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ] ~~~~~~ ~~~~~~ ~~~~~~~~ [ BLANK WHEN ZERO ] ~~~~~ ~~~~ [ JUSTIFIED RIGHT ] ~~~~ [ OCCURS [ integer-1 TO ] integer-2 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-2 ] ~~~~~~~~~ [ ASCENDING|DESCENDING KEY IS identifier-3 ] ~~~~~~~~~ ~~~~~~~~~~ [ INDEXED BY identifier-4 ] ] ~~~~~~~ [ PICTURE IS picture-string ] ~~~ [ REDEFINES identifier-5 ] ~~~~~~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE [CHARACTER] ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ [ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] ~~~~ ~~~~ ~~~~ ~~~~~ [ USAGE IS data-item-usage ] . [ FILE-SECTION-Data-Item ]... ~~~~~
The LEFT
and RIGHT
(SYNCRONIZED) clauses are syntactically recognized but are otherwise non-functional.
Every sort file description (SD
or FD
) must be followed by at least one 01-level data item, except for file descriptions containing the REPORT IS
clause. These 01-level data items, in turn, may be broken down into subordinate group and elementary items. An 01-level data item defined here in the file section is also known as a Record, even if it is an elementary item, provided that elementary item lacks the CONSTANT
attribute.
- The reserved words
BY
,IS
,KEY
,ON
andWHEN
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - The reserved words
SYNCRONIZED
andSYNCRONIZED
are interchangeable. Both may be abbreviated toSYNC
. - The reserved word
PICTURE
may be abbreviated toPIC
. - As the syntax diagram shows, the definition of a FILE-SECTION-Data-Item is a recursive one in that there may be any number of such specifications coded following a FD or SD. The first such specification must have a level number of 01, and will describe a specific format of data record within the file. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of the record. The definition of a record is terminated when one of the following occurs:
- Another 01-level item is found
-
signifies the start of another record layout for the file.
- Another
FD
orSD
is found -
marks the completion of the detailed description of the file and begins another.
- A division or section header is found
also marks the completion of the detailed description of the file and signifies the end of the file section as well.
- Every FILE-SECTION-Data-Item description must be terminated with a period.
- If there are multiple record descriptions present for a given
FD
orSD
, the one with the longest length will define the size of the record buffer into which aREAD
statement (see READ) or aRETURN
statement (see RETURN) will deliver data read from the file and from which aWRITE
statement (see WRITE) orRELEASE
statement (see RELEASE) statement will obtain the data to be written to the file. - The various 01-level record descriptions for a file description implicitly share that one common record buffer (thus, they provide different ways to view the structure of data that can exist within the file). Record buffers can be shared between files by using the
SAME RECORD AREA
(see SAME RECORD AREA) clause. - The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 66, 77, 78 and 88 all have special uses — See Special Data Items, for details.
- Not specifying an identifier-1 or
FILLER
immediately after the level number has the same effect as ifFILLER
were specified. A data item namedFILLER
cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it. -
EXTERNAL
cannot be combined withGLOBAL
orREDEFINES
. - File section data buffers (and therefore all 01-level record layouts defined in the file section) are initialized to all binary zeros when the program is loaded into storage.
- See Data Description Clauses, for information on the usage of the various data description clauses.
6.3. WORKING-STORAGE SECTION
WORKING-STORAGE-SECTION-Data-Item Syntax
level-number [ identifier-1 | FILLER ] [ IS GLOBAL | EXTERNAL ] ~~~~~~ ~~~~~~ ~~~~~~~~ [ BASED ] ~~~~~ [ BLANK WHEN ZERO ] ~~~~~ ~~~~ [ JUSTIFIED RIGHT ] ~~~~ [ OCCURS [ integer-1 TO ] integer-2 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-2 ] ~~~~~~~~~ [ ASCENDING|DESCENDING KEY IS identifier-3 ] ~~~~~~~~~ ~~~~~~~~~~ [ INDEXED BY identifier-4 ] ] ~~~~~~~ [ PICTURE IS picture-string ] ~~~ [ REDEFINES identifier-5 ] ~~~~~~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ [ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] ~~~~ ~~~~ ~~~~ ~~~~~ [ USAGE IS data-item-usage ] ~~~~~ [ VALUE IS [ ALL ] literal-1 ] . [ WORKING-STORAGE-SECTION-Data-Item ]... ~~~~~ ~~~
The LEFT
and RIGHT
(SYNCRONIZED) clauses are syntactically recognized but are otherwise non-functional.
The working-storage section is used to describe data items that are not part of files, screens or reports and whose data values persist throughout the execution of the program.
- The reserved words
BY
,CHARACTER
,IS
,KEY
,ON
,RIGHT
(JUSTIFIED),TIMES
andWHEN
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - The reserved words
SYNCRONIZED
andSYNCHRONISED
are interchangeable. Both may be abbreviated asSYNC
. - The reserved word
PICTURE
may be abbreviated toPIC
. - The reserved word
JUSTIFIED
may be abbreviated toJUST
. - As the syntax diagram shows, the definition of a
WORKING-STORAGE-SECTION-Data-Item
is a recursive one in that there may be any number of such specifications coded following one another. The first such specification must have a level number of 01. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of a record. The definition of a record is terminated when one of the following occurs:- Another 01-level item is found — this signifies the end of the definition of one record and the start of a another.
- A 77-level item is found — this signifies the end of the definition of the record and begins the definition of a special data item; See 77-Level Data Items, for more information.
- A division or section header is found — this also marks the completion of a record and signifies the end of the working-storage section as well.
- Every
WORKING-STORAGE-SECTION-Data-Item
description must be terminated with a period. - The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 49 are used to define data items that may be part of a hierarchical structure. Level number 01 can also be used to define a constant — an item with an unchangeable value specified at compilation time.
- Level numbers 66, 77, 78 and 88 all have special uses — See Special Data Items, for details.
- Not specifying an identifier-1 or
FILLER
immediately after the level number has the same effect as ifFILLER
were specified. A data item namedFILLER
cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it. - Data items defined within the working-storage section are automatically initialized once — as the program in which the data is defined is loaded into memory. Subprograms may be loaded into memory more than once (see the
CANCEL
statement (see CANCEL)), in which case initialization will happen each time they are loaded. See Data Initialization, for a discussion of the initialization rules. - See Data Description Clauses, for information on the usage of the various data description clauses.
6.4. LOCAL-STORAGE SECTION
LOCAL-STORAGE-SECTION-Data-Item Syntax
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ] ~~~~~~ ~~~~~~ ~~~~~~~~ [ BASED ] ~~~~~ [ BLANK WHEN ZERO ] ~~~~~ ~~~~ [ JUSTIFIED RIGHT ] ~~~~ [ OCCURS [ integer-1 TO ] integer-2 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-2 ] ~~~~~~~~~ [ ASCENDING|DESCENDING KEY IS identifier-3 ] ~~~~~~~~~ ~~~~~~~~~~ [ INDEXED BY identifier-4 ] ] ~~~~~~~ [ PICTURE IS picture-string ] ~~~ [ REDEFINES identifier-5 ] ~~~~~~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ [ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] ~~~~ ~~~~ ~~~~ ~~~~~ [ USAGE IS data-item-usage ] ~~~~~ [ VALUE IS [ ALL ] literal-1 ] . [ LOCAL-STORAGE-SECTION-Data-Item ]... ~~~~~ ~~~
The LEFT
and RIGHT
(SYNCRONIZED) clauses are syntactically recognized but are otherwise non-functional.
The local-storage section is similar to working-storage, but describes data within a subprogram that will be dynamically allocated and initialized (automatically) each time the subprogram is executed. See Data Initialization, for the rules of data initialization.
- The reserved words
BY
,CHARACTER
IS
,KEY
,ON
,RIGHT
(JUSTIFIED),TIMES
andWHEN
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - The reserved words
SYNCRONIZED
andSYNCHRONISED
are interchangeable. Both may be abbreviated asSYNC
. - The reserved word
PICTURE
may be abbreviated toPIC
. - The reserved word
JUSTIFIED
may be abbreviated toJUST
. - As the syntax diagram shows, the definition of a
LOCAL-STORAGE-SECTION-Data-Item
is a recursive one in that there may be any number of such specifications coded following one another. The first such specification must have a level number of 01. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of a record. The definition of a record is terminated when one of the following occurs:- Another 01-level item is found — this signifies the end of the definition of one record and the start of a another.
- A division or section header is found — this also marks the completion of a record and signifies the end of the local-storage section as well.
- Every
LOCAL-STORAGE-SECTION-Data-Item
description must be terminated with a period. - The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 49 are used to define data items that may be part of a hierarchical structure. Level number 01 can also be used to define a constant — an item with an unchangeable value specified at compilation time.
- Level numbers 66, 77, 78 and 88 all have special uses — See Special Data Items, for details.
- Not specifying an identifier-1 or
FILLER
immediately after the level number has the same effect as ifFILLER
were specified. A data item namedFILLER
cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it. - Local-storage cannot be used in nested subprograms.
- See Data Description Clauses, for information on the usage of the various data description clauses.
6.5. LINKAGE SECTION
LINKAGE-SECTION-Data-Item Syntax
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ] ~~~~~~ ~~~~~~ ~~~~~~~~ [ ANY LENGTH ] ~~~ ~~~~~~ [ BASED ] ~~~~~ [ BLANK WHEN ZERO ] ~~~~~ ~~~~ [ JUSTIFIED RIGHT ] ~~~~ [ OCCURS [ integer-1 TO ] integer-2 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-3 ] ~~~~~~~~~ [ ASCENDING|DESCENDING KEY IS identifier-4 ] ~~~~~~~~~ ~~~~~~~~~~ [ INDEXED BY identifier-5 ] ] ~~~~~~~ [ PICTURE IS picture-string ] ~~~ [ REDEFINES identifier-6 ] ~~~~~~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ [ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] ~~~~ ~~~~ ~~~~ ~~~~~ [ USAGE IS data-item-usage ] . [ LINKAGE-SECTION-Data-Item ]... ~~~~~
The LEFT
and RIGHT
(SYNCRONIZED) clauses are syntactically recognized but are otherwise non-functional.
The linkage section describes data within a subprogram that serves as either input arguments to or output results from the subprogram.
- The reserved words
BY
,CHARACTER
,IS
,KEY
,ON
andWHEN
are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program. - The reserved words
SYNCRONIZED
and “SYNCHRONISED
” are interchangeable. Both may be abbreviated asSYNC
. - The reserved word
PICTURE
may be abbreviated toPIC
. - The reserved word
JUSTIFIED
may be abbreviated toJUST
. - As the syntax diagram shows, the definition of a
LINKAGE-SECTION-Data-Item
is a recursive one in that there may be any number of such specifications coded following one another. The first such specification must have a level number of 01. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of a record. The definition of a record is terminated when one of the following occurs:- Another 01-level item is found — this signifies the end of the definition of one record and the start of a another.
- A division or section header is found — this also marks the completion of a record and signifies the end of the linkage section as well.
- Every
LINKAGE-SECTION-Data-Item
description must be terminated with a period. - The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 49 are used to define data items that may be part of a hierarchical structure. Level number 01 can also be used to define a constant — an item with an unchangeable value specified at compilation time.
- Level numbers 66, 77, 78 and 88 all have special uses — See Special Data Items, for details.
- It is expected that:
- A linkage section should occur only within a subprogram. The compiler will not prevent its use in a main program, however.
- All 01-level data items described within a subprogram’s linkage section should appear in a
PROCEDURE DIVISION USING
(see PROCEDURE DIVISION USING) or as arguments on anENTRY
statement. - Each 01-level data item described within a subprogram’s linkage section should correspond to an argument passed on a
CALL
statement (see CALL) or an argument on a function call to the subprogram.
- Not specifying an identifier-1 or
FILLER
immediately after the level number has the same effect as ifFILLER
were specified. A data item namedFILLER
cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it. In the linkage section, 01-level data items cannot be namedFILLER
. - No storage is allocated for data defined in the linkage section; the data descriptions there are merely defining storage areas that will be passed to the subprogram by a calling program. Therefore, any discussion of the default initialization of such data is irrelevant. It is possible, however, to manually allocate linkage section data items that aren’t subprogram arguments via the
ALLOCATE
statement (see ALLOCATE) statement. In such cases, initialization will take place as per the documentation of that statement. - See Data Description Clauses, for information on the usage of the various data description clauses.
6.6. REPORT SECTION
REPORT SECTION Syntax
[ REPORT SECTION. ~~~~~~ ~~~~~~~ { Report-Description [ { Report-Group-Definition } ]... }... ] { { 01-Level-Constant } } { { 78-Level-Constant } } { 01-Level-Constant } { 78-Level-Constant }
Report-Description (RD) Syntax
RD report-name [ IS GLOBAL ] ~~ ~~~~~~ [ CODE IS literal-1 | identifier-1 ] ~~~~ [ { CONTROL IS } { FINAL }... ] { ~~~~~~~ } { ~~~~~ } { CONTROLS ARE } { identifier-2 } ~~~~~~~~ [ PAGE [ { LIMIT IS } ] [ { literal-2 } LINES ] ~~~~ { ~~~~~ } { identifier-3 } ~~~~ { LIMITS ARE } ~~~~~~ [ literal-3 | identifier-4 COLUMNS|COLS ] ~~~~~~~ ~~~~ [ HEADING IS literal-4 | identifier-5 ] ~~~~~~~ [ FIRST DE|DETAIL IS literal-5 | identifier-6 ] ~~~~~ ~~ ~~~~~~ [ LAST CH|{CONTROL HEADING} IS literal-6 | identifier-7 ] ~~~~ ~~ ~~~~~~~ ~~~~~~~ [ LAST DE|DETAIL IS literal-7 | identifier-8 ] ~~~~ ~~ ~~~~~~ [ FOOTING IS literal-8 | identifier-9 ] ] . ~~~~~~~
This section describes the layout of printed reports as well as many of the functional aspects of the generation of reports that will be produced via the Report Writer Control System. It is important to maintain the order of these clauses and ensure that all fields defined or referenced with this section are actually defined in the WORKING-STORAGE SECTION
and not elsewhere.
- The reserved words
ARE
andIS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The phrases
CONTROL IS
andCONTROLS ARE
are interchangeable, as are thePAGE LIMIT
andPAGE LIMITS
phrases. - The reserved word
LINES
may be abbreviated asLINE
. - The reserved word
COLUMNS
may be abbreviated asCOLS
. - Each report referenced on a
REPORT IS
clause (see File/Sort-Description) must be described with a report description (RD
). - See GLOBAL, for information on the
GLOBAL
option. - Please see Report Writer Features, if you have not read it already. It will familiarize you with the Report Writer terminology that follows.
- The following rules pertain to the
PAGE LIMITS
clause:- If no
PAGE LIMITS
clause is specified, the entire report will be generated as if it consists of a single arbitrarily long page. - All literals (literal-2 through literal-8) must be numeric with non-zero positive integer values.
- All identifiers (identifier-2 through identifier-8) must be numeric, unedited with non-zero positive integer values.
- Any value specified for literal-2 or identifier-2 will define the total number of available lines on any report page, not counting any unused margins at the top and/or bottom of the page (defined by the
LINES AT TOP
andLINES AT BOTTOM
values specified on theLINAGE
clause of theFD
thisRD
is linked to — see File/Sort-Description). - Any value specified for literal-3 or identifier-3 will be ignored.
- The
HEADING
clause defines the first line number at which a report heading or page heading may be presented. - The
FIRST DETAIL
clause defines the first line at which a detail group may be presented. - The
LAST CONTROL
HEADING
clause defines the last line at which any line of a control heading may be presented. - The
LAST DETAIL
clause defines the last line at which any line of a detail group may be presented. - The
FOOTING
clause defines the last line at which any line of a control footing group may be presented. - The following rules establish default values for the various
PAGE LIMIT
clauses, assuming there is one:HEADING
-
default is one (1)
FIRST DETAIL HEADING
-
value is used
LAST CONTROL HEADING
-
value from
LAST DETAIL
or, if that is absent, the value fromFOOTING
or, if that too is absent, the value fromPAGE LIMIT
LAST DETAIL
-
value from
FOOTING
or, if that is absent, the value fromPAGE LIMIT
FOOTING
value from
LAST DETAIL
or, if that is absent, the value fromPAGE LIMIT
- For the values specified on a
PAGE LIMIT
clause to be valid, all of the following must be true:-
FIRST DETAIL
≤HEADING
-
LAST CONTROL HEADING
≤FIRST DETAIL
-
LAST DETAIL
≤LAST CONTROL HEADING
-
FOOTING
≤LAST DETAIL
-
- If no
- The following rules pertain to the
CONTROL
clause:- If there is no
CONTROL
clause, the report will contain no control breaks; this implies that there can be noCONTROL HEADING
orCONTROL FOOTING
report groups defined for thisRD
. - Include the reserved word
FINAL
if you want to include a special control heading before the first detail line is generated (CONTROL HEADING FINAL
) or after the last detail line is generated (CONTROL FOOTING FINAL
). - If you specify
FINAL
, it must be the first control break named in theRD
. - Any identifier-9 specifications included on the
CONTROL
clause are referencing data names defined in any data division section except for the report section. - There must be a
CONTROL HEADING
and/orCONTROL FOOTING
report group defined in the report section for each identifier-9. - At execution time:
- Each time a
GENERATE
statement (see GENERATE) is executed against a detail report group defined for thisRD
, the RWCS will check the contents of each identifier-2 data item; whenever an identifier-9’s value has changed since the previousGENERATE
, a control break condition will be in effect for that identifier-2. - Once the list of control breaks has been determined, the
CONTROL FOOTING
for each identifier-2 having a control break (if any such report group is defined) will be presented. - Next, the
CONTROL HEADING
for each identifier-2 having a control break (if any such report group is defined) will be presented. - The
CONTROL FOOTING
andCONTROL HEADING
report groups will be presented in the sequence in which they are listed on theCONTROL
clause. - Only after this processing has occurred will the detail report group specified on the
GENERATE
be presented.
- Each time a
- If there is no
- Each
RD
will have the following allocated for it:- The
PAGE-COUNTER
special register (see Special Registers), which will contain the current report page number.- This register will be set to a value of 1 when an
INITIATE
statement (see INITIATE) is executed for the report and will be incremented by 1 each time the RWCS starts a new page of the report. - References to
PAGE-COUNTER
within the report section will be implicitly qualified with the name of the report to which the report group referencing the register belongs. - References to
PAGE-COUNTER
in the procedure division must be qualified with the appropriate report name if there are multipleRD
s defined.
- This register will be set to a value of 1 when an
- The
LINE-COUNTER
special register, which will contain the current line number on the current page.
- The
- The
RD
must be followed by at least one 01-level report group definition.
6.6.1. Report Group Definitions
Report-Group-Definition Syntax
01 [ identifier-1 ] [ LINE NUMBER IS { integer-1 [ [ ON NEXT PAGE ] } ] ~~~~ { ~~~~ ~~~~ } { +|PLUS integer-1 } { ~~~~ } { ON NEXT PAGE } ~~~~ ~~~~ [ NEXT GROUP IS { [ +|PLUS ] integer-2 } ] ~~~~ ~~~~~ { ~~~~ } { NEXT|{NEXT PAGE}|PAGE } ~~~~ ~~~~ ~~~~ ~~~~ [ TYPE IS { RH|{REPORT HEADING} } ] ~~~~ { ~~ ~~~~~~ ~~~~~~~ } { PH|{PAGE HEADING} } { ~~ ~~~~ ~~~~~~~ } { CH|{CONTROL HEADING} FINAL|identifier-2 } { ~~ ~~~~~~~ ~~~~~~~ ~~~~~ } { DE|DETAIL } { ~~ ~~~~~~ } { CF|{CONTROL FOOTING} FINAL|identifier-2 } { ~~ ~~~~~~~ ~~~~~~~ ~~~~~ } { PF|{PAGE FOOTING} } { ~~ ~~~~ ~~~~~~~ } { RF|{REPORT FOOTING} } ~~ ~~~~~~ ~~~~~~~ . [ REPORT-SECTION-Data-Item ]...
The syntax shown here documents how a report group is defined to a report. This syntax is valid only in the report section, and only then after an RD
.
- The reserved words
IS
,NUMBER
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The
RH
andREPORT HEADING
terms are interchangeable, as arePH
andPAGE HEADING
,CH
andCONTROL HEADING
,DE
andDETAIL
,CF
andCONTROL FOOTING
,PF
andPAGE FOOTING
as well asRF
andREPORT FOOTING
. - The report group being defined will be a part of the most-recently coded
RD
. - The
TYPE
(see TYPE) clause specifies the type of report group being defined. - The level number used for a report group definition must be 01.
- The optional identifier-1 specification assigns a name to this report group so that the group may be referenced either by a
GENERATE
statement or on aUSE BEFORE REPORTING
. - No two report groups in the same report (
RD
) may named with the same identifier-1. There may, however, be multiple identifier-1 definitions in different reports. In such instances, references to identifier-1 must be qualified by the report name. - There may only be one report heading, report footing, final control heading, final control footing, page heading and page footing defined per report.
- Report group declarations must be followed by at least one
REPORT-SECTION-Data-Item
with a level number in the range 02-49. - See Data Description Clauses, for information on the usage of the various data description clauses.
6.6.2. REPORT SECTION Data Items
REPORT-SECTION-Data-Item Syntax
level-number [ identifier-1 ] [ BLANK WHEN ZERO ] ~~~~~ ~~~~ [ COLUMN [ { NUMBER IS } ] [ +|PLUS ] integer-1 ] ~~~ { ~~~~~~ } ~~~~ { NUMBERS ARE } ~~~~~~~ [ GROUP INDICATE ] ~~~~~ ~~~~~~~~ [ JUSTIFIED RIGHT ] ~~~~ [ LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } ] ~~~~ { +|PLUS integer-2 ~~~~ ~~~~ } { ~~~~ } { ON NEXT PAGE } ~~~~ ~~~~ [ OCCURS [ integer-3 TO ] integer-4 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-2 ] ~~~~~~~~~ [ STEP integer-5 ] ~~~~ [ VARYING identifier-3 FROM { identifier-4 } BY { identifier-5 } ] ~~~~~~~ ~~~~ { integer-6 } ~~ { integer-7 } [ PICTURE IS picture-string ] ~~~ [ PRESENT WHEN condition-name ] ~~~~~~~ ~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ [ { SOURCE IS literal-1|identifier-6 [ ROUNDED ] } ] { ~~~~~~ ~~~~~~~ } { SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] } { ~~~ { literal-2 } { ~~~~~ ~~~~~ } } { VALUE IS [ ALL ] literal-3 { UPON identifier-9 } } ~~~~~ ~~~ ~~~~ . [ REPORT-SECTION-Data-Item ]...
Data item descriptions describing the report lines and fields that make up the substance of a report group immediately follow the definition of that group.
- The reserved words
IS
,NUMBER
,OF
,ON
,RIGHT
,TIMES
andWHEN
(BLANK) are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved word
COLUMN
may be abbreviated asCOL
. - The reserved word
JUSTIFIED
may be abbreviated asJUST
. - The reserved word
PICTURE
may be abbreviated asPIC
. - The
SOURCE
(see SOURCE),SUM
(see SUM) andVALUE
(see VALUE) clauses, valid only on an elementary item, are mutually-exclusive of each other. - Group items (those without
PICTURE
clauses) are frequently used to describe entire lines of a report, while elementary items (those with a picture clause) are frequently used to describe specific fields of information on the report. When this coding convention is being used, group items will haveLINE
(see LINE) clauses and noCOLUMN
(see COLUMN) clauses while elementary items will be specified the other way around. - See Data Description Clauses, for information on the usage of the various data description clauses.
6.7. SCREEN SECTION
SCREEN-SECTION-Data-Item Syntax
level-number [ identifier-1 | FILLER ] ~~~~~~ [ AUTO | AUTO-SKIP | AUTOTERMINATE ] [ BELL | BEEP ] ~~~~ ~~~~~~~~~ ~~~~~~~~~~~~~ ~~~~ ~~~~ [ BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-2 ] ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~ [ BLANK LINE|SCREEN ] [ ERASE EOL|EOS ] ~~~~~ ~~~~ ~~~~~~ ~~~~~ ~~~ ~~~ [ BLANK WHEN ZERO ] [ JUSTIFIED RIGHT ] ~~~~~ ~~~~ ~~~~ [ BLINK ] [ HIGHLIGHT | LOWLIGHT ] [ REVERSE-VIDEO ] ~~~~~ ~~~~~~~~~ ~~~~~~~~ ~~~~~~~~~~~~~ [ COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ] ~~~ ~~~~ [ FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-3 | identifier-4 ] ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~ [ { FROM literal-1 | identifier-5 } ] { ~~~~ } { TO identifier-5 } { ~~ } { USING identifier-5 } { ~~~~~ } { VALUE IS [ ALL ] literal-1 } ~~~~~ ~~~ [ FULL | LENGTH-CHECK ] [ REQUIRED | EMPTY-CHECK ] [ SECURE | NO-ECHO ] ~~~~ ~~~~~~~~~~~~ ~~~~~~~~ ~~~~~~~~~~~ ~~~~~~ ~~~~~~~ [ LEFTLINE ] [ OVERLINE ] [ UNDERLINE ] ~~~~~~~~ ~~~~~~~~ ~~~~~~~~~ [ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ] ~~~~ ~~~~ [ OCCURS integer-5 TIMES ] ~~~~~~ [ PICTURE IS picture-string ] ~~~ [ PROMPT [ CHARACTER IS literal-2 | identifier-7 ] ~~~~~~ ~~~~~~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ . [ SCREEN-SECTION-Data-Item ]...
The screen section describes the screens to be displayed during terminal/console I-O.
- The reserved words
CHARACTER
(SEPARATE
clause),IS
,NUMBER
,RIGHT
,TIMES
andWHEN
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved word
COLUMN
may be abbreviated asCOL
. - The reserved word
PICTURE
may be abbreviated asPIC
. - The following sets of reserved words are interchangeable:
-
AUTO
,AUTO-SKIP
andAUTOTERMINATE
-
BACKGROUND-COLOR
andBACKGROUND-COLOUR
-
BELL
andBEEP
-
FOREGROUND-COLOR
andFOREGROUND-COLOUR
-
FULL
andLENGTH-CHECK
-
REQUIRED
andEMPTY-CHECK
-
SECURE
andNO-ECHO
-
- Data items defined in the screen section describe input, output or combination screen layouts to be used with
ACCEPT screen-data-item
statement (see ACCEPT screen-data-item) orDISPLAY screen-data-item
statement (see DISPLAY screen-data-item) statements. These screen layouts may define the entire available screen area or any subset of it. - The term available screen area is a nebulous one in those environments where command-line shell sessions are invoked within a graphical user-interface environment, as will be the case on Windows, OSX and most Unix/Linux systems — these environments allow command-line session windows to exist with a variable number of available screen rows and columns. When you are designing GnuCOBOL screens, you need to do so with an awareness of the logical screen row/column geometry the program will be executing within.
- Data items with level numbers 01 (Constants), 66, 78 and 88 may be used in the screen section; they have the same syntax, rules and usage as they do in the other data division sections.
- Without
LINE
(see LINE) orCOLUMN
(see COLUMN) clauses, screen section fields will display on the console window beginning at whatever line/column coordinate is stated or implied by theACCEPT screen-data-item
orDISPLAY screen-data-item
statement that presents the screen item. After a field is presented to the console window, the next field will be presented immediately following that field. - A
LINE
clause explicitly stated in the definition of a screen section data item will override anyLINE
clause included on theACCEPT screen-data-item
orDISPLAY screen-data-item
statement that presents that data item to the screen. The same is true ofCOLUMN
clauses. - The
Tab
andBack-Tab
(Shift
-Tab
on most keyboards) keys will position the cursor from field to field in the line/column sequence in which the fields occur on the screen at execution time, regardless of the sequence in which they were defined in the screen section. - See Data Description Clauses, for information on the usage of the various data description clauses.
6.8. Special Data Items
6.8.1. 01-Level Constants
01-Level-Constant Syntax
01 constant-name-1 CONSTANT [ IS GLOBAL ] ~~~~~~~~ ~~~~~~ { AS { literal-1 } } . { { { BYTE-LENGTH } OF { identifier-1 } } } { { { ~~~~~~~~~~~ } { usage-name } } } { { { LENGTH } } } { ~~~~~~ } { FROM CDF-variable-name-1 } ~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, SCREEN
.
The 01-level constant is one of four types of compilation-time constants that can be declared within a program. The other three types are >>DEFINE
CDF directive (see >>DEFINE) constants, >>SET
CDF directive (see >>SET) constants and 78-level constants (see 78-Level Data Items).
- The reserved words
AS
,IS
andOF
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - See GLOBAL, for information on the
GLOBAL
option. - This particular type of constant declaration provides the ability to determine the length of a data item or the storage size associated with a particular numeric
USAGE
(see USAGE) type — something not possible with the other types of constants. - Constants defined in this way become undefined once an
END PROGRAM
orEND FUNCTION
is encountered in the input source. - Data descriptions of this form do not actually allocate any storage — they merely define a name (constant-name-1) that may be used anywhere a numeric literal (see
BYTE-LENGTH
orLENGTH
options) or a literal of the same type as literal-1 may be used. - The constant-name-1 name may not be referenced on a CDF directive.
- Care must be taken that constant-name-1 does not duplicate any other data item name that has been defined in the program as references to that data item name will refer to the constant and not the data item. The GnuCOBOL compiler will not issue a warning about this condition.
- The value specified for usage-name may be any
USAGE
that does not use aPICTURE
(see PICTURE) clause. These would be any ofBINARY-C-LONG
,BINARY-CHAR
,BINARY-DOUBLE
,BINARY-LONG
,BINARY-SHORT
,COMP-1
(orCOMPUTATIONAL-1
),COMP-2
(orCOMPUTATIONAL-2
),FLOAT-DECIMAL-16
,FLOAT-DECIMAL-34
,FLOAT-LONG
,FLOAT-SHORT
,POINTER
, orPROGRAM-POINTER
. - The
BYTE-LENGTH
clause will produce a numeric value for constant-name-1 identical to that which would be returned by theBYTE-LENGTH
intrinsic function executed against identifier-1 or a data item declared with aUSAGE
of usage-name. - The
LENGTH
clause will produce a numeric value for constant-name-1 identical to that which would be returned by theLENGTH
intrinsic function executed against identifier-1 or a data item declared with aUSAGE
of usage-name.
Here is the listing of a GnuCOBOL program that uses 01-level constants to display the length (in bytes) of the various picture-less usage types.
IDENTIFICATION DIVISION. PROGRAM-ID. Usage Lengths. DATA DIVISION. WORKING-STORAGE SECTION. 01 Len-BINARY-C-LONG CONSTANT AS LENGTH OF BINARY-C-LONG. 01 Len-BINARY-CHAR CONSTANT AS LENGTH OF BINARY-CHAR. 01 Len-BINARY-DOUBLE CONSTANT AS LENGTH OF BINARY-DOUBLE. 01 Len-BINARY-LONG CONSTANT AS LENGTH OF BINARY-LONG. 01 Len-BINARY-SHORT CONSTANT AS LENGTH OF BINARY-SHORT. 01 Len-COMP-1 CONSTANT AS LENGTH OF COMP-1. 01 Len-COMP-2 CONSTANT AS LENGTH OF COMP-2. 01 Len-FLOAT-DECIMAL-16 CONSTANT AS LENGTH OF FLOAT-DECIMAL-16. 01 Len-FLOAT-DECIMAL-34 CONSTANT AS LENGTH OF FLOAT-DECIMAL-34. 01 Len-FLOAT-LONG CONSTANT AS LENGTH OF FLOAT-LONG. 01 Len-FLOAT-SHORT CONSTANT AS LENGTH OF FLOAT-SHORT. 01 Len-POINTER CONSTANT AS LENGTH OF POINTER. 01 Len-PROGRAM-POINTER CONSTANT AS LENGTH OF PROGRAM-POINTER. PROCEDURE DIVISION. 000-Main. DISPLAY "On this system, with this build of GnuCOBOL, the" DISPLAY "PICTURE-less USAGE's have these lengths (in bytes):" DISPLAY " " DISPLAY "BINARY-C-LONG: " Len-BINARY-C-LONG DISPLAY "BINARY-CHAR: " Len-BINARY-CHAR DISPLAY "BINARY-DOUBLE: " Len-BINARY-DOUBLE DISPLAY "BINARY-LONG: " Len-BINARY-LONG DISPLAY "BINARY-SHORT: " Len-BINARY-SHORT DISPLAY "COMP-1: " Len-COMP-1 DISPLAY "COMP-2: " Len-COMP-2 DISPLAY "FLOAT-DECIMAL-16: " Len-FLOAT-DECIMAL-16 DISPLAY "FLOAT-DECIMAL-34: " Len-FLOAT-DECIMAL-34 DISPLAY "FLOAT-LONG: " Len-FLOAT-LONG DISPLAY "FLOAT-SHORT: " Len-FLOAT-SHORT DISPLAY "POINTER: " Len-POINTER DISPLAY "PROGRAM-POINTER: " Len-PROGRAM-POINTER STOP RUN .
The output of this program, on a Windows 7 system with a 32-bit MinGW build of GnuCOBOL is:
On this system, with this build of GnuCOBOL, the PICTURE-less USAGE's have these lengths (in bytes): BINARY-C-LONG: 4 BINARY-CHAR: 1 BINARY-DOUBLE: 8 BINARY-LONG: 4 BINARY-SHORT: 2 COMP-1: 4 COMP-2: 8 FLOAT-DECIMAL-16: 8 FLOAT-DECIMAL-34: 16 FLOAT-LONG: 8 FLOAT-SHORT: 4 POINTER: 4 PROGRAM-POINTER: 4
6.8.2. 66-Level Data Items
66-Level-Data-Item Syntax
66 identifier-1 RENAMES identifier-2 [ THRU|THROUGH identifier-3 ] . ~~~~~~~ ~~~~ ~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
A 66-level data item regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.
- The reserved words
THRU
andTHROUGH
are interchangeable. - A level-66 data item cannot rename a level-66, level-01, level-77, or level-88 data item.
- There may be multiple level-66 data items that rename data items contained within the same 01-level record description.
- All
RENAMES
entries associated with one logical record must immediately follow that record’s last data description entry.
6.8.3. 77-Level Data Items
77-Level-Data-Item Syntax
77 identifier-1 [ IS GLOBAL|EXTERNAL ] ~~~~~~ ~~~~~~~~ [ BASED ] ~~~~~ [ BLANK WHEN ZERO ] ~~~~~ ~~~~ [ JUSTIFIED RIGHT ] ~~~~ [ PICTURE IS picture-string ] ~~~ [ REDEFINES identifier-5 ] ~~~~~~~~~ [ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~ [ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] ~~~~ ~~~~ ~~~~ ~~~~~ [ USAGE IS data-item-usage ] ~~~~~ [ VALUE IS [ ALL ] literal-1 ] . ~~~~~ ~~~
The LEFT
and RIGHT
(SYNCRONIZED) clauses are syntactically recognized but are otherwise non-functional.
This syntax is valid in the following sections: WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
The intent of a 77-level item is to be able to create a stand-alone elementary data item.
- The reserved words
CHARACTER
,IS
,RIGHT
(JUSTIFIED) andWHEN
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved word
JUSTIFIED
may be abbreviated asJUST
, the reserved wordPICTURE
may be abbreviated asPIC
and the reserved wordsSYNCRONIZED
andSYNCHRONISED
may be abbreviated asSYNC
. - New programs requiring a stand-alone elementary item should be coded to use a level number of 01 rather than 77.
- See Data Description Clauses, for information on the usage of the various data description clauses.
6.8.4. 78-Level Data Items
78-Level-Constant Syntax
78 constant-name-1 VALUE IS literal-1 . ~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, SCREEN
The 78-level constant is one of four types of compilation-time constants that can be declared within a program. The other three types are >>DEFINE
CDF directive (see >>DEFINE) constants, >>SET
CDF directive (see >>SET) constants and 01-level constants (see 01-Level Constants).
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - Constants defined in this way become undefined once an
END PROGRAM
orEND FUNCTION
is encountered in the input source. - Data descriptions of this form do not actually allocate any storage — they merely define a name (constant-name-1) that may be used anywhere a literal of the same type as literal-1 may be used.
- The constant-name-1 name may not be referenced on a CDF directive.
- Care must be taken that constant-name-1 does not duplicate any other data item name that has been defined in the program as references to that data item name will refer to the constant and not the data item. The GnuCOBOL compiler will not issue a warning about this condition.
6.8.5. 88-Level Data Items
88-Level-Data-Item Syntax
88 condition-name-1 { VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}... { ~~~~~ } ~~~~ ~~~~~~~ { VALUES ARE } ~~~~~~ [ WHEN SET TO FALSE IS literal-3 ] . ~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
Condition names are Boolean (i.e. TRUE
/ FALSE
) data items that receive their TRUE
and FALSE
values based upon the values of the non 88-level data item whose definition they immediately follow.
- The reserved words
ARE
,IS
,SET
andTO
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
THRU
andTHROUGH
are interchangeable. - Condition names are always defined subordinate to another (non 88-level) data item. That data item must be an elementary item. Whenever the parent data item assumes one of the values specified on the 88-level item’s
VALUE
(see VALUE) clause, condition-name-1 will take on the value ofTRUE
. - Condition names do not occupy any storage.
- The optional
THROUGH
clause allows a range of possibleTRUE
values to be specified. - Whenever the parent data item assumes any value except one of the values specified on condition-name-1’s
VALUE
clause, condition-name-1 will take on the value of FALSE. - Executing the statement
SET condition-name-1 TO TRUE
will cause condition-name-1’s parent data item to take on the first value specified on condition-name-1’sVALUE
clause. - Executing the statement
SET condition-name-1 TO FALSE
will cause condition-name-1’s parent data item to take on the value specified on condition-name-1’sFALSE
clause. If condition-name-1 does not have aFALSE
clause, theSET
(see SET) statement will generate an error message at compilation time. - See Condition Names, for more information.
6.9. Data Description Clauses
6.9.1. ANY LENGTH
ANY LENGTH Attribute Syntax
ANY LENGTH ~~~ ~~~~~~
This syntax is valid in the following sections: LINKAGE
Data items declared with the ANY LENGTH
attribute have no fixed compile-time length. Such items may only be defined in the linkage section of a subprogram as they may only serve as subroutine argument descriptions. These items must have a PICTURE
(see PICTURE) clause that specifies exactly one A, X or 9 symbol.
- The
ANY LENGTH
andBASED
(see BASED) clauses cannot be used together in the same data item description.
6.9.2. AUTO
AUTO Attribute Syntax
AUTO ~~~~
This syntax is valid in the following sections: SCREEN
A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.
- The
AUTO
,AUTO-SKIP
(see AUTO-SKIP) andAUTOTERMINATE
(see AUTOTERMINATE) clauses are interchangeable, and may not be used together in the same data item description.
6.9.3. AUTO-SKIP
AUTO-SKIP Attribute Syntax
AUTO-SKIP ~~~~~~~~~
This syntax is valid in the following sections: SCREEN
A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.
- The
AUTO
(see AUTO),AUTO-SKIP
andAUTOTERMINATE
(see AUTOTERMINATE) clauses are interchangeable, and may not be used together in the same data item description.
6.9.4. AUTOTERMINATE
AUTOTERMINATE Attribute Syntax
AUTOTERMINATE ~~~~~~~~~~~~~
This syntax is valid in the following sections: SCREEN
A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.
- The
AUTO
(see AUTO),AUTO-SKIP
(see AUTO-SKIP) andAUTOTERMINATE
clauses are interchangeable, and may not be used together in the same data item description.
6.9.5. BACKGROUND-COLOR
BACKGROUND-COLOR Attribute Syntax
BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-1 ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
This syntax is valid in the following sections: SCREEN
This clause is used to specify the screen background color of the screen data item or the default screen background color of subordinate items if used on a group item.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved words
BACKGROUND-COLOR
andBACKGROUND-COLOUR
are interchangeable. - You specify colors by number (0-7), or by using the constant names provided in the screenio.cpy copybook (provided with all GnuCOBOL source distributions).
- Colors may also be specified using a numeric non-edited identifier whose value is in the range 0-7.
For composite DISPLAY
’s, the attributes are always only applied to the previous source-item but the following also allows a change by variable or literal i.e.
DISPLAY "Name: " BACKGROUND-COLOR COB-YELLOW NAME-VAR BACKGROUND-COLOR COB-BLACK END-DISPLAY
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.6. BASED
BASED Attribute Syntax
BASED ~~~~~
This syntax is valid in the following sections: WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
Data items declared with BASED
are allocated no storage at compilation time. At run-time, the ALLOCATE
(see ALLOCATE) or SET ADDRESS
(see SET ADDRESS) statements are used to allocate space for and (optionally) initialize such items.
- The
BASED
andANY LENGTH
(see ANY LENGTH) clauses cannot be used together in the same data item description. - The
BASED
clause may only be used on level 01 and level 77 data items.
6.9.7. BEEP
BEEP Attribute Syntax
BEEP ~~~~
This syntax is valid in the following sections: SCREEN
- The
BEEP
andBELL
(see BELL) clauses are interchangeable, and may not be used together in the same data item description. - Use this clause to cause an audible tone to occur when the screen item is
DISPLAY
ed.
6.9.8. BELL
BELL Attribute Syntax
BELL ~~~~
This syntax is valid in the following sections: SCREEN
- The
BEEP
(see BEEP) andBELL
clauses are interchangeable, and may not be used together in the same data item description. - Use this clause to cause an audible tone to occur when the screen item is
DISPLAY
ed.
6.9.9. BLANK
BLANK Attribute Syntax
BLANK LINE|SCREEN ~~~~~ ~~~~ ~~~~~~
This syntax is valid in the following sections: SCREEN
This clause will blank out either the entire screen (BLANK SCREEN
) or just the line upon which data is about to be displayed (BLANK LINE
).
- Blanked-out areas will have their foreground and background colors set to the attributes of the field containing the
BLANK
clause. - This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
6.9.10. BLANK WHEN ZERO
BLANK-WHEN-ZERO Attribute Syntax
BLANK WHEN ZERO ~~~~~ ~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
This clause will cause that item’s value to be automatically transformed into spaces if a value of 0 is ever MOVE
d to the item.
- The reserved word
WHEN
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - This clause may only be used on a
PIC 9
data item with aUSAGE
(see USAGE) ofDISPLAY
.
6.9.11. BLINK
BLINK Attribute Syntax
BLINK ~~~~~
This syntax is valid in the following sections: SCREEN
The BLINK
clause modifies the visual appearance of the displayed field by making the field contents blink.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.12. COLUMN
COLUMN (REPORT SECTION) Clause Syntax
COLUMN [ { NUMBER IS } ] [ +|PLUS ] integer-1 ] ~~~ { NUMBERS ARE } ~~~~
COLUMN (SCREEN SECTION) Clause Syntax
COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ] ~~~ ~~~~
This syntax is valid in the following sections: REPORT
, SCREEN
The COLUMN
clause provides the means of stating in which column a field should be presented on the console window (screen section) or a report (report section).
- The reserved words
ARE
,IS
,NUMBER
andNUMBERS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved word
COLUMN
may be abbreviated asCOL
. - The line location of a report section or screen section field will be determined by the
LINE
(see LINE) clause. - The value of integer-1 must be 1 or greater.
- If identifier-1 is used to specify either an absolute or relative column position, identifier-1 must be defined as a numeric item of any
USAGE
(see USAGE) other thanCOMPUTATIONAL-1
orCOMPUTATIONAL-2
, without editing symbols. The value of identifier-1 at the time the screen data item is presented must be 1 or greater. Note that aCOMPUTATIONAL-1
orCOMPUTATIONAL-2
identifier will be accepted by the compiler, but will produce unpredictable results at run-time. - The column coordinate of a field may be stated on an absolute basis (i.e.
COLUMN 5
) or on a relative basis based upon the end of the previously-presented field (i.e.COLUMN PLUS 1
). - The symbol ‘+’ may be used in lieu of the word
PLUS
, if desired; if symbol ‘+’ is used, however, there must be at least one space separating it from integer-1. Failure to include this space will cause the symbol ‘+’ sign to be simply treated as part of integer-1 and will treat theCOLUMN
clause as an absolute column specification rather than a relative one. - Using relative column positioning (
COLUMN PLUS
) has slightly different behaviour depending upon the section in which the clause is used, as follows:- When used on a report section data item,
COLUMN PLUS
will position the start of the new field’s value such that there are integer-1 blank columns between the end of the previous field and the beginning of this field.If a report data item’s description includes the
SOURCE
(see SOURCE),SUM
(see SUM) orVALUE
(see VALUE) clause but has noCOLUMN
clause,COLUMN PLUS 1
will be assumed. - When used on a screen section data item,
COLUMN PLUS
will position the new field so that it begins exactly integer-1 or identifier-1 characters past the last character of the previous field. Thus,COLUMN PLUS 1
will leave no blank positions between the end of the previous field and the start of this one.If a screen data item’s description includes the
FROM
(see FROM),TO
(see TO),USING
(see USING) orVALUE
(see VALUE) clause but has noCOLUMN
clause, the new screen field will begin at the column coordinate of the last character of the previous field.
- When used on a report section data item,
6.9.13. CONSTANT
CONSTANT Attribute Syntax
CONSTANT ~~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, SCREEN
This option signifies that the 01-level data item in whose declaration CONSTANT
is specified will be treated as a symbolic name for a literal value, usable wherever a literal of the appropriate type could be used.
- The value of a data item defined as a constant cannot be changed at run-time. In fact, it is not syntactically acceptable to use such a data item as the destination field of any procedure division statement that stores a value.
- See 01-Level Constants, for additional information.
6.9.14. EMPTY-CHECK
EMPTY-CHECK Attribute Syntax
EMPTY-CHECK ~~~~~~~~~~~
This syntax is valid in the following sections: SCREEN
This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if EMPTY-CHECK
is specified on a group item).
- The
EMPTY-CHECK
andREQUIRED
(see REQUIRED) clauses are interchangeable, and may not be used together in the same data item description. - In order to take effect, the user must first move the cursor into the field having this clause in its definition.
- The
ACCEPT screen-data-item
statement (see ACCEPT screen-data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless data has been entered into the field. Function keys will still be allowed to terminate theACCEPT
. - In order to be functional, this attribute must be supported by the underlying “curses” package your GnuCOBOL implementation was built with. As of this time, the “PDCurses” package (used for native Windows or MinGW builds) does not support
EMPTY-CHECK
.
6.9.15. ERASE
ERASE Clause Syntax
ERASE EOL|EOS ~~~~~ ~~~ ~~~
This syntax is valid in the following sections: SCREEN
ERASE
will blank-out screen contents from the location where the screen data item whose description contains this clause will be displayed, forward until the end of the screen (ERASE EOS
)
- Erased areas will have their foreground and background colors set to the attributes of the field containing the
ERASE
clause. - This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.16. EXTERNAL
EXTERNAL Attribute Syntax
EXTERNAL ~~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
This clause marks a data item description, FD
or SD
see File/Sort-Description as being shareable with other programs executed from the same execution thread.
- By specifying the
EXTERNAL
clause on either anFD
or anSD
, the file description is capable of being shared between all programs executed from the same execution thread, provided anEXTERNAL
clause is coded with the file’s description in each program requiring it. This sharing allows the file to be opened, read and/or written and closed in different programs. This sharing applies to the record descriptions subordinate to the file description too. - By specifying the
EXTERNAL
clause on the description of a data item, the data item is capable of being shared between all programs executed from the same execution thread, provided the data item is coded (with anEXTERNAL
clause) in each program requiring it. - The following points apply to the specification of
EXTERNAL
in a data item’s definition:
6.9.17. FALSE
FALSE Clause Syntax
WHEN SET TO FALSE IS literal-1 ~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
This clause, which may only appear on the definition of a level-88 condition name, is used to specify the value of the data item that serves as the parent of the level-88 condition name that will force the condition name to assume a value of FALSE
.
- The reserved words
IS
,SET
,TO
andWHEN
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - See 88-Level Data Items, or See Condition Names, for more information.
6.9.18. FOREGROUND-COLOR
FOREGROUND-COLOR Attribute Syntax
FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-1 | identifier-1 ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
This syntax is valid in the following sections: SCREEN
This clause is used to specify the color of text within a screen data item or the default text color of subordinate items if used on a group item.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved words
FOREGROUND-COLOR
andFOREGROUND-COLOUR
are interchangeable. - You specify colors by number (0-7), or by using the constant names provided in the screenio.cpy copybook (which is provided with all GnuCOBOL source distributions).
- Colors may also be specified using a numeric non-edited identifier whose value is in the range 0-7.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.19. FROM
FROM Clause Syntax
FROM literal-1 | identifier-5 ~~~~
This syntax is valid in the following sections: SCREEN
This clause is used to specify either the data item a screen section field is to obtain its value from when the screen is displayed, or a literal that will specify the value of that same field.
- The
FROM
,TO
(see TO),USING
(see USING) andVALUE
(see VALUE) clauses are mutually-exclusive in any screen section data item’s definition.
6.9.20. FULL
FULL Attribute Syntax
FULL ~~~~
This syntax is valid in the following sections: SCREEN
The FULL
clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if specified on a group item) sufficient to fill every character position of the field.
- The
FULL
andLENGTH-CHECK
(see LENGTH-CHECK) clauses are interchangeable, and may not be used together in the same data item description. - In order for this clause to take effect at execution time, the user must move the cursor into the field having this clause in its definition.
- The
ACCEPT screen-data-item
statement (see ACCEPT screen-data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless the proper amount of data has been entered into the field. Function keys will still be allowed to terminate theACCEPT
, however. - In order to be functional, this attribute must be supported by the underlying “curses” package your GnuCOBOL implementation was built with. As of this time, the “PDCurses” package (used for native Windows or MinGW builds) does not support
FULL
.
6.9.21. GLOBAL
GLOBAL Attribute Syntax
GLOBAL ~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, REPORT
This clause marks a data item, 01-level constant, FD
(see File/Sort-Description), SD
(see File/Sort-Description) or an RD
(see REPORT SECTION) as being shareable with any nested subprograms.
- By specifying the
GLOBAL
clause on the description of a file or a report, that description is capable of being shared between a program and any nested subprograms within it, provided theFD
,SD
orRD
is coded (with aGLOBAL
clause) in each nested subprogram requiring it. This sharing allows the file to be opened, read and/or written and closed or the report to be initiated or terminated in those programs. Separately compiled programs may not share aGLOBAL
file description, but they may share anEXTERNAL
(see EXTERNAL) file description. This sharing applies to the record descriptions subordinate to the file description and the report groups subordinate to theRD
also. - By specifying the
GLOBAL
clause on the description of a data item, the data item is capable of being shared between a program and any nested subprograms within it, provided the data item is coded (with aGLOBAL
clause) in each program requiring it. - The following points apply to the specification of
GLOBAL
in a data item’s definition:
6.9.22. GROUP INDICATE
GROUP-INDICATE Attribute Syntax
GROUP INDICATE ~~~~~ ~~~~~~~~
This syntax is valid in the following sections: REPORT
The GROUP INDICATE
clause specifies that the data item in whose definition the clause appears will be presented only in very limited circumstances.
- This clause may only appear within a
DETAIL
report group (see TYPE). - When this clause is present, the data item in question will be presented only under the following circumstances:
- On the first presentation of the detail group following the
INITIATE
(see INITIATE) of the report. - On the first presentation of the detail group after every new page is started.
- On the first presentation of the detail group after any control break occurs.
- On the first presentation of the detail group following the
6.9.23. HIGHLIGHT
HIGHLIGHT Attribute Syntax
HIGHLIGHT ~~~~~~~~~
This syntax is valid in the following sections: SCREEN
This clause controls the intensity of text (FOREGROUND-COLOR
(see FOREGROUND-COLOR)) by setting that intensity to its highest of three possible settings.
- This clause, along with
LOWLIGHT
(see LOWLIGHT), are intended to provide a three-level intensity scheme (LOWLIGHT
… nothing (Normal) …HIGHLIGHT
).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.24. JUSTIFIED
JUSTIFIED Attribute Syntax
JUSTIFIED RIGHT ~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
The presence of a JUSTIFIED RIGHT
clause in a data item’s definition alters the manner in which data is stored into the field from the default ’left-justified, space filled’ behaviour to ’right justified, space filled’.
- The reserved word
RIGHT
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved word
JUSTIFIED
may be abbreviated asJUST
. - This clause is valid only on alphabetic (
PIC A
) or alphanumeric (PIC X
) data items. - The presence or absence of this clause influences the behaviour of the
MOVE
(see MOVE) statement as well as theFROM
(see FROM),SOURCE
(see SOURCE) andUSING
(see USING) data item description clauses. - If the value being stored into the field is the same length as the receiving field, the presence or absence of the
JUSTIFIED RIGHT
clause on that field’s description is irrelevant. - The following examples illustrate the behaviour of the presence and absence of the
JUSTIFIED RIGHT
clause when the field size is different than that of the value being stored. In these examples, the symbol b represents a space.When the value is shorter than the field size:
Without JUSTIFIED
With JUSTIFIED
01 A PIC X(6). MOVE @code{ABC} TO A
01 A PIC X(6) JUSTIFIED RIGHT. MOVE @code{ABC} TO A
Result Result ABCbbb
bbbABC
When the value is longer than the field size:
Without JUSTIFIED
With JUSTIFIED
01 A PIC X(6). MOVE 'ABCDEFGHI' TO A
01 A PIC X(6) JUSTIFIED RIGHT. MOVE 'ABCDEFGHI' TO A
Result Result ABCDEF
DEFGHI
6.9.25. LEFTLINE
LEFTLINE Attribute Syntax
LEFTLINE ~~~~~~~~
This syntax is valid in the following sections: SCREEN
The LEFTLINE
clause will introduce a vertical line at the left edge of a screen field.
- The
LEFTLINE
,OVERLINE
(see OVERLINE) andUNDERLINE
(see UNDERLINE) clauses may be used in any combination in a single field’s description. - This clause is essentially non-functional when used within Windows command shell (cmd.exe) environments and running programs compiled using a GnuCOBOL implementation built using “PDCurses” (such as Windows/MinGW builds).
- Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will depend upon the video attribute capabilities of the terminal output drivers and “curses” software being used.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.26. LENGTH-CHECK
LENGTH-CHECK Attribute Syntax
LENGTH-CHECK ~~~~~~~~~~~~
This syntax is valid in the following sections: SCREEN
The LENGTH-CHECK
clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if specified on a group item) sufficient to fill every character position of the field.
- The
FULL
(see FULL) andLENGTH-CHECK
clauses are interchangeable, and may not be used together in the same data item description. - In order for this clause to take effect at execution time, the user must move the cursor into the field having this clause in its definition.
- The
ACCEPT screen-data-item
statement (see ACCEPT screen-data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless the proper amount of data has been entered into the field. Function keys will still be allowed to terminate theACCEPT
, however. - In order to be functional, this attribute must be supported by the underlying “curses” package your GnuCOBOL implementation was built with. As of this time, the “PDCurses” package (used for native Windows or MinGW builds) does not support
LENGTH-CHECK
.
6.9.27. LINE
LINE (REPORT SECTION) Clause Syntax
LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } ~~~~ { ~~~~ ~~~~ } { +|PLUS integer-2 } { ~~~~ } { ON NEXT PAGE } ~~~~ ~~~~
LINE (SCREEN SECTION) Clause Syntax
[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ] ~~~~ ~~~~
This syntax is valid in the following sections: REPORT
, SCREEN
This clause provides a means of explicitly stating on which line a field should be presented on the console window (screen section) or on a report (report section).
- The reserved words
IS
,NUMBER
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The following points document the use of format 1 of the
LINE
clause:- The column location of a report item will be determined by the
COLUMN
(see COLUMN) clause. - The value of integer-1 must be 1 or greater.
- The report line number upon which the data item containing this clause along with any subordinate data items will be presented may be stated on an absolute basis (i.e.
LINE 5
) or on a relative basis based upon the previously-displayed line (i.e.LINE PLUS 1
). - The symbol ‘+’ may be used in lieu of the word
PLUS
, if desired; if ‘+’ is used, however, there must be at least one space separating it from integer-1. Failure to include this space will cause the ‘+’ to be simply treated as part of integer-1 and will treat the LINE clause as an absolute line specification rather than a relative one. - The optional
NEXT PAGE
clause specifies that — regardless of whether or not the report group containing this clause could fit on the report page being currently generated, the report group will be forced to appear on a new page.
- The column location of a report item will be determined by the
- The following points document the use for format 2 of the
LINE
clause:- The column location of a screen section field is determined by the
COLUMN
(see COLUMN) clause. - The value of integer-1 must be 1 or greater.
- If identifier-1 is used to specify either an absolute or relative column position, identifier-1 must be defined as a numeric item of any
USAGE
(see USAGE) other thanCOMPUTATIONAL-1
orCOMPUTATIONAL-2
, without editing symbols. The value of identifier-1 at the time the screen data item is presented must be 1 or greater. Note that aCOMPUTATIONAL-1
orCOMPUTATIONAL-2
identifier will be accepted by the compiler, but will produce unpredictable results at run-time. - The screen line number upon which the data item containing this clause along with any subordinate data items will be displayed may be stated on an absolute basis (i.e.
LINE 5
) or on a relative basis based upon the previously-displayed line (i.e.LINE PLUS 1
). - The symbol ‘+’ may be used in lieu of the word
PLUS
, if desired; if ‘+’ is used, however, there must be at least one space separating it from integer-1. Failure to include this space will cause the ‘+’ to be simply treated as part of integer-1 and will treat theLINE
clause as an absolute line specification rather than a relative one. - If a screen data item’s description includes the
FROM
(see FROM),TO
(see TO),USING
(see USING) orVALUE
(see VALUE) clause but has no LINE clause, the “current screen line” will be assumed.
- The column location of a screen section field is determined by the
6.9.28. LOWLIGHT
LOWLIGHT Attribute Syntax
LOWLIGHT ~~~~~~~~
This syntax is valid in the following sections: SCREEN
The LOWLIGHT
clause controls the intensity of text (FOREGROUND-COLOR
) by setting that intensity to its lowest of three possible settings.
- This clause, along with
HIGHLIGHT
(see HIGHLIGHT), are intended to provide a three-level intensity scheme (LOWLIGHT
… nothing (Normal) …HIGHLIGHT
). In environments such as a Windows console where only two levels of intensity are supported,LOWLIGHT
is the same as leaving this clause off altogether.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.29. NEXT GROUP
NEXT-GROUP Clause Syntax
NEXT GROUP IS { [ +|PLUS ] integer-2 } ~~~~ ~~~~~ { ~~~~ } { NEXT|{NEXT PAGE}|PAGE } ~~~~ ~~~~ ~~~~ ~~~~
This syntax is valid in the following sections: REPORT
This clause defines any rules for where the next group to be presented on a report will begin, line-wise, with respect to the last line of the group in which this clause appears.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The terms
NEXT
,NEXT PAGE
andPAGE
are interchangeable. - A report group must contain at least one
LINE NUMBER
clause in order to also contain aNEXT GROUP
clause. - If the
RD
(see REPORT SECTION) in which the report group containing aNEXT GROUP
clause does not contain aPAGE LIMITS
clause, only thePLUS integer-1
option may be specified. - The
NEXT PAGE
option cannot be used in aPAGE FOOTING
. - The
NEXT GROUP
option cannot be specified in either aREPORT HEADING
or aPAGE HEADING
. - The effects of
NEXT GROUP
will be in addition to any line spacing defined by the next-presented group’sLINE NUMBER
clause.
6.9.30. NO-ECHO
NO-ECHO Attribute Syntax
NO-ECHO ~~~~~~~
This syntax is valid in the following sections: SCREEN
The NO-ECHO
clause will cause all data entered into the field to appear on the screen as asterisks.
- The
NO-ECHO
andSECURE
(see SECURE) clauses are interchangeable, and may not be used together in the same data item description. - This clause may only be used on a field allowing data entry (a field containing either the
USING
(see USING) orTO
(see TO) clause).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.31. OCCURS
OCCURS (REPORT SECTION) Clause Syntax
OCCURS [ integer-1 TO ] integer-2 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-1 ] ~~~~~~~~~ [ STEP integer-3 ] ~~~~ [ VARYING identifier-2 FROM { identifier-3 } BY { identifier-4 } ] ~~~~~~~ ~~~~ { integer-4 } ~~ { integer-5 }
OCCURS (SCREEN SECTION) Clause Syntax
OCCURS integer-2 TIMES ~~~~~~
OCCURS (All Other Sections Clause Syntax
OCCURS [ integer-1 TO ] integer-2 TIMES ~~~~~~ ~~ [ DEPENDING ON identifier-1 ] ~~~~~~~~~ [ ASCENDING|DESCENDING KEY IS identifier-5... ]... ~~~~~~~~~ ~~~~~~~~~~ [ INDEXED BY identifier-6 ] ~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
The OCCURS
clause is used to create a data structure called a table, where entries in that structure repeat multiple times.
- The reserved words
BY
(INDEXED),IS
,KEY
,ON
andTIMES
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The value of integer-2 specifies how many entries will be allocated in the table.
- The following is an example of how a table might be defined:
05 QUARTERLY-REVENUE OCCURS 4 TIMES PIC 9(7)V99.
This will allocate the following:
QUARTERLY-REVENUE(1) QUARTERLY-REVENUE(2) QUARTERLY-REVENUE(3) QUARTERLY-REVENUE(4)
Each occurrence is referenced using the subscript syntax (a numeric literal, arithmetic expression or numeric identifier enclosed within parenthesis) shown above.
- The
OCCURS
clause may be used at the group level too, in which case the entire group structure repeats, as follows:05 GRP OCCURS 3 TIMES. 10 A PIC X(1). 10 B PIC X(1). 10 C PIC X(1).
This would allow references to any of the following:
GRP(1) includes A(1), B(1) and C(1) GRP(2) includes A(2), B(2) and C(2) GRP(3) includes A(3), B(3) and C(3)
or each A,B,C item could be referenced as follows:
A(1) character #1 of GRP(1) B(1) character #2 of GRP(1) C(1) character #3 of GRP(1) A(2) character #1 of GRP(2) B(2) character #2 of GRP(2) C(2) character #3 of GRP(2) A(3) character #1 of GRP(3) B(3) character #2 of GRP(3) C(3) character #3 of GRP(3)
- The optional
DEPENDING ON
clause can be added to anOCCURS
to create a variable-length table. In such cases, the value of integer-1 specifies what the minimum number of entries in the table will be while integer-2 specifies the maximum. Such tables will be allocated out to the maximum size specified as integer-2. At execution time the value of identifier-1 will determine how many of the table elements are accessible. - See the documentation of the
SEARCH
(see SEARCH),SEARCH ALL
(see SEARCH ALL) andSORT
(see SORT) statements for explanations of theKEY
andINDEXED BY
clauses. - The
OCCURS
clause cannot be specified in a data description entry that has a level number of 01, 66, 77, or 88, although it is valid in data items described subordinate to an 01-level data item. - The following points apply to an
OCCURS
used in the report section:- The optional
STEP
clause defines an incrementation value that will be added to any absoluteLINE
(see LINE) orCOLUMN
(see COLUMN) number specifications that may be part of or subordinate to this data item’s definition. - The optional
VARYING
clause defines an identifier that may be used as a subscript for the multiple occurrences of this or any subordinate data item should theSOURCE
(see SOURCE) orSUM
(see SUM) clause(s) on this or subordinate data items reference entries within the table. The identifier-2 data item is dynamically created as needed and cannot be referenced outside the scope of the report data item definition. - The following two examples illustrate two different ways a report could include four quarters worth of sales figures in its detail lines — one doing things ’the hard way’ and one using the advanced
OCCURS
capabilities ofSTEP
andVARYING
. Both assume the definition of the following table exists in working-storage:05 SALES OCCURS 4 TIMES PIC 9(7)V99.
First, the “Hard Way”:
10 COL 7 PIC $(7)9.99 SOURCE SALES(1). 10 COL 17 PIC $(7)9.99 SOURCE SALES(2). 10 COL 27 PIC $(7)9.99 SOURCE SALES(3). 10 COL 37 PIC $(7)9.99 SOURCE SALES(4).
And then using
STEP
andVARYING
:10 COL 7 OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1 PIC $(7)9.99 SOURCE SALES(QTR).
- The optional
6.9.32. OVERLINE
OVERLINE Attribute Syntax
OVERLINE ~~~~~~~~
This syntax is valid in the following sections: SCREEN
The OVERLINE
clause will introduce a horizontal line at the top edge of a screen field.
- The
LEFTLINE
(see LEFTLINE),OVERLINE
andUNDERLINE
(see UNDERLINE) clauses may be used in any combination in a single field’s description. - This clause is essentially non-functional when used within Windows command shell (cmd.exe) environments and running programs compiled using a GnuCOBOL implementation built using “PDCurses” (such as Windows/MinGW builds).
- Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will depend upon the video attribute capabilities of the terminal output drivers and “curses” software being used.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.33. PICTURE
PICTURE Clause Syntax
PICTURE IS picture-string ~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
The picture clause defines the class (numeric, alphabetic or alphanumeric), size and format of the data that may be contained by the data item being defined. Sometimes this role is assisted by the USAGE
(see USAGE) clause, and in a few instances will be assumed entirely by that clause.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved word
PICTURE
may be abbreviated asPIC
. Most programmers prefer to use the latter. - A picture clause may only be specified on an elementary item.
- A picture-string is a sequence of the special symbols ‘$’, ‘*’, ‘+’, ‘,’, ‘-’, ‘.’, ‘/’, ‘0’ (zero), ‘9’, ‘A’, ‘B’,
CR
,DB
, ‘S’, ‘V’, ‘X’ and ‘Z’. - In general, each picture symbol represents either a single character in storage or a single decimal digit. There are a few exceptions, and they will be discussed as needed.
- When a picture-string contains a repeated sequence of symbols —
PIC 9999/99/99
— for example, the repetition can be specified using a parenthetic repeat count, as inPIC 9(4)/9(2)/9(2)
. Using repeat counts is optional and their use (or not) is entirely at the discretion of the programmer. Many programmers use repetition for small sequences (PIC XXX
) and repeat counts for larger ones (PIC 9(9)
. - This first set of picture symbols defines the basic data type of a data item. Each symbol represents a single character’s worth of storage.
- ‘A’
-
Defines storage reserved for a single alphabetic character (‘A’-‘Z’, ‘a’-‘z’).
- ‘N’
-
Defines storage reserved for a single character in the computer’s National Character set. Support for national character sets in GnuCOBOL is currently only partially implemented, and the compile- and run-time effect of using the ‘N’ picture symbol is the same as if
X(2)
had been coded, with the additional effect that such a field will qualify as aNATIONAL
orNATIONAL-EDITED
field on anINITIALIZE
(see INITIALIZE) statement. - ‘X’
-
Defines storage reserved for a single alphanumeric character (any character).
- ‘9’
Defines storage reserved for a single numeric digit character (‘0’-‘9’).
Typically, only one kind of each of those symbols is used in the same picture clause, but that isn’t a requirement. Data items that, of the three symbols above, use nothing but ‘A’ picture symbols are known as Alphabetic Data Items while those that use ‘9’ picture symbols without any ‘A’ or ‘X’ symbols (or those that have a
USAGE
without aPICTURE
) are known as Numeric Data Items. All other data items are referred to as Alphanumeric Data Items.If you need to allocate space for a data item whose format is two letters followed by five digits followed by three letters, you could use the picture-string
AA99999AAA
,A(2)9(5)A(3)
XXXXXXXXXX
orX(10)
. There is absolutely no functional difference whatsoever between the four — none of them provide any functionality the others do not. The first two probably make for better documentation of the expected field contents, but they don’t provide any run-time enforcement capabilities.As far as enforcement goes, however, both alphabetic and numeric picture strings do provide for both compile-time and run-time enforcement capabilities. In the case of compilation enforcement, the compiler can issue warning messages if you attempt to specify a non-numeric value for a numeric data item or if you attempt to
MOVE
(see MOVE) a non-numeric data item to one that is numeric. Similar capabilities exist for alphabetic data items. At run-time, you may use a special class test (see Class Conditions) to determine if the contents of a data item are entirely numeric or entirely alphabetic. - The following picture symbols may be used with numeric data items.
- ‘P’
-
Defines an implied digit position that will be considered to be a zero when the data item is referenced at run-time. This symbol is used to allow data items that will contain very large values to be allocated using less storage by assuming a certain number of trailing zeros (one per ‘P’) to exist at the end of values.
The ‘P’ symbol is not allowed in conjunction with ‘N’.
The ‘P’ symbol may only be used at the beginning or end of a picture clause.
‘P’ is a repeatable symbol.
All computations and
MOVE
(see MOVE) operations involving such a data item will behave as if the zeros were actually there.For example, let’s say you need to allocate a data item that contains however many millions of dollars of revenue your company has in gross revenues this year:
01 Gross-Revenue PIC 9(9).
In which case 9 characters of storage will be reserved. The values 000000000 through 999999999 will represent the gross-revenues. But, if only the millions are tracked (meaning the last six digits are always going to be 0), you could define the field as:
01 Gross-Revenue PIC 9(3)P(6).
Whenever Gross-Revenue is referenced in calculations, or whenever its value is moved to another data item, the value of Gross-Revenue will be treated as if it is
nnn000000
, wherennn
is the actual value in storage.If you wanted to store the value 128 million into that field, you would do so as if the ‘P’s were ‘9’s:
MOVE 128000000 TO Gross-Revenue
A
DISPLAY
(see DISPLAY) of a data item containing ‘P’ symbols is a little strange. The value displayed will be what is actually in storage, but the total size of the displayed value will be as if the ‘P’ symbols had been ‘9’s. Thus, after the above statement established a value for Gross-Revenue, aDISPLAY Gross-Revenue
would produce output of ‘000000128’. - ‘S’
-
This symbol, if used, must be the very first symbol in the
PICTURE
value. A ‘S’ indicates that the data item isSigned
, meaning that negative values are possible for this data item. Without an ‘S’, any negative values stored into this data item via aMOVE
or arithmetic statement will have the negative sign stripped from it (in effect becoming the absolute value).The ‘S’ symbol is not allowed in conjunction with ‘N’.
The ‘S’ symbol may only occur once in a picture string. See SIGN IS, for further discussion of how negative values may be stored in a numeric data item.
- ‘V’
-
This symbol is used to define where an implied decimal-point (if any) is located in a numeric item. Just as there may only be a single decimal point in a number so may there be no more than one ‘V’ in a
PICTURE
. Implied decimal points occupy no space in storage — they just specify how values are used. For example, if the value1234
is in storage in a field defined asPIC 999V9
, that value would be treated as 123.4 in any statements that referenced it.The ‘V’ symbol is not allowed in conjunction with ‘N’.
The ‘V’ symbol may only occur once in a picture string.
- Any editing symbols introduced past this point will, if coded in the picture clause of an otherwise numeric data item, transform that data item from a numeric to a Numeric Edited data item. Numeric edited data items are treated as alphanumeric and may not serve either as table subscripts or as source arguments on an arithmetic statement.
- The following are the fixed insertion editing symbols that may be specified in a picture string. Each of these editing symbols will insert a special character into the field value at the position it is specified in the picture string. These editing symbols will each introduce one extra character into the total field size for each occurrence of the symbol in the picture string.
- ‘B’
-
The ‘B’ editing symbol introduces a blank into the field value for each occurrence.
Multiple ‘B’ symbols may be coded.
The following example will format a ten digit number (presumably a telephone number) into a ‘### ### ####’ layout:
... 05 Phone-Number PIC 9(3)B9(3)B9(4). ... MOVE 5185551212 TO Phone-Number DISPLAY Phone-Number
This code will display ‘518 555 1212’.
- ‘0’
-
The ‘0’ (zero) editing symbol introduces one “0” character into the field value for each occurrence in the picture string.
Multiple ‘0’ symbols may be coded.
Here’s an example:
... 05 Output-Item PIC 909090909. ... MOVE 12345 TO Output-Item DISPLAY Output-Item
The above will display ‘102030405’.
- ‘/’
-
The ‘/’ editing symbol inserts one “/” character into the field value for each occurrence in the picture string.
Multiple ‘/’ symbols may be coded.
This editing symbol is most-frequently used to format dates, as follows:
... 05 Year-Month-Day PIC 9(4)/9(2)/9(2). ... MOVE 20140207 TO Year-Month-Day DISPLAY Year-Month-Day
This example displays ‘2014/02/07’.
- The following are the numeric formatting symbols that may be specified in a picture string. Each of these editing symbols will insert special characters into the field value to present numbers in a “friendly” format. These editing symbols will each introduce one extra character into the total field size for each occurrence of the symbol in the picture string. Numeric fields whose picture clause contains these characters may neither be used as source fields in any calculation nor may they serve as source fields for the transfer of data values to any data item other than an alphanumeric field.
- ‘.’
-
The ‘.’ symbol inserts a decimal point into a numeric field value. When the contents of a numeric data item sending field are moved into a receiving data item whose picture clause contains the ‘.’ editing symbol, implied (‘V’) or actual decimal point in the sending data item or literal, respectively, will be aligned with the ‘.’ symbol in the receiving field. Digits are then transferred from the sending to the receiving field outward from the sending field’s ‘V’ or ‘.’, truncating sending digits if there aren’t enough positions in the receiving field. Any digit positions in the receiving field that don’t receive digits from the sending field, if any, will be set to 0.
The ‘.’ symbol is not allowed in conjunction with ‘N’.
An example will probably help:
... 05 Source-Field PIC 9(2)V9 VALUE 7.2. 05 Dest-Field PIC 9(5).9(2). ... MOVE 1234567.89 TO Dest-Field DISPLAY Dest-Field MOVE 19 TO Dest-Field DISPLAY Dest-Field MOVE Source-Field TO Dest-Field DISPLAY Dest-Field
The example will display three results — ‘34567.89’, ‘00019.00’ and ‘00007.20’.
Both data item definitions appear to have two decimal points in their picture clauses. They actually don’t, because the last character of every data item definition is always a period — the period that ends the definition.
- ‘,’
-
The ‘,’ symbol serves as a thousands separator. Many times, you’ll see large numbers formatted with these symbols — for example, 123,456,789. This can be accomplished easily by adding thousands separator symbols to a picture string. Thousands separator symbols that aren’t needed will behave as if they were ‘9’s.
The ‘,’ symbol is not allowed in conjunction with ‘N’.
Here’s an example:
... 05 My-Lottery-Winnings PIC 9(3),9(3),9(3). ... MOVE 12345 TO My-Lottery-Winnings DISPLAY My-Lottery-Winnings
The value ‘0000012,345’ (a very disappointing one for my retirement plans, but a good thousands separator demo) will be displayed. Notice how, since the first comma wasn’t needed due to the meagre amount I won, it behaved like another ‘9’.
If desired, you may reverse the roles of the ‘.’ and ‘,’ editing symbols by specifying
DECIMAL POINT IS COMMA
in theSPECIAL-NAMES
(see SPECIAL-NAMES) paragraph. - The following are insertion symbols. They are used to insert an extra character (two in the case of
CR
andDB
) to signify the sign (positive or negative) of the numeric value that is moved into the field whose picture string contains one of these symbols, or the fact that the data item represents a currency (money) amount. Only one of the ‘+’, ‘-’,CR
orDB
symbols may be used in a picture clause. In this context, when any of these symbols are used in a picture-string, they must be at the end. The ‘+’, ‘-’ and/or currency symbols may also be used as floating editing symbols at the beginning of the picture-string — a subject that will be covered in the next numbered paragraph.- ‘+’
-
If the value of the numeric value moved into the field is positive (0 or greater), a ‘+’ character will be inserted. If the value is negative (less than 0), a ‘-’ character is inserted.
The ‘+’ symbol is not allowed in conjunction with ‘N’.
- ‘-’
-
If the value of the numeric value moved into the field is positive (0 or greater), a space will be inserted. If the value is negative (less than 0), a ‘-’ character is inserted.
The ‘-’ symbol is not allowed in conjunction with ‘N’.
CR
-
This symbol is coded as the two characters ‘C’ and ‘R’. If the value of the numeric value moved into the field is positive (0 or greater), two spaces will be inserted. If the value is negative (less than 0), the characters
CR
(credit) are inserted.The
CR
symbol is not allowed in conjunction with ‘N’. DB
-
This symbol is coded as the two characters ‘D’ and ‘B’. If the value of the numeric value moved into the field is positive (0 or greater), two spaces will be inserted. If the value is negative (less than 0), the characters
DB
(debit) are inserted.The
DB
symbol is not allowed in conjunction with ‘N’. - ‘$’
-
Regardless of the value moved into the field, this symbol will insert the currency symbol into the data item’s value in the position where it occurs in the picture-string (see SPECIAL-NAMES).
The ‘$’ symbol is not allowed in conjunction with ‘N’.
- These editing symbols are known as floating replacement symbols. These symbols may occur in sequences before any ‘9’ editing symbols in the picture-string of a numeric data item. Using these symbols transforms that numeric data item into a numerid edited data item, which can no longer be used in calculations or subscripts.
- Each of the following symbols behave like a ‘9’, until such point as all digits in the numeric value are exhausted and leading zeros are about to be inserted. In effect, these editing symbols define what should happen to those leading zero.
- ‘$’
-
Of those currency symbols that correspond to character positions in which leading zeros reside, the right-most will have its ‘0’ value replaced by the currency symbol in-effect for the program (see SPECIAL-NAMES). Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces.
The ‘$’ symbol is not allowed in conjunction with ‘N’.
Any currency symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’.
- ‘*’
-
This symbol is referred to as a check protection symbol. All check-protection symbols that correspond to character positions in which leading zeros reside will have their ‘0’ values replaced by ‘*’.
The ‘*’ symbol is not allowed in conjunction with ‘N’.
Any check-suppression symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’.
- ‘+’
-
Of those ‘+’ symbols that correspond to character positions in which leading zeros reside, the right-most will have its ‘0’ value replaced by a ‘+’ if the value in the data item is zero or greater or a ‘-’ otherwise. Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces. You cannot use both ‘+’ and ‘-’ in the same picture-string.
The ‘+’ symbol is not allowed in conjunction with ‘N’.
Any ‘+’ symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’.
- ‘-’
-
Of those ‘-’ symbols that correspond to character positions in which leading zeros reside, the right-most will have its ‘0’ value replaced by a space if the value in the data item is zero or greater or a ‘-’ otherwise. Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces. You cannot use both ‘+’ and ‘-’ in the same picture-string.
The ‘-’ symbol is not allowed in conjunction with ‘N’.
Any ‘-’ symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’.
- ‘Z’
-
All ‘Z’ symbols that correspond to character positions in which leading zeros reside will have their ‘0’ values replaced by spaces.
Any zero-suppression symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’.
‘Z’ and ‘*’ should not be coded in the same picture-string
‘+’ and ‘-’ should not be coded in the same picture-string
When multiple floating symbols are coded, even if there is only one of them used they will all be considered floating and will all be able to assume each other’s properties. For example, if a data item has a
PIC +$ZZZZ9.99
picture-string, and a value of 1 is moved to that field at run-time, the resulting value will be (the b symbol represents a space)bbbb+$1.00
. This is not consistent with many other COBOL implementations, where the result would have been+$bbbb1.00
.Most other COBOL implementations reject the use of multiple occurrences of multiple floating editing symbols. For example, they would reject picture-strings such as
+++$$$9.99
,$$$ZZZ9.99
and so on. GnuCOBOL accepts these. Programmers creating GnuCOBOL programs should avoid such picture-strings if there is any likelihood that those programs may be used with other COBOL implementations.
6.9.34. PRESENT WHEN
PRESENT-WHEN Clause Syntax
PRESENT WHEN condition-name ~~~~~~~ ~~~~
This syntax is valid in the following sections: REPORT
This clause names an existing Condition Name
(see Condition Names) that will serve as a switch controlling the presentation or suppression of a report group.
- If the specified condition-name has a value of FALSE when a
GENERATE
statement (see GENERATE) causes a report group to be presented, the presentation of that group will be suppressed. - If the condition-name has a value of
TRUE
, the group will be presented. - See Condition Names, for more information.
6.9.35. PROMPT
PROMPT Clause Syntax
PROMPT [ CHARACTER IS literal-1 | identifier-1 ] ~~~~~~ ~~~~~~~~~
This syntax is valid in the following sections: SCREEN
This clause defines the character that will be used as the fill-character for any input fields on the screen.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The default prompt character, should no
CHARACTER
specification be coded, or should thePROMPT
clause be absent altogether, is an underscore (‘_’). - Prompt characters will be automatically transformed into spaces upon input.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.36. PROTECTED
PROTECTED Attribute Syntax
PROTECTED SIZE IS { identifier } ~~~~~~~~ ~~~~ { integer }
This syntax is valid in the following sections: SCREEN
- The
PROTECTED
extended clause will effect the specified field to be limited in size, regardless of the picture size.2 - The SIZE phrase specifies the size (length) of the field. After the
ACCEPT
orDISPLAY
is finished, the cursor is placed immediately after the field defined by this clause, unless this would place the cursor outside of the current terminal window. In this case, the cursor is wrapped around to the beginning of the next line (scrolling the window if necessary). - If the
SIZE
phrase is not used, then the field length defaults to the size of the item being accepted or displayed. If theCONVERT
phrase is used, however, then the size of the field depends on the data type of the item and the verb being used.- If the
DISPLAY
verb is executing, then the size is the same as if theCONVERT
phrase were not specified except for numeric items. For numeric items, the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed. The remaining cases cover the size when anACCEPT
statement is used. - If the item is numeric or numeric edited, then the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed.
- If the item is alphanumeric edited, then the size is set to the number of ‘A’ or ‘X’ positions specified in its
PICTURE
clause. - For all other data types, the field size is set to the size of the item (same as if
CONVERT
were not specified).
- If the
- Note that the
OUTPUT
phrase changes the way in which the default field size is computed. See that heading above for details. Also note that theOUTPUT
phrase affects only the way items are displayed on the screen; the internal format of accepted data is not affected. - Note that you cannot supply the
CONVERT
phrase in the Screen Section. Thus the size of a Screen Section field is always the size of its screen entry unless theSIZE
phrase is specified.
6.9.37. REDEFINES
REDEFINES Clause Syntax
REDEFINES identifier-1 ~~~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
The REDEFINES
clause causes the data item in who’s definition the REDEFINES
clause is specified (hereafter referred to as the redefines object) to occupy the same physical storage space as identifier-1 (hereafter referred to as the redefines subject).
- The following rules must all be followed in order to use
REDEFINES
:- The level number of both the subject and object data items must be the same.
- The level numbers of both the subject and object data items cannot be 66, 78 or 88.
- If N represents the level number of the object, then no other data items with level number N may be defined between the subject and object data items unless they too are
REDEFINES
of the subject. - If N represents the level number of the object, then no other data items with a level number numerically less than N may be defined between the subject and object data items.
- The total allocated size of the subject data item must be the same as the total allocated size of the object data item.
- No
OCCURS
(see OCCURS) clause may be part of the definition of either the subject or object data items. Either or both, however, may be group items that contain data items withOCCURS
clauses. - No
VALUE
(see VALUE) clause may be defined on the object data item, and no data items subordinate to the object data item may haveVALUE
clauses, with the exception of level-88 condition names.
6.9.38. RENAMES
RENAMES Clause Syntax
RENAMES identifier-1 [ THRU|THROUGH identifier-2 ~~~~~~~ ~~~~ ~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
The RENAMES
clause regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.
- The reserved words
THRU
andTHROUGH
are interchangeable. - You must use the level number 66 for data description entries that contain the
RENAMES
clause. - The identifier-1 and identifier-2 data items, along with all data items defined between those two data items in the program source, must all be contained within the same 01-level record description.
- See 66-Level Data Items, for additional information on the
RENAMES
clause.
6.9.39. REQUIRED
REQUIRED Attribute Syntax
REQUIRED ~~~~~~~~
This syntax is valid in the following sections: SCREEN
This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if REQUIRED
is specified on a group item).
- The
EMPTY-CHECK
(see EMPTY-CHECK) andREQUIRED
clauses are interchangeable, and may not be used together in the same data item description. - In order to take effect, the user must first move the cursor into the field having this clause in its definition.
- The
ACCEPT screen-data-item
statement (see ACCEPT screen-data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless data has been entered into the field. Function keys will still be allowed to terminate theACCEPT
. - In order to be functional, this attribute must be supported by the underlying “curses” package your GnuCOBOL implementation was built with. As of this time, the “PDCurses” package (used for native Windows or MinGW builds) does not support
REQUIRED
.
6.9.40. REVERSE-VIDEO
REVERSE-VIDEO Attribute Syntax
REVERSE-VIDEO ~~~~~~~~~~~~~
This syntax is valid in the following sections: SCREEN
The REVERSE-VIDEO
attribute swaps the specified or implied FOREGROUND-COLOR
(see FOREGROUND-COLOR) and BACKGROUND-COLOR
(see BACKGROUND-COLOR) attributes for the field whose definition contains this clause (or all subordinate fields if used on a group item).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.41. SECURE
SECURE Attribute Syntax
SECURE ~~~~~~
This syntax is valid in the following sections: SCREEN
This clause will cause all data entered into the field to appear on the screen as asterisks.
- The
NO-ECHO
(see NO-ECHO) andSECURE
clauses are interchangeable, and may not be used together in the same data item description. - This clause may only be used on a field allowing data entry (a field containing either the
USING
(see USING) orTO
(see TO) clause).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.42. SIGN IS
SIGN-IS Clause Syntax
SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
This clause, allowable only for USAGE DISPLAY
numeric data items, specifies how an ‘S’ symbol will be interpreted in a data item’s picture clause.
- The reserved words
CHARACTER
andIS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Without the
SEPARATE CHARACTER
option, the sign of the data item’s value will be encoded by transforming the last (seeTRAILING
) or first (seeLEADING
) digit as follows:First/Last Digit Value For Positive Value for Negative 0 0 p 1 1 q 2 2 r 3 3 s 4 4 t 5 5 u 6 6 v 7 7 w 8 8 x 9 9 y - If the
SEPARATE CHARACTER
clause is used, then an actual ‘+’ or ‘-’ character will be inserted into the field’s value as the first (LEADING
) or last (TRAILING
) character. Note that having this character embedded within the data item’s storage does not prevent the data item from being used as a source field in arithmetic operations. - When
SEPARATE CHARACTER
is specified, the ‘S’ symbol in the data item’sPICTURE
must be counted when determining the data item’s size. - Neither the presence of an encoded digit (see above) nor an actual ‘+’ or ‘-’ character embedded within the data item’s storage prevents the data item from being used as a source field in arithmetic operations.
6.9.43. SOURCE
SOURCE Clause Syntax
SOURCE IS literal-1 | identifier-1 [ ROUNDED ] ~~~~~~ ~~~~~~~
This syntax is valid in the following sections: REPORT
This clause logically attaches a report section data item to another data item defined elsewhere in the data division.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - When the report group containing this clause is presented, the value of the specified numeric literal or identifier will be automatically moved to the report data item prior to presentation.
- The specified identifier may be defined anywhere in the data division, but if it is defined in the report section it may only be
PAGE-COUNTER
,LINE-COUNTER
or aSUM
(see SUM) counter. - The
PICTURE
(see PICTURE) of the report data item must be such that it would be legal toMOVE
(see MOVE) the specified literal or identifier to a data item with thatPICTURE
. - The
ROUNDED
option comes into play should the number of digits to the right of an actual or assumed decimal point be different between the specified literal or identifier value (the “source value”) and thePICTURE
specified for the field in whose definition theSOURCE
clause appears (the “target field”). WithoutROUNDED
, excess digits in the source value will simply be truncated to fit the target field. WithROUNDED
, the source value will be arithmetically rounded to fit the target field. See ROUNDED, for information on theNEAREST-AWAY-FROM-ZERO
rounding rule, which is the one that will apply.
6.9.44. SUM OF
SUM-OF Clause Syntax
SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] ~~~ { literal-2 } { ~~~~~ ~~~~~ } { UPON identifier-9 } ~~~~
This syntax is valid in the following sections: REPORT
The SUM
clause establishes a summation counter whose value will be arithmetically calculated whenever the field is presented.
- The reserved words
OF
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The
SUM
clause may only appear in aCONTROL FOOTING
report group. - If the data item in which the
SUM
clause appears has been assigned its own identifier name, and that name is notFILLER
, then that data item is referred to as a sum counter. - All identifier-7 data items must be non-edited numeric in nature.
- If any identifier-7 data item is defined in the report section, it must be a sum counter.
- Any identifier-7 data items that are sum counters must either be defined in the same report group as the data item in which this
SUM
clause appears or they must be defined in a report data item that exists at a lower level in this report’s control hierarchy. See Control Hierarchy, for additional information. - The
PICTURE
of the report data item in who’s description thisSUM
clause appears in must be such that it would be legal toMOVE
(see MOVE) the specified identifier-7 or literal-2 value to a data item with thatPICTURE
. - The following points apply to the
UPON
option:- The data item identifier-9 must be the name of a detail group specified in the same report as the control footing group in which this
SUM
clause appears. - The presence of an
UPON
clause limits theSUM
clause to adding the specified numeric literal or identifier value into the sum counter only when aGENERATE identifier-9
statement is executed. - If there is no
UPON
clause specified, the value of identifier-7 or literal-2 will be added into the sum counter whenever aGENERATE
(see GENERATE) of any detail report group in the report is executed. - If there is only a single detail group in the report’s definition, the
UPON
clause is meaningless.
- The data item identifier-9 must be the name of a detail group specified in the same report as the control footing group in which this
- The following points apply to the
RESET
option:- If the
RESET
option is coded,FINAL
or identifier-8 (whichever is coded on theRESET
) must be one of the report’s control breaks specified on theCONTROLS
clause. - If there is no
RESET
option coded, the sum counter will be reset back to zero after each time the control footing containing theSUM
clause is presented. This is the typical behaviour that would be expected. - If, however, you want to reset the
SUM
counter only when the control footing for a control break higher in the control hierarchy is presented, specify that higher control break on theRESET
option.
- If the
6.9.45. SYNCRONIZED
SYNCRONIZED Syntax
SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ~~~~ ~~~~ ~~~~ ~~~~~
The LEFT
and RIGHT
(SYNCRONIZED) clauses are syntactically recognized but are otherwise non-functional.
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
This optional clause optimizes the storage of binary numeric items to store them in such a manner as to make it as fast as possible for the CPU to fetch them.
- The reserved words
SYNCRONIZED
andSYNCHRONISED
are interchangeable, and may be abbreviated asSYNC
. - If the
SYNCRONIZED
clause is coded on anything but a numeric data item with aUSAGE
(see USAGE) that specifies storage of data in a binary form, theSYNCRONIZED
clause will be ignored. - Synchronization is performed (by the compiler) as follows:
- If the binary item occupies one byte of storage, no synchronization is performed.
- If the binary item occupies two bytes of storage, the binary item is allocated at the next half-word boundary.
- If the binary item occupies four bytes of storage, the binary item is allocated at the next word boundary.
- If the binary item occupies four bytes of storage, the binary item is allocated at the next word boundary.
6.9.46. TO
TO Clause Syntax
TO identifier-5 ~~
This syntax is valid in the following sections: SCREEN
This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.
- The
TO
clause is used to define a data-entry field with no initial value; when a value is entered, it will be saved to the specified identifier. - The
FROM
(see FROM),TO
,USING
(see USING) andVALUE
(see VALUE) clauses are mutually-exclusive in any screen section data item’s definition.
6.9.47. TYPE
TYPE Clause Syntax
[ TYPE IS { RH|{REPORT HEADING} } ] ~~~~ { ~~ ~~~~~~ ~~~~~~~ } { PH|{PAGE HEADING} } { ~~ ~~~~ ~~~~~~~ } { CH|{CONTROL HEADING} FINAL|identifier-2 } { ~~ ~~~~~~~ ~~~~~~~ ~~~~~ } { DE|DETAIL } { ~~ ~~~~~~ } { CF|{CONTROL FOOTING} FINAL|identifier-2 } { ~~ ~~~~~~~ ~~~~~~~ ~~~~~ } { PF|{PAGE FOOTING} } { ~~ ~~~~ ~~~~~~~ } { RF|{REPORT FOOTING} } ~~ ~~~~~~ ~~~~~~~
This syntax is valid in the following sections: REPORT
This clause defines the type of report group that is being defined for a report.
- This clause is required on any 01-level data item definitions (other than 01-level constants) in the report section. This clause is invalid on any other report section data item definitions.
- There may be a maximum of one (1) report group per
RD
defined with aTYPE
ofREPORT HEADING
,PAGE HEADING
,PAGE FOOTING
andREPORT FOOTING
. - There must be either a
CONTROL HEADING
or aCONTROL FOOTING
or both specified for each entry specified on theCONTROLS ARE
clause of theRD
. - The various report groups that constitute a report may be defined in any order.
- See RWCS Lexicon, for a description of the seven different types of report groups.
6.9.48. UNDERLINE
UNDERLINE Attribute Syntax
UNDERLINE ~~~~~~~~~
This syntax is valid in the following sections: SCREEN
The UNDERLINE
clause will introduce a horizontal line at the bottom edge of a screen field.
- The
LEFTLINE
(see LEFTLINE),OVERLINE
(see OVERLINE) andUNDERLINE
clauses may be used in any combination in a single field’s description. - This clause is essentially non-functional when used within Windows command shell (cmd.exe) environments and running programs compiled using a GnuCOBOL implementation built using “PDCurses” (such as Windows/MinGW builds).
- Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will depend upon the video attribute capabilities of the terminal output drivers and “curses” software being used.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
6.9.49. USAGE
USAGE Clause Syntax
USAGE IS data-item-usage ~~~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
The USAGE
clause defines the format that will be used to store the value of a data item.
- The reserved word
IS
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The following table summarizes the various USAGE specifications available in GnuCOBOL.
BINARY
~~~~~~
Range of Values: Defined by the quantity of ‘9’s and the presence or absence of an ‘S’ in the PICTURE
Storage Format: Compatible Binary Integer Negative Values Allowed?: If PICTURE
contains ‘S’PICTURE
Used?:Yes BINARY-C-LONG [ SIGNED ]
~~~~~~~~~~~~~
Same as BINARY-DOUBLE SIGNED
BINARY-C-LONG UNSIGNED
~~~~~~~~~~~~~ ~~~~~~~~
Range of Values: Typically 0 – 4,294,967,295 Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No BINARY-CHAR [ SIGNED ]
~~~~~~~~~~~
Range of Values: -128 – 127 Storage Format: Native Binary Integer Negative Values Allowed?: Yes PICTURE
Used?:No BINARY-CHAR UNSIGNED
~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 – 255 Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No BINARY-DOUBLE [ SIGNED ]
~~~~~~~~~~~~~
Range of Values: -9,223,372,036,854,775,808 – 9,223,372,036,854,775,807 Storage Format: Native Binary Integer Negative Values Allowed?: Yes PICTURE
Used?:No BINARY-DOUBLE UNSIGNED
~~~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 – 18,446,744,073,709,551,615 Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No BINARY-INT
~~~~~~~~~~
Same as BINARY-LONG SIGNED
BINARY-LONG [ SIGNED ]
~~~~~~~~~~~
Range of Values: -2,147,483,648 – 2,147,483,647 Storage Format: Native Binary Integer Negative Values Allowed?: Yes PICTURE
Used?:No BINARY-LONG UNSIGNED
~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 – 4,294,967,295 Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No BINARY-LONG-LONG
~~~~~~~~~~~~~~~~
Same as BINARY-DOUBLE SIGNED
BINARY-SHORT [ SIGNED ]
~~~~~~~~~~~~
Range of Values: -32,768 – 32,767 Storage Format: Native Binary Integer Negative Values Allowed?: Yes PICTURE
Used?:No BINARY-SHORT UNSIGNED
~~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 – 65,535 Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No COMPUTATIONAL
~~~~
Same as BINARY
COMP[UTATIONAL]-1
~~~~ ~~
Same as FLOAT-SHORT
COMP[UTATIONAL]-2
~~~~ ~~
Same as FLOAT-LONG
COMP[UTATIONAL]-3
~~~~ ~~
Same as PACKED-DECIMAL
COMP[UTATIONAL]-4
~~~~ ~~
Same as BINARY
COMP[UTATIONAL]-5
~~~~ ~~
Range of Values: Depends on number of ‘9’s in the PICTURE
and thebinary-size
setting of the configuration file used to compile the programStorage Format: Native Binary Integer Negative Values Allowed?: If PICTURE
contains ‘S’PICTURE
Used?:Yes COMP[UTATIONAL]-6
~~~~ ~~
Range of Values: Defined by the quantity of ‘9’s and the presence or absence of an ‘S’ in the PICTURE
Storage Format: Unsigned Packed Decimal Negative Values Allowed?: No PICTURE
Used?:Yes COMP[UTATIONAL]-X
~~~~ ~~
Range of Values: If used with PIC X
, allocates one byte of storage per ‘X’; range of values is 0 to max storable in that many bytes. If used withPIC 9
, range of values depends on number of ‘9’s in PICTUREStorage Format: Native unsigned (X) or signed (9) Binary Negative Values Allowed?: If PICTURE
9 and contains ‘S’PICTURE
Used?:Yes DISPLAY
~~~~~~~
Range of Values: Depends on PICTURE
— One character per X, A, 9, period, $, Z, 0, *, S (ifSEPARATE CHARACTER
specified), +, - or B symbol inPICTURE
; Add 2 more bytes if theDB
orCR
editing symbol is usedStorage Format: Characters Negative Values Allowed?: If PICTURE
contains ‘S’PICTURE
Used?:Yes FLOAT-DECIMAL-16
~~~~~~~~~~~~~~~~
Range of Values: -9.999999999999999 * 10383 – 9.999999999999999 * 10384 Storage Format: Native IEEE 754 Decimal64 Floating-point Negative Values Allowed?: Yes PICTURE
Used?:No FLOAT-DECIMAL-34
~~~~~~~~~~~~~~~~
Range of Values: -9.99999... * 106143 – 9.99999... * 106144 Storage Format: Native IEEE 754 Decimal128 Floating-point Negative Values Allowed?: Yes PICTURE
Used?:No FLOAT-LONG
~~~~~~~~~~
Range of Values: Approximately -1.797693134862316 * 10308 – 1.797693134862316 * 10308 Storage Format: Native IEEE 754 Binary64 Floating-point Negative Values Allowed?: Yes PICTURE
Used?:No FLOAT-SHORT
~~~~~~~~~~~
Range of Values: Approximately -3.4028235 * 1038 – 3.4028235 * 1038 Storage Format: Native IEEE 754 Binary32 Negative Values Allowed?: Yes PICTURE
Used?:No INDEX
~~~~~
Range of Values: 0 to maximum address possible (32 or 64 bits) Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No NATIONAL
~~~~~~~~
USAGE NATIONAL
, while syntactically recognized, is not supported by GnuCOBOLPACKED-DECIMAL
~~~~~~~~~~~~~~
Range of Values: Defined by the quantity of ‘9’s and the presence or absence of an ‘S’ in the PICTURE Storage Format: Signed Packed Decimal Negative Values Allowed?: If PICTURE
contains ‘S’PICTURE
Used?:Yes POINTER
~~~~~~~
Range of Values: 0 to maximum address possible (32 or 64 bits) Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No PROCEDURE-POINTER
~~~~~~~~~~~~~~~~~
Same as PROGRAM-POINTER
PROGRAM-POINTER
~~~~~~~~~~~~~~~
Range of Values: 0 to maximum address possible (32 or 64 bits) Storage Format: Native Binary Integer Negative Values Allowed?: No PICTURE
Used?:No SIGNED-INT
~~~~~~~~~~
Same as BINARY-LONG SIGNED
SIGNED-LONG
~~~~~~~~~~~
Same as BINARY-DOUBLE SIGNED
SIGNED-SHORT
~~~~~~~~~~~~
Same as BINARY-SHORT SIGNED
UNSIGNED-INT
~~~~~~~~~~~~
Same as BINARY-LONG UNSIGNED
UNSIGNED-LONG
~~~~~~~~~~~~~
Same as BINARY-DOUBLE UNSIGNED
UNSIGNED-SHORT
~~~~~~~~~~~~~~
Same as BINARY-SHORT UNSIGNED
- Binary data (integer or floating-point) can be stored in either a Big-Endian or Little-Endian form.
Big-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the least-significant byte is the right-most byte. For example, a four-byte binary item having a value of decimal 20 would be big-endian allocated as 00000014 (shown in hexadecimal notation).
Little-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the least-significant byte is the left-most byte. For example, a four-byte binary item having a value of decimal 20 would be little-endian allocated as 14000000 (shown in hexadecimal notation).
All CPUs are capable of understanding big-endian format, which makes it the most compatible form of binary storage across computer systems.
Some CPUs — such as the Intel/AMD i386/x64 architecture processors used in most Windows PCs — prefer to process binary data stored in a little-endian format. Since that format is more efficient on those systems, it is referred to as the native binary format.
On a system supporting only one format of binary storage (generally, that would be big-endian), the terms most efficient and native format are synonymous.
- Data items that have the
UNSIGNED
attribute explicitly coded, orDISPLAY
,PACKED-DECIMAL
,COMP-5
,COMP-X
items that do not have an ‘S’ symbol in their picture clause cannot preserve negative values that may be stored into them. Storing a negative value into such a field will actually result in the sign being stripped, essentially saving the absolute value in the data item. - Packed-decimal (i.e.
USAGE PACKED-DECIMAL
,USAGE COMP-3
orUSAGE COMP-6
) data is stored as a series of bytes such that each byte contains two 4-bit fields, referred to as nibbles (since they comprise half a “byte”, they’re just “nibbles” — don’t groan, I don’t just make this stuff up!). Each nibble represents a ‘9’ in thePICTURE
and each holds a single decimal digit encoded as its binary value (0 = 0000, 1 = 0001, … , 9 = 1001).The last byte of a
PACKED-DECIMAL
orCOMP-3
data item will always have its left nibble corresponding to the last ‘9’ in thePICTURE
and its right nibble reserved as a sign indicator. This sign indicator is always present regardless of whether or not thePICTURE
included an ‘S’ symbol.The first byte of the data item will contain an unused left nibble if the
PICTURE
had an even number of ‘9’ symbols in it.The sign indicator will have a value of a hexadecimal A through F. Traditional packed decimal encoding rules call for hexadecimal values of F, A, C or E (“FACE”) in the sign nibble to indicate a positive value and B or D to represent a negative value (hexadecimal digits 0-9 are undefined). Testing with a Windows MinGW/GnuCOBOL implementation shows that — in fact — hex digit D represents a negative number and any other hexadecimal digit denotes a positive number. Therefore, a
PIC S9(3) COMP-3
packed-decimal field with a value of -15 would be stored internally as a hexadecimal 015D in GnuCOBOL.If you attempt to store a negative number into a packed decimal field that has no ‘S’ in its
PICTURE
, the absolute value of the negative number will actually be stored.USAGE COMP-6
does not allow for negative values, therefore no sign nibble will be allocated. AUSAGE COMP-6
data item containing an odd number of ‘9’ symbols in itsPICTURE
will leave its leftmost nibble unused. - The
USAGE
specificationsFLOAT-DECIMAL-16
andFLOAT-DECIMAL-34
will encode data using IEEE 754 Decimal64 and Decimal128 format, respectively. The former allows for up to 16 digits of exact precision while the latter offers 34. The phrase “exact precision” is used because the traditional binary renderings of decimal real numbers in a floating-point format (FLOAT-LONG
andFLOAT-SHORT
, for example) only yield an approximation of the actual value because many decimal fractions cannot be precisely rendered in binary. The Decimal64 and Decimal128 renderings, however, render decimal real numbers in encoded decimal form in much the same way thatPACKED-DECIMAL
renders a decimal integer in digit-by-digit decimal form. The exact manner in which this rendering is performed is complex (Wikipedia has an excellent article on the subject — just search for Decimal64). - GnuCOBOL stores
FLOAT-DECIMAL-16
andFLOAT-DECIMAL-34
data items using either Big-Endian or Little-Endian form, whichever is native to the system. - The
USAGE
specificationsFLOAT-LONG
andFLOAT-SHORT
use the IEEE 754 Binary64 and Binary32 formats, respectively. These are binary encodings of real decimal numbers, and as such cannot represent every possible value between the minimum and maximum values in the range for those usages. Wikipedia has an excellent article on the Binary64 and Binary32 encoding schemes — just search on Binary32 or Binary64.GnuCOBOL stores
FLOAT-LONG
andFLOAT-SHORT
data items using either Big-Endian or Little-Endian form, whichever is native to the system. - A
USAGE
clause specified at the group item level will apply thatUSAGE
to all subordinate data items, except those that themselves have aUSAGE
clause. - The only
USAGE
that is allowed in the report section isUSAGE DISPLAY
.
6.9.50. USING
USING Clause Syntax
USING identifier-1 ~~~~~
This syntax is valid in the following sections: SCREEN
This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.
- When the screen item whose definition this clause is part of is displayed, the value currently in identifier-1 will be automatically moved into the screen item first.
- When the screen item whose definition this clause is part of (or its parent) is accepted, the current contents of the screen item will be saved back to identifier-1 at the conclusion of the
ACCEPT
. - The
FROM
(see FROM),TO
(see TO),USING
andVALUE
(see VALUE) clauses are mutually-exclusive in any screen section data item’s definition.
6.9.51. VALUE
VALUE (Condition Names) Clause Syntax
{ VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}... { ~~~~~ } ~~~~ ~~~~~~~ { VALUES ARE } ~~~~~~
VALUE (Other Data Items) Syntax
VALUE IS [ ALL ] literal-1 ~~~~~ ~~~
This syntax is valid in the following sections: FILE
, WORKING-STORAGE
, LOCAL-STORAGE
, LINKAGE
, REPORT
, SCREEN
The VALUE
clause is used to define condition names or to assign values (at compilation time) to data items.
- The reserved words
ARE
andIS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - This clause cannot be specified on the same data item as a
FROM
(see FROM),TO
(see TO) orUSING
(see USING) clause. - The following points apply to using the
VALUE
clause in the definition of a condition name:- The clauses
VALUE IS
andVALUES ARE
are interchangeable. - The reserved words
THRU
andTHROUGH
are interchangeable. - See 88-Level Data Items, for a discussion of how this format of
VALUE
is used to create condition names. - See Condition Names, for a discussion of how condition names are used.
- The clauses
- The following points apply to using the
VALUE
clause in the definition of any other data item:- In this context,
VALUE
specifies an initial compilation-time value that will be assigned to the storage occupied by the data item in the program object code generated by the compiler. - The
VALUE
clause is ignored onEXTERNAL
(see EXTERNAL) data items or on any data items defines as subordinate to anEXTERNAL
data item. - This format of the
VALUE
clause may not be used anywhere in the description of an 01 item (or any of its subordinate items) serving as anFD
orSD
record description. - If the optional
ALL
clause is used, it may only be used with an alphanumeric literal value; the value will be repeated as needed to completely fill the data item. Here are some examples with and withoutALL
(the symbol b denotes a space):PIC X(5) VALUE ‘A’ *> Abbbb PIC X(5) VALUE ALL ‘A’ *> AAAAA PIC 9(3) VALUE 1 *> 001 PIC 9(3) VALUE ALL ‘1’ *> 111
- When used in the definition of a screen data item:
- A figurative constant may not be supplied as literal-1.
- Any
FROM
(see FROM),TO
(see TO) orUSING
(see USING) clause in the same data item’s definition will be ignored. - If there is no picture clause specified, the size of the screen data item will be the length of the literal-1 value.
- If there is no picture clause and the
ALL
option is specified, theALL
option will be ignored.
- Giving a table an initial, compile-time value is one of the trickier aspects of COBOL data definition. There are basically three standard techniques and a fourth that people familiar with other COBOL implementations but new to GnuCOBOL may find interesting. So, here are the three standard approaches:
- Don’t bother worrying about it at compile-time. Use the
INITIALIZE
(see INITIALIZE) to initialize all data item occurrences in a table (at run-time) to their data-type-specific default values (numerics: 0, alphabetic and alphanumerics: spaces). - Initialize small tables at compile time by including a
VALUE
clause on the group item that serves as a parent to the table, as follows:05 SHIRT-SIZES VALUE "S 14M 15L 16XL17". 10 SHIRT-SIZE-TBL OCCURS 4 TIMES. 15 SST-SIZE PIC X(2). 15 SST-NECK PIC 9(2).
- Initialize tables of almost any size at compilation time by utilizing the
REDEFINES
(see REDEFINES) clause:05 SHIRT-SIZE-VALUES. 10 PIC X(4) VALUE "S 14". 10 PIC X(4) VALUE "M 15". 10 PIC X(4) VALUE "L 16". 10 PIC X(4) VALUE
XL17
. 05 SHIRT-SIZES REDEFINES SHIRT-SIZE-VALUES. 10 SHIRT-SIZE-TBL OCCURS 4 TIMES. 15 SST-SIZE PIC X(2). 15 SST-NECK PIC 9(2).Admittedly, this table is much more verbose than the one shown with a group
VALUE
. What is good about this initialization technique, however, is that you can have as manyFILLER
andVALUE
items as you need for a larger table, and those values can be as long as necessary!
- Don’t bother worrying about it at compile-time. Use the
- Many COBOL compilers do not allow the use of
VALUE
andOCCURS
(see OCCURS) on the same data item; additionally, they don’t allow aVALUE
clause on a data item subordinate to anOCCURS
. GnuCOBOL, however, has neither of these restrictions!Observe the following example, which illustrates a fourth manner in which tables may be initialized in GnuCOBOL:
05 X OCCURS 6 TIMES. 10 A PIC X(1) VALUE '?'. 10 B PIC X(1) VALUE '%'. 10 N PIC 9(2) VALUE 10.
In this example, all six ‘A’ items will be initialized to ‘?’, all six ‘B’ items will be initialized to ‘%’ and all six ‘N’ items will be initialized to 10. It’s not clear exactly how many times this sort of initialization will be useful, but it’s there if you need it.
- In this context,
- The
FROM
(see FROM),TO
(see TO),USING
(see USING) andVALUE
clauses are mutually-exclusive in any screen section data item’s definition.
7. PROCEDURE DIVISION
PROCEDURE DIVISION Syntax
PROCEDURE DIVISION [ { USING Subprogram-Argument... } ] ~~~~~~~~~ ~~~~~~~~ { ~~~~~ } { CHAINING Main-Program-Argument...} ~~~~~~~~ [ RETURNING identifier-1 ] . [ DECLARATIVES. ] ~~~~~~~~~ ~~~~~~~~~~~~ [ Event-Handler-Routine... . ] [ END DECLARATIVES. ] ~~~ ~~~~~~~~~~~~ General-Program-Logic [ Nested-Subprogram... ] [ END PROGRAM|FUNCTION name-1 ] ~~~ ~~~~~~~ ~~~~~~~~
The PROCEDURE DIVISION
of any GnuCOBOL program marks the point where all executable code is written.
7.1. PROCEDURE DIVISION USING
PROCEDURE DIVISION Subprogram-Argument Syntax
[ BY { REFERENCE [ OPTIONAL ] } ] identifier-1 { ~~~~~~~~~ ~~~~~~~~ } { VALUE [ [ UNSIGNED ] SIZE IS { AUTO } ] } ~~~~~ ~~~~~~~~ ~~~~ { ~~~~ } { DEFAULT } { ~~~~~~~ } { integer-1 }
The USING
clause defines the arguments that will be passed to a GnuCOBOL program which is serving as a subprogram.
- The reserved words
BY
andIS
are optional and may be omitted. The presence or absence of these words have no effect upon the program. - The
USING
clause should only be used on the procedure division header of subprograms (subroutines or user-defined functions). - The calling program will pass zero or more data items, known as arguments, to this subprogram — there must be exactly as many identifier-1 data items specified on the
USING
clause as the maximum number of arguments the subprogram will ever be passed. - If a subprogram does not expect any arguments, it should not have a
USING
clause specified on its procedure division header. - The order in which arguments are defined on the
USING
clause must correspond to the order in which those arguments will be passed to the subprogram by the calling program. - The identifiers specified on the
USING
clause must be defined in the linkage section of the subprogram. No storage is actually allocated for those identifiers in the subprogram as the actual storage for them will exist in the calling program. - A GnuCOBOL subprogram expects that all arguments to it will be one of two things:
- The memory address of the actual data item (allocated in the calling program) that is being passed to the subprogram.
- A numeric, full-word, binary value (i.e.
USAGE BINARY-LONG
(see USAGE)) which is the actual argument being passed to the subprogram.
In the case of the former, the
USING
clause on the procedure division header should describe the argument via theBY REFERENCE
clause — in the latter case, aBY VALUE
specification should be coded. This allows the code generated by the compiler to properly reference the subprogram arguments at run-time. -
BY REFERENCE
is the assumed default for the firstUSING
argument should noBY
clause be specified for it. Subsequent arguments will assume theBY
specification of the argument prior to them should they lack aBY
clause of their own. - Changes made by a subprogram to the value of an argument specified on the
USING
clause will “be visible” to the calling program only ifBY REFERENCE
was explicitly specified or implicitly assumed for the argument on the subprogram’s procedure division header and the argument was passed to the subprogramBY REFERENCE
by the calling program. See Subprogram Arguments, for additional information on the mechanics of how arguments are passed to subprograms. - The optional
SIZE
clause allows you to specify the number of bytes aBY VALUE
argument will occupy, withSIZE DEFAULT
specifying 4 bytes (this is the default if noSIZE
clause is used),SIZE AUTO
specifying the size of the argument in the calling program andSIZE integer-1
specifying a specific byte count. - The optional
UNSIGNED
keyword, legal only ifSIZE AUTO
orSIZE integer-1
are coded, will add theunsigned
attribute to the argument’s specification in the C-language function header code generated for the subprogram. While not of any benefit when the calling program is a GnuCOBOL program, this can improve compatibility with a C-language calling program. - The
OPTIONAL
keyword, legal only onBY REFERENCE
arguments, allows calling programs to codeOMITTED
for that corresponding argument when they call this subprogram. See CALL. for additional information on this feature.
7.2. PROCEDURE DIVISION CHAINING
PROCEDURE DIVISION Main-Program-Argument Syntax
[ BY REFERENCE ] [ OPTIONAL ] identifier-1 ~~~~~~~~~ ~~~~~~~~
The CHAINING
term provides one mechanism a programmer may use to retrieve command-line arguments passed to a program at execution time.
-
PROCEDURE DIVISION CHAINING
may only be coded in a main program (that is, the first program executed when a compiled GnuCOBOL compilation unit is executed). It cannot be used in any form of subprogram. - The
CHAINING
clause defines arguments that will be passed to a main program from the operating system. The argument identifiers specified on theCHAINING
clause will be populated by character strings comprised of the parameters specified to the program on the command line that executed it, as follows:- When a GnuCOBOL program is executed from a command-line, the complete command line text will be broken into a series of tokens, where each token is identified as being a word separated from the others in the command text by at least one space. For example, if the command line was
/usr/local/myprog THIS IS A TEST
, there will be five tokens identified by the operating system — ‘/usr/local/myprog’, ‘THIS’, ‘IS’, ‘A’ and ‘TEST’. - Multiple space-delimited tokens may be treated as a single token by enclosing them in quotes. For example, there are only three tokens generated from the command line
C:\Pgms\myprog.exe ‘THIS IS A’ TEST
— ‘C:\Pgms\myprog.exe’, ‘THIS IS A’ and ‘TEST’. When quote characters are used to create multi-word tokens, the quote characters themselves are stripped from the token’s value. - Once tokens have been identified, the first one (the command) will be discarded; the rest will be stored into the
CHAINING
arguments when the program begins execution, with the 2nd token going to the 1st argument, the 3rd token going to the 2nd argument and so forth. - If there are more tokens than there are arguments, the excess tokens will be discarded.
- If there are fewer tokens than there are arguments, the excess arguments will be initialized as if the
INITIALIZE identifier-1
(see INITIALIZE) statement were executed. - All identifiers specified on the
CHAINING
clause should be defined asPIC X, PIC A
, group items (which are treated implicitly asPIC X
) or asPIC 9 USAGE DISPLAY
. The use ofUSAGE BINARY
(or the like) data items asCHAINING
arguments is not recommended as all command-line tokens will be retained in their original character form as they are moved into the argument data items. - If an argument identifier is smaller in storage size than the token value to be stored in it, the right-most excess characters of the token value will be truncated as the value is moved in. Any
JUSTIFIED RIGHT
clause on such an argument identifier will be ignored. - If an argument is larger in storage size than the token value to be stored in it, the token value will be moved into the argument identifier in a left-justified manner. unmodified-modified byte positions in the identifier will be space filled, unless the argument identifier is defined as
PIC 9 USAGE DISPLAY
, in which case unmodified bytes will be filled with ‘0’ characters from the systems native character set.This behaviour when the argument is defined as
PIC 9
may be unacceptable, as an argument defined asPIC 9(3)
but passed in a value of ‘1’ from the command line will receive a value of ‘100’, not ‘001’. Consider defining “numeric” command line arguments asPIC X
and then using theNUMVAL
intrinsic function (see NUMVAL) function to determine the proper numeric value.
- When a GnuCOBOL program is executed from a command-line, the complete command line text will be broken into a series of tokens, where each token is identified as being a word separated from the others in the command text by at least one space. For example, if the command line was
7.3. PROCEDURE DIVISION RETURNING
PROCEDURE DIVISION RETURNING Syntax
RETURNING identifier-1 ~~~~~~~~~
The RETURNING clause on the PROCEDURE DIVISION header documents that the subprogram in which the clause appears will be returning a numeric value back to the program that called it.
- The
RETURNING
clause is optional within a subroutine, as not all subroutines return a value to their caller. - The
RETURNING
clause is mandatory within a user-defined function, as all such must return a numeric result. - The identifier-1 data item should be defined as a
USAGE BINARY-LONG
data item. - Main programs that wish to “pass back” a return code value to the operating system when they exit do not use
RETURNING
- they do so simply by MOVEing a value to theRETURN-CODE
special register. - This is not the only mechanism that a subprogram may use to pass a value back to its caller. Other possibilities are:
- The subprogram may modify any argument that is specified as
BY REFERENCE
on itsPROCEDURE DIVISION
header. Whether the calling program can actually “see” any modifications depends upon how the calling program passed the argument to the subprogram. See CALL, for more information. - A data item with the
GLOBAL
(see GLOBAL) attribute specified in its description in the calling program is automatically visible to and updatable by a subprogram nested with the calling program. See Independent vs Contained vs Nested Subprograms, for more information on subprogram nesting. - A data item defined with the
EXTERNAL
(see EXTERNAL) attribute in a subprogram and the calling program (same name in both programs) is automatically visible to and updatable by both programs, even if those programs are compiled separately from one another.
- The subprogram may modify any argument that is specified as
7.4. PROCEDURE DIVISION Sections and Paragraphs
The procedure division is the only one of the COBOL divisions that allows you to create your own sections and paragraphs. These are collectively referred to as Procedures, and the names you create for those sections and paragraphs are called Procedure Names.
Procedure names are optional in the procedure division and — when used — are named entirely according to the needs and whims of the programmer.
Procedure names may be up to thirty one (31) characters long and may consist of letters, numbers, dashes and underscores. A procedure name may neither begin nor end with a dash (‘-’) or underscore (‘_’) character. This means that Main
, 0100-Read-Transaction
and 17
are all perfectly valid procedure names.
There are three circumstances under which the use of certain GnuCOBOL statements or options will require the specification of procedures. These situations are:
- When
DECLARATIVES
(see DECLARATIVES) are specified. - When the
ENTRY
statement (see ENTRY) is being used. - When any procedure division statement that references procedures is used. These statements are:
-
ALTER procedure-name
-
GO TO procedure-name
-
MERGE … OUTPUT PROCEDURE procedure-name
-
PERFORM procedure-name
-
SORT … INPUT PROCEDURE procedure-name
and/orSORT … INPUT PROCEDURE procedure-name
-
7.5. DECLARATIVES
DECLARATIVES Syntax
section-name-1 SECTION. USE { [ GLOBAL ] AFTER STANDARD { EXCEPTION } PROCEDURE ON { INPUT } } ~~~ { ~~~~~~ { ~~~~~~~~~ } { ~~~~~ } } { { ERROR } { OUTPUT } } { ~~~~~ { ~~~~~~ } } { { I-O } } { FOR DEBUGGING ON { procedure-name-1 } { ~~~ } } { ~~~~~~~~~ { ALL PROCEDURES } { EXTEND } } { { ~~~ ~~~~~~~~~~ } { ~~~~~~ } } { { REFERENCES OF identifier-1 } { file-name-1 } } { } { [ GLOBAL ] BEFORE REPORTING identifier-2 } { ~~~~~~ ~~~~~~ ~~~~~~~~~ } { } { AFTER EC|{EXCEPTION CONDITION} } ~~ ~~~~~~~~~ ~~~~~~~~~
The AFTER EXCEPTION CONDITION
and AFTER EC
clauses are syntactically recognized but are otherwise non-functional.
The DECLARATIVES
area of the procedure division allows the programmer to define a series of “trap” procedures (referred to as declarative procedures) capable of intercepting certain events that may occur at program execution time. The syntax diagram above shows the format of a single such procedure.
- The reserved words
AFTER
,FOR
,ON
,PROCEDURE
andSTANDARD
are optional and may be omitted. The presence or absence of these words has no effect upon the program. -
EC
andEXCEPTION CONDITION
are interchangeable. - The declaratives area may contain any number of declarative procedures, but no two declarative procedures should be coded to trap the same event.
- The following points apply to the
USE BEFORE REPORTING
clause:- identifier-2 must be a report group.
- At run-time, the declaratives procedure will be executed prior to the processing of the specified report group’s presentation; within the procedure you may take either of the following actions:
- You may adjust the value(s) of any items referenced in
SUM
(see SUM) orSOURCE
(see SOURCE) clauses in the report group. - You may execute the
SUPPRESS
(see SUPPRESS) statement to squelch the presentation of the specified report group altogether. Note that you will be suppressing this one specific instance of that group’s presentation and not all of them.
- You may adjust the value(s) of any items referenced in
- The following points apply to the
USE FOR DEBUGGING
clause:- This clause allows you to define a declarative procedure that will be invoked whenever…
- …identifier-1 is referenced on any statement.
- …procedure-name-1 is executed.
- …any procedure is executed (
ALL PROCEDURES
).
- A
USE FOR DEBUGGING
declarative procedure will be ignored at compilation time unlessWITH DEBUGGING MODE
is specified in theSOURCE-COMPUTER
(see SOURCE-COMPUTER) paragraph. Neither the compiler’s -fdebugging-line switch nor -debug switch will activate this feature. - Any
USE FOR DEBUGGING
declarative procedures will be ignored at execution time unless theCOB_SET_DEBUG
run-time environment variable (see Run Time Environment Variables) has been set to a value of ‘Y’, ‘y’ or ‘1’. - The typical use of a
USE FOR DEBUGGING
declarative procedure is to display theDEBUG-ITEM
special register, which will be implicitly and automatically created in your program for you ifWITH DEBUGGING MODE
is active.The structure of
DEBUG-ITEM
will be as follows:01 DEBUG-ITEM. 05 DEBUG-LINE PIC X(6). 05 FILLER PIC X(1) VALUE SPACE. 05 DEBUG-NAME PIC X(31). 05 FILLER PIC X(1) VALUE SPACE. 05 DEBUG-SUB-1 PIC S9(4) SIGN LEADING SEPARATE. 05 FILLER PIC X(1) VALUE SPACE. 05 DEBUG-SUB-2 PIC S9(4) SIGN LEADING SEPARATE. 05 FILLER PIC X(1) VALUE SPACE. 05 DEBUG-SUB-3 PIC S9(4) SIGN LEADING SEPARATE. 05 FILLER PIC X(1) VALUE SPACE. 05 DEBUG-CONTENTS PIC X(31).
where…
DEBUG-LINE
-
… is the program line number of the statement that triggered the declaratives procedure.
DEBUG-NAME
-
… is the procedure name or identifier name that triggered the declaratives procedure.
DEBUG-SUB-1
-
… is the first subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.
DEBUG-SUB-2
-
… is the second subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.
DEBUG-SUB-3
-
… is the third subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.
DEBUG-CONTENTS
… is a (brief) statement of the manner in which the procedure that triggered the declaratives procedure was executed or the first 31 characters of the value of the identifier whose reference triggered the declaratives procedure (the value after the statement was executed).
- This clause allows you to define a declarative procedure that will be invoked whenever…
- The
USE AFTER STANDARD ERROR PROCEDURE
clause defines a declarative procedure invoked any time a failure is encountered with the specified I/O type (or against the specified file(s)). - The
GLOBAL
(see GLOBAL) option, if used, allows a declarative procedure to be used across the program containing theUSE
statement and any subprograms nested within that program. - Declarative procedures may not reference any other procedures defined outside the scope of DECLARATIVES.
7.6. Common Clauses on Executable Statements
7.6.1. AT END + NOT AT END
AT END Syntax
[ AT END imperative-statement-1 ] ~~~ [ NOT AT END imperative-statement-2 ] ~~~ ~~~
AT END
clauses may be specified on READ
(see READ), RETURN
(see RETURN), SEARCH
(see SEARCH) and SEARCH ALL
(see SEARCH ALL) statements.
- The following points pertain to the use of these clauses on
READ
(see READ) andRETURN
(see RETURN) statements:- The
AT END
clause will — if present — cause imperative-statement-1 (see Imperative Statement) to be executed if the statement fails due to a file status of 10 (end-of-file). See File Status Codes, for a list of possible File Status codes.An
AT END
clause will not detect other non-zero file-status values.Use a
DECLARATIVES
(see DECLARATIVES) routine or an explicitly-declared file status field tested after theREAD
orRETURN
to detect error conditions other than end-of-file. - A
NOT AT END
clause will cause imperative-statement-2 to be executed if theREAD
orRETURN
attempt is successful.
- The
- The following points pertain to the use of these clauses on
SEARCH
(see SEARCH) andSEARCH ALL
(see SEARCH ALL) statements:- An
AT END
clause detects and handles the case where either form of table search has failed to locate an entry that satisfies the search conditions being used. - The
NOT AT END
clause is not allowed on either form of table search.
- An
7.6.2. CORRESPONDING
Three GnuCOBOL statements — ADD
(see ADD CORRESPONDING), MOVE
(see MOVE CORRESPONDING) and SUBTRACT
(see SUBTRACT CORRESPONDING) support the use of a CORRESPONDING
option:
ADD CORRESPONDING group-item-1 TO group-item-2 MOVE CORRESPONDING group-item-1 TO group-item-2 SUBTRACT CORRESPONDING group-item-1 FROM group-item-2
This option allows one or more data items within one group item (group-item-1 — the first named on the statement) to be paired with correspondingly-named (hence the name) in a second group item (group-item-2 — the second named on the statement). The contents of group-item-1 will remain unaffected by the statement while one or more data items within group-item-2 will be changed.
In order for data-item-1, defined subordinate to group item group-item-1 to be a corresponding match to data-item-2 which is subordinate to group-item-2, each of the following must be true:
- Both data-item-1 and data-item-2 must have the same name, and that name may not explicitly or implicitly be
FILLER
. - Both data-item-1 and data-item-2…
- …must exist at the same relative structural “depth” of definition within group-item-1 and group-item-2, respectively
- …and all “parent” data items defined within each group item must have identical (but non-
FILLER
) names.
- When used with a
MOVE
verb…- …one of data-item-1 or data-item-2 (but not both) is allowed to be a group item
- …and it must be valid to move data-item-1 TO data-item-2.
- When used with
ADD
orSUBTRACT
verbs, both data-item-1 and data-item-2 must be numeric, elementary, unedited items. - Neither data-item-1 nor data-item-2 may be a
REDEFINES
(see REDEFINES) orRENAMES
(see RENAMES) of another data item. - Neither data-item-1 nor data-item-2 may have an
OCCURS
(see OCCURS) clause, although either may contain subordinate data items that do have anOCCURS
clause (assuming rule 3a applies)
Observe the definitions of data items ‘Q’ and ‘Y’…
01 Q. 01 Y. 03 X. 02 A PIC X(1). 05 A PIC 9(1). 02 G1. 05 G1. 03 G2. 10 G2. 04 B PIC X(1). 15 B PIC X(1). 02 C PIC X(1). 05 C. 02 G3. 10 FILLER PIC X(1). 03 G5. 05 G3. 04 D PIC X(1). 10 G4. 03 G6 PIC X(1). 15 D PIC X(1). 02 E PIC 9(1). 05 E PIC X(1). 02 F PIC X(1). 05 F REDEFINES V1 02 G PIC X(4). PIC X(1). 02 H OCCURS 4 TIMES 05 G. PIC X(1). 10 G6 OCCURS 4 TIMES 66 I RENAMES E. PIC X(1). 02 J. 05 H PIC X(4). 03 K. 05 I PIC 9(1). 04 L. 05 J. 05 M. 10 K. 15 M PIC X(1).
The following are the valid CORRESPONDING
matches, assuming the statement MOVE CORRESPONDING X TO Y
is being executed (there are no valid corresponding matches for ADD CORRESPONDING
or SUBTRACT CORRESPONDING
because every potential match up violates rule #4):
The following are the CORRESPONDING
match ups that passed rule #1 (but failed on another rule), and the reasons why they failed.
Data Item | Failure Reason |
---|---|
D |
Fails due to rule #2b |
E |
Fails due to rule #3b |
F |
Fails due to rule #5 |
G1 |
Fails due to rule #3a |
G2 |
Fails due to rule #3a |
G3 |
Fails due to rule #3a |
G4 |
Fails due to rule #1 |
G5 |
Fails due to rule #1 |
G6 |
Fails due to rule #6 |
H |
Fails due to rule #6 |
I |
Fails due to rule #5 |
J |
Fails due to rule #3a |
K |
Fails due to rule #3a |
L |
Fails due to rule #1 |
M |
Fails due to rule #2a |
7.6.3. INVALID KEY + NOT INVALID KEY
INVALID KEY Syntax
[ INVALID KEY imperative-statement-1 ] ~~~~~~~ [ NOT INVALID KEY imperative-statement-2 ] ~~~ ~~~~~~~
INVALID KEY
clauses may be specified on DELETE
(see DELETE), READ
(see Random READ), REWRITE
(see REWRITE), START
(see START) and WRITE
(see WRITE) statements.
Specification of an INVALID KEY
clause will allow your program to trap an I/O failure condition (with an I/O error code in the file’s FILE-STATUS
(see SELECT) field) that has occurred due to a record-not-found condition and handle it gracefully by executing imperative-statement-1 (see Imperative Statement).
An optional NOT INVALID KEY
clause will cause imperative-statement-2 to be executed if the statement’s execution was successful.
7.6.4. ON EXCEPTION + NOT ON EXCEPTION
ON EXCEPTION Syntax
[ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~
EXCEPTION
clauses may be specified on ACCEPT
(see ACCEPT), CALL
(see CALL) and DISPLAY
(see DISPLAY) statements.
Specification of an exception clause will allow your program to trap a failure condition that has occurred and handle it gracefully by executing imperative-statement-1 (see Imperative Statement). If such a condition occurs at runtime without having one of these clauses specified, an error message will be generated (by the GnuCOBOL runtime library) to the SYSERR
device (pipe 2). The program may also be terminated, depending upon the type and severity of the error.
An optional NOT ON EXCEPTION
clause will cause imperative-statement-2 to be executed if the statement’s execution was successful.
7.6.5. ON OVERFLOW + NOT ON OVERFLOW
ON OVERFLOW Syntax
[ ON OVERFLOW imperative-statement-1 ] ~~~~~~~~ [ NOT ON OVERFLOW imperative-statement-2 ] ~~~ ~~~~~~~~
OVERFLOW
clauses may be specified on CALL
(see CALL), STRING
(see STRING) and UNSTRING
(see UNSTRING) statements.
An ON OVERFLOW
clause will allow your program to trap a failure condition that has occurred and handle it gracefully by executing imperative-statement-1 (see Imperative Statement). If such a condition occurs at runtime without having one of these clauses specified, an error message will be generated (by the GnuCOBOL runtime library) to the SYSERR
device (pipe 2). The program may also be terminated, depending upon the type and severity of the error.
An optional NOT ON OVERFLOW
clause will cause imperative-statement-2 to be executed if the statement’s execution was successful.
7.6.6. ON SIZE ERROR + NOT ON SIZE ERROR
ON SIZE ERROR Syntax
[ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~
SIZE ERROR
clauses may be included on ADD
(see ADD), COMPUTE
(see COMPUTE), DIVIDE
(see DIVIDE), MULTIPLY
(see MULTIPLY) and SUBTRACT
(see SUBTRACT) statements.
Including an ON SIZE ERROR
clause on an arithmetic statement will allow your program to trap a failure of an arithmetic statement (either generating a result too large for the receiving field, or attempting to divide by zero) and handle it gracefully by executing imperative-statement-1 (see Imperative Statement). Field size overflow conditions occur silently, usually without any runtime messages being generated, even though such events rarely lend themselves to generating correct results. Division by zero errors, when no ON SIZE ERROR
clause exists, will produce an error message (by the GnuCOBOL runtime library) to the SYSERR
device (pipe 2) and will also abort the program.
An optional NOT ON SIZE ERROR
clause will cause imperative-statement-2 to be executed if the arithmetic statement’s execution was successful.
7.6.7. ROUNDED
ROUNDED Syntax
ROUNDED [ MODE IS { AWAY-FROM-ZERO } ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~
GnuCOBOL provides for control over the final rounding process applied to the receiving fields on all arithmetic verbs. Each of the arithmetic statements (ADD
(see ADD), COMPUTE
(see COMPUTE), DIVIDE
(see DIVIDE), MULTIPLY
(see MULTIPLY) and SUBTRACT
(see SUBTRACT)) statements allow an optional ROUNDED
clause to be applied to each receiving data item.
The following rules apply to the rounding behaviour induced by this clause.
- Rounding only applies when the result being saved to a receiving field with a
ROUNDED
clause is a non-integer value. - Absence of a
ROUNDED
clause is the same as specifyingROUNDED MODE IS TRUNCATION
. - Use of a
ROUNDED
clause without aMODE
specification is the same as specifyingROUNDED MODE IS NEAREST-AWAY-FROM-ZERO
.
The behaviour of the eight different rounding modes is defined in the following table. Note that a ‘…’ indicates the last digit repeats. The examples assume an integer receiving field.
AWAY-FROM-ZERO
-
Rounding is to the nearest value of larger magnitude.
-3.510 ⇒ -4 +3.510 ⇒ +4 -3.500 ⇒ -4 +3.500 ⇒ +4 -3.499… ⇒ -4 +3.499… ⇒ +4 -2.500 ⇒ -3 +2.500 ⇒ +3 -2.499… ⇒ -3 +2.499… ⇒ +3 NEAREST-AWAY-FROM-ZERO
-
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value with the larger absolute value is selected.
-3.510 ⇒ -4 +3.510 ⇒ +4 -3.500 ⇒ -4 +3.500 ⇒ +4 -3.499… ⇒ -3 +3.499… ⇒ +3 -2.500 ⇒ -3 +2.500 ⇒ +3 -2.499… ⇒ -2 +2.499… ⇒ +2 NEAREST-EVEN
-
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value whose rightmost digit is even is selected. This mode is sometimes called “Banker’s rounding”.
-3.510 ⇒ -4 +3.510 ⇒ +4 -3.500 ⇒ -4 +3.500 ⇒ +4 -3.499… ⇒ -3 +3.499… ⇒ +3 -2.500 ⇒ -2 +2.500 ⇒ +2 -2.499… ⇒ -2 +2.499… ⇒ +2 NEAREST-TOWARD-ZERO
-
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value with the smaller absolute value is selected.
-3.510 ⇒ -4 +3.510 ⇒ +4 -3.500 ⇒ -3 +3.500 ⇒ +3 -3.499… ⇒ -3 +3.499… ⇒ +3 -2.500 ⇒ -2 +2.500 ⇒ +2 -2.499… ⇒ -2 +2.499… ⇒ +2 PROHIBITED
-
No rounding is performed. If the value cannot be represented exactly in the desired format, the
EC-SIZE-TRUNCATION
condition (exception code 1005) is set (and may be retrieved via theACCEPT
(see ACCEPT FROM Runtime-Info) statement) and the results of the operation are undefined.-3.510 ⇒ Undefined +3.510 ⇒ Undefined -3.500 ⇒ Undefined +3.500 ⇒ Undefined -3.499… ⇒ Undefined +3.499… ⇒ Undefined -2.500 ⇒ Undefined +2.500 ⇒ Undefined -2.499… ⇒ Undefined +2.499… ⇒ Undefined TOWARD-GREATER
-
Rounding is toward the nearest value whose algebraic value is larger.
-3.510 ⇒ -3 +3.510 ⇒ +4 -3.500 ⇒ -3 +3.500 ⇒ +4 -3.499… ⇒ -3 +3.499… ⇒ +4 -2.500 ⇒ -2 +2.500 ⇒ +3 -2.499… ⇒ -2 +2.499… ⇒ +3 TOWARD-LESSER
-
Rounding is toward the nearest value whose algebraic value is smaller.
-3.510 ⇒ -4 +3.510 ⇒ +3 -3.500 ⇒ -4 +3.500 ⇒ +3 -3.499… ⇒ -4 +3.499… ⇒ +3 -2.500 ⇒ -3 +2.500 ⇒ +2 -2.499… ⇒ -3 +2.499… ⇒ +2 TRUNCATION
-
Rounding is to the nearest value whose magnitude is smaller.
-3.510 ⇒ -3 +3.510 ⇒ +3 -3.500 ⇒ -3 +3.500 ⇒ +3 -3.499… ⇒ -3 +3.499… ⇒ +3 -2.500 ⇒ -2 +2.500 ⇒ +2 -2.499… ⇒ -2 +2.499… ⇒ +2
7.7. Special Registers
GnuCOBOL, like other COBOL dialects, includes a number of data items that are automatically available to a programmer without the need to actually define them in the data division. COBOL refers to such items as registers or special registers. The special registers available to a GnuCOBOL program are as follows:
COB-CRT-STATUS
-
PIC 9(4) — This is the default data item allocated for use by the
ACCEPT screen-data-item
statement (see ACCEPT screen-data-item), if noCRT STATUS
(see SPECIAL-NAMES) clause was specified.. DEBUG-ITEM
-
Group Item — A group item in which debugging information generated by a
USE FOR DEBUGGING
section in the declaratives area of the procedure division will place information documenting why theUSE FOR DEBUGGING
procedure was invoked. Consult theDECLARATIVES
(see DECLARATIVES) documentation for information on the structure of this register. LINAGE-COUNTER
-
BINARY-LONG SIGNED
— An occurrence of this register exists for each selected file having aLINAGE
(see File/Sort-Description) clause. If there are multiple files whose file descriptions haveLINAGE
clauses, any explicit references to this register will require qualification (usingOF file-name
). The value of this register will be the current logical line number within the page body. The value of this register cannot be modified. LINE-COUNTER
-
BINARY-LONG SIGNED
— An occurrence of this register exists for each report defined in the program (via anRD
(see REPORT SECTION)). If there are multiple reports, any explicit references to this register not made in the report section will require qualification (OF report-name
). The value of this register will be the current logical line number on the current page. The value of this register cannot be modified. NUMBER-OF-CALL-PARAMETERS
-
BINARY-LONG SIGNED
— This register contains the number of arguments passed to a subroutine — the same value that would be returned by theC$NARG
built-in system subroutine (see C$NARG). Its value will be zero when referenced in a main program. This register, when referenced from within a user-defined function, returns a value of one (‘1’) if the function has any number of arguments and a zero if it has no arguments. PAGE-COUNTER
-
BINARY-LONG SIGNED
— An occurrence of this register exists for each report having anRD
(see REPORT SECTION). If there are multiple such reports, any explicit references to this register not made in the report section will require qualification (OF report-name
). The value of this register will be the current report page number. The value of this register cannot be modified. RETURN-CODE
-
BINARY-LONG SIGNED
— This register provides a numeric data item into which a subroutine mayMOVE
(see MOVE) a value (which will then be available to the calling program) prior to transferring control back to the program that called it, or into which a main program mayMOVE
a value before returning control to the operating system. Many built-in subroutines will return a value using this register. These values are — by convention — used to signify success (usually with a value of 0) or failure (usually with a non-zero value) of the process the program was attempting to perform. This register may also be modified by a subprogram as a result of that subprogram’s use of theRETURNING
(see PROCEDURE DIVISION RETURNING) clause. SORT-RETURN
-
BINARY-LONG SIGNED
— This register is used to report the success/fail status of aRELEASE
(see RELEASE) orRETURN
(see RETURN) statement. A value of 0 is reported on success. A value of 16 denotes failure. AnAT END
(see AT END + NOT AT END) condition on aRETURN
is not considered a failure. WHEN-COMPILED
PIC X(16)
— This register contains the date and time the program was compiled in the format ‘mm/dd/yyhh.mm.ss’. Note that only a two-digit year is provided.
LENGTH OF Syntax
LENGTH OF numeric-literal-1 | identifier-1 ~~~~~~
Alphanumeric literals and identifiers may optionally be prefixed with the LENGTH OF
clause. The compile-time value generated by this clause will be the number of bytes in the alphanumeric literal or the defined size (in bytes) of the identifier.
- The reserved word
OF
is optional and may be omitted. The presence or absence of this word has no effect upon the program. Here is an example. The following two GnuCOBOL statements both display the same result (27):01 Demo-Identifier PIC X(27). ... DISPLAY LENGTH OF "This is a LENGTH OF Example" DISPLAY LENGTH OF Demo-Identifier
- The
LENGTH OF
clause on a literal or identifier reference may generally be used anywhere a numeric literal might be specified, with the following exceptions:
7.8. GnuCOBOL Statements
7.8.1. ACCEPT
7.8.1.1. ACCEPT FROM CONSOLE
ACCEPT FROM CONSOLE Syntax
ACCEPT { identifier-1 } [ FROM mnemonic-name-1 ] ~~~~~~ ~~~~ { OMITTED } ~~~~~~~ [ END-ACCEPT ] ~~~~~~~~~~
This format of the ACCEPT
statement is used to read a value from the console window or the standard input device and store it into a data item (identifier-1).
- If no
FROM
clause is specified,FROM CONSOLE
is assumed. - The specified mnemonic-name-1 must either be one of the built-in device names
CONSOLE
,STDIN
,SYSIN
orSYSIPT
, or a user-defined (see SPECIAL-NAMES) mnemonic name attached to one of those four device names. - Input will be read either from the console window (
CONSOLE
) or from the system-standard input (pipe 0 =STDIN
,SYSIN
orSYSIPT
) and will be saved in identifier-1. - If identifier-1 is a numeric data item, the character value read from the console or standard-input device will be parsed according to the rules for input to the
NUMVAL
intrinsic function (see NUMVAL), except that none of the trailing sign formats are honoured.
7.8.1.2. ACCEPT FROM COMMAND-LINE
ACCEPT FROM COMMAND-LINE Syntax
ACCEPT identifier-1 ~~~~~~ FROM { COMMAND-LINE } ~~~~ { ~~~~~~~~~~~~ } { ARGUMENT-NUMBER } { ~~~~~~~~~~~~~~~ } { ARGUMENT-VALUE } { ~~~~~~~~~~~~~~ } { [ ON EXCEPTION imperative-statement-1 ] } { ~~~~~~~~~ } { [ NOT ON EXCEPTION imperative-statement-2 ] } [ END-ACCEPT ] ~~~ ~~~~~~~~~ ~~~~~~~~~~
This format of the ACCEPT
statement is used to retrieve information from the program’s command line.
- The reserved word
ON
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - When you accept from the
COMMAND-LINE
option, you will retrieve the entire set of arguments entered on the command line that executed the program, exactly as they were specified. Parsing that returned data into its meaningful information will be your responsibility. - Using
COMMAND-LINE
orARGUMENT-VALUE
in a *nix based platform and that includes Linux, OSX, BSD and under windows running msys or MinGW etc, the shell process will expand any arguments that have a ‘*’ in the list — such as ‘a*’, ‘abc*.*’, etc. — and create a list of all files that match the pattern. To avoid this if not wanted, put all such argument within quotes, e.g.,progundertest "a*" b c d "ef*" "*hg"
and the text within quotes will be passed verbatim to the program (as in the exampleprogundertest
). - By accepting from
ARGUMENT-NUMBER
, you will be asking the GnuCOBOL run-time system to parse the arguments from the command line and return the number of arguments found. Parsing will be conducted according to the following rules:- Arguments will be separated by treating spaces and/or tab characters as the delimiters between arguments. The number of such delimiters separating two non-blank argument values is irrelevant.
- Strings enclosed in double-quote characters (‘"’) will be treated as a single argument, regardless of how many spaces or tab characters (if any) might be embedded within the quotation characters.
- On Windows systems, single-quote, or apostrophe, characters (‘'’) will be treated just like any other data character and will not delineate argument strings.
- By accepting from
ARGUMENT-VALUE
, you will be asking the GnuCOBOL run-time system to parse the arguments from the command line and return the “current” argument. You specify which argument number is “current” via theARGUMENT-NUMBER
option on theDISPLAY
statement (see DISPLAY UPON COMMAND-LINE). Parsing of arguments will be conducted according to the rules set forth above. - The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to the failure or success, respectively, of an attempt to retrieve anARGUMENT-VALUE
. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.
7.8.1.3. ACCEPT FROM ENVIRONMENT
ACCEPT FROM ENVIRONMENT Syntax
ACCEPT identifier-1 ~~~~~~ FROM { ENVIRONMENT-VALUE } ~~~~ { ~~~~~~~~~~~~~~~~~ } { ENVIRONMENT { literal-1 } } { ~~~~~~~~~~~ { identifier-1 } } [ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~ [ END-ACCEPT ] ~~~~~~~~~~
This format of the ACCEPT
statement is used to retrieve environment variable values.
- The reserved word
ON
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - By accepting from
ENVIRONMENT-VALUE
, you will be asking the GnuCOBOL run-time system to retrieve the value of the environment variable whose name is currently in theENVIRONMENT-NAME
register. A value may be placed into theENVIRONMENT-NAME
register using theENVIRONMENT-NAME
option of theDISPLAY
statement (see DISPLAY UPON ENVIRONMENT-NAME). - A simpler approach to retrieving an environment variables value is to use the
ENVIRONMENT
option, where you specify the environment variable whose value is to be retrieved right on theACCEPT
statement itself. - The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to an attempt to retrieve the value of a non-existent environment variable or the successful retrieval of an environment variable’s value, respectively. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.
7.8.1.4. ACCEPT screen-data-item
ACCEPT screen-data-item Syntax
ACCEPT { identifier-1 } ~~~~~~ { OMITTED } ~~~~~~~ [{ FROM EXCEPTION-STATUS }] ~~~~ ~~~~~~~~~~~~~~~~ [{ FROM CRT ] [ MODE IS BLOCK ]} ~~~~ ~~~ ~~~~ ~~~~~ [ AT { | LINE NUMBER { integer-1 } | } ] ~~ { | ~~~~ { identifier-2 } | } { | COLUMN|COL|POSITION|POS NUMBER { integer-2 } { | ~~~~~~ ~~~ ~~~~~~~~ ~~~ { identifier-3 } { } { { integer-3 } } { { identifier-4 } } [ WITH [ Attribute-Specification ]... ~~~~ [ LOWER|UPPER ] ~~~~~ ~~~~~ [ SCROLL { UP } [ { integer-4 } LINE|LINES ] ] ~~~~~~ { ~~ } { identifier-5 } { DOWN } ~~~~ [ TIMEOUT|TIME-OUT AFTER { integer-5 } ] ~~~~~~~ ~~~~~~~~ { identifier-6 } [ CONVERSION ] ~~~~~~~~~~ [ UPDATE ] ~~~~~~ [ SIZE { integer-6 } ] ~~~~ { identifier-7 } [ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~ [ END-ACCEPT ] ~~~~~~~~~~
The FROM CRT
, MODE IS BLOCK
and CONVERSION
clauses are syntactically recognized but are otherwise non-functional.
This format of the ACCEPT
statement is used to retrieve data from a formatted console window screen.
- The reserved words
AFTER
,IS
,NUMBER
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
COLUMN
,COL
andPOSITION
are interchangeable. - The reserved words
TIMEOUT
andTIME-OUT
are interchangeable. - If identifier-1 is defined in the
SCREEN SECTION
(see SCREEN SECTION), anyAT
, Attribute-Specification,LOWER
,UPPER
orSCROLL
clauses will be ignored. In these cases, an impliedDISPLAY
(see DISPLAY screen-data-item) of identifier-1 will occur before input is accepted. Coding an explicitDISPLAY identifier-1
before anACCEPT identifier-1
is redundant and will incur the performance penalty of painting the screen contents twice. - The various
AT
clauses provide a means of positioning the cursor to a specific spot on the screen before the screen is read. One or the other (but not both) may be used, as follows:- The
LINE
andCOLUMN
clauses provide one mechanism for specifying the line and column position to which the cursor will be positioned before allowing the user to enter data. In the absence of one or the other, a value of 1 will be assumed for the one that is missing. The author’s personal preference, however, is to explicitly code both. - The literal-3 or identifier-4 value, if specified, must be a four- or six-digit value with the 1st half of the number indicating the line where the cursor should be positioned and the second half indicating the column. You may code only one of each clause on any
ACCEPT
.
- The
-
WITH
options (including the various individual Attribute-Specifications) should be coded only once. - The following Attribute-Specification clauses are allowed on the
ACCEPT
statement; these are the same as those allowed forSCREEN SECTION
data items. A particular Attribute-Specification may be used only once in anyACCEPT
:-
AUTO
(see AUTO),AUTO-SKIP
(see AUTO-SKIP),AUTOTERMINATE
(see AUTOTERMINATE),TAB
-
BACKGROUND-COLOR
(see BACKGROUND-COLOR) -
BEEP
(see BEEP),BELL
(see BELL) -
BLINK
(see BLINK) -
FOREGROUND-COLOR
(see FOREGROUND-COLOR) -
FULL
(see FULL),LENGTH-CHECK
(see LENGTH-CHECK) -
HIGHLIGHT
(see HIGHLIGHT) -
LEFTLINE
(see LEFTLINE) -
LOWLIGHT
(see LOWLIGHT) -
OVERLINE
(see OVERLINE) -
PROMPT
(see PROMPT) -
PROTECTED
(see PROTECTED) -
REQUIRED
(see REQUIRED),EMPTY-CHECK
(see EMPTY-CHECK) -
REVERSE-VIDEO
(see REVERSE-VIDEO) -
SECURE
(see SECURE),NO-ECHO
(see NO-ECHO) -
UNDERLINE
(see UNDERLINE)
-
- The
SCROLL
option will cause the entire contents of the screen to be scrolledUP
orDOWN
by the specified number of lines before any value is displayed on the screen. It is syntactically allowable to specify aSCROLL UP
clause as well as aSCROLL DOWN
clause. In such an instance, it is the last one specified that will be honoured. If noLINES
specification is made,1 LINE
will be assumed. - The
TIMEOUT
option will cause theACCEPT
to wait no more than the specified number of seconds for input. The wait count may be specified as a positive integer or a numeric data item with a positive value. - The
UPDATE
option will enable the supplied data field to be updated having been displayed on screen prior to data being entered by overwriting, if needed. When this option is not used the input field is cleared prior to input and this is the default but can be changed by the use of compiler steering command -faccept-with-update that can be input when starting the compiler or included in the configuration file e.g., default.conf used when selected by default -std=default. For more information see cobc - The GnuCOBOL Compiler option switches) and Compiler Configuration Files. - This format of the
ACCEPT
statement will be terminated by any of the following events:- When the
Enter
key is pressed. - Expiration of the
TIMEOUT
timer — this will be treated as if theEnter
key had been pressed with no data being entered. - When a function key (
Fn
) is pressed. - The pressing of the
PgUp
orPgDn
keys, if theCOB_SCREEN_EXCEPTIONS
run-time environment variable (see Run Time Environment Variables) is set to any non-blank value. - The pressing of the
Esc
key if both theCOB_SCREEN_ESC
run-time environment variable as well asCOB_SCREEN_EXCEPTIONS
run-time environment variable are set to any non-blank value. - The pressing of the
Up-arrow
,Down-Arrow
orPrtSc
(Print Screen) keys. These keys are not detectable on Windows systems, however.
- When the
- The following apply when identifier-1 is defined in the
SCREEN SECTION
:- Alphanumeric data entered into identifier-1 or any screen data item subordinate to it must be consistent with the
PICTURE
(see PICTURE) clause of that item. This will be enforced at runtime by theACCEPT
statement. - If identifier-1 or any screen data item subordinate to it are defined as numeric, entered data must be acceptable as
NUMVAL
intrinsic function (see NUMVAL) input (no decimal points are allowed, however). The value stored into the screen data item will be as if the input were passed to that function. - If identifier-1 or any screen data item subordinate to it are defined as numeric edited, entered data must be acceptable as
NUMVAL-C
intrinsic function (see NUMVAL-C) input (again, no decimal points are allowed). The value stored into the screen data item will be as if the input were passed to that function.
- Alphanumeric data entered into identifier-1 or any screen data item subordinate to it must be consistent with the
- The following apply when identifier-1 is not defined in the
SCREEN SECTION
:- Alphanumeric data entered into identifier-1 should be consistent with the
PICTURE
(see PICTURE) clause of that item, although that will not be enforced by theACCEPT
statement. You may useClass Conditions
(see Class Conditions) after the data is accepted to enforce the data type. - If identifier-1 is defined as numeric, entered data must be acceptable as
NUMVAL
intrinsic function (see NUMVAL) input (no decimal points are allowed, however). The value stored into identifier-1 will be as if the input were passed to that function. - If identifier-1 is defined as numeric edited, entered data must be acceptable as
NUMVAL-C
intrinsic function (see NUMVAL-C) input (again, no decimal points are allowed). The value stored into identifier-1 will be as if the input were passed to that function.
- Alphanumeric data entered into identifier-1 should be consistent with the
- The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to the failure or success, respectively, of the screen I/O attempt. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.After this format of the
ACCEPT
statement is executed, the program’sCRT STATUS
(see SPECIAL-NAMES) identifier will be populated with one of the following:Code Meaning 0000 ENTER
key pressed1001–1064 F1
–F64
, respectively, were pressed2001 PgUp
was pressed2002 PgDn
was pressed2003 Up-Arrow
was pressed2004 Down-Arrow
was pressed2005 Esc
was pressed2006 PrtSc
(Print Screen) was pressed2007 Tab
2008 Back Tab
2009 Key Left
2010 Key Right
2011 Insert
Key on accept omitted2012 Delete
Key on accept omitted2013 Backspace
Key on accept omitted2014 Home
Key on accept omitted2015 End
Key on accept omitted2040- 2095 Exception keys for Mouse Handling 2040 Mouse Move 2041 Left Pressed 2042 Left Released 2043 Left Dbl Click 2044 Mid Pressed 2045 Mid Released 2046 Mid Dbl Click 2047 Right Pressed 2048 Right Released 2049 Right Dbl Click 2050 Shift Move 2051 Shift Left Pressed 2052 Shift Left Released 2053 Shift Left Dbl Click 2054 Shift Mid Pressed 2055 Shift Mid Released 2056- Shift Mid Dbl Click 2057 Shift Right Pressed 2058 Shift Right Released 2059 Shift Right Dbl Click 2060 Ctrl Move 2061 Ctrl Left Pressed 2062 Ctrl Left Released 2063 Ctrl Left Dbl Click 2064 Ctrl Mid Pressed 2065 Ctrl Mid Released 2066 Ctrl Mid Dbl Click 2067 Ctrl Right Pressed 2068 Ctrl Right Released 2069 Ctrl Right Dbl Click 2070 Alt Move 2071 Alt Left Pressed 2072 Alt Left Released 2073- Alt Left Dbl Click 2074 Alt Mid Pressed 2075 Alt Mid Released 2076 Alt Mid Dbl Click 2077 Alt Right Pressed 2078 Alt Right Released 2079 Alt Right Dbl Click 2080 Wheel Up 2081 Wheel Down 2082 Wheel Left 2083 Wheel Right 2084 Shift Wheel Up 2085 Shift Wheel Down 2086 Shift Wheel Left 2087 Shift Wheel Right 2088 Ctrl Wheel Up 2089 Ctrl Wheel Down 2090 Ctrl Wheel Left 2091 Ctrl Wheel Right 2092 Alt Wheel Up 2093 Alt Wheel Down 2094 Alt Wheel Left 2095 Alt Wheel Right Input validation 8000 NO Field 8001 Time Out Other errors 9000 Fatal 9001 Max Field - The actual key pressed to generate a function key (
Fn
) will depend on the type of terminal device you’re using (PC, Macintosh, VT100, etc.) and what type of enhanced display driver was configured with the version of GnuCOBOL you’re using.For example, on a GnuCOBOL build for a Windows PC using MinGW and “PDCurses”,
F1
–F12
are the actual F-keys on the PC keyboard,F13
–F24
are entered by shifting the F-keys,F25
–F36
are entered by holding Ctrl while pressing an F-key andF37
–F48
are entered by holding Alt while pressing an F-key. On the other hand, a GnuCOBOL implementation built for Windows using Cygwin and NCurses treats the PCsF1
–F12
keys as the actualF1
–F12
, while shifted F-keys will enterF11
–F2
0. With Cygwin/NCurses, Ctrl- and Alt-modified F-keys aren’t recognized, nor areShift-F11
orShift-F12
.Mouse Key codes are populated only if mouse management has been enabled. To enable mouse it is first necessary to set
COB_MOUSE_FLAGS
(either externally via terminal command, or internally viaSET ENVIRONMENT
to the applicable ?mouse mask? (specifying which activities you wish the program to detect). Here is an example of setting the mask from a COBOL program:COPY screenio.cpy. 01 mouse-flags PIC 9(4). ... COMPUTE mouse-flags = COB-AUTO-MOUSE-HANDLING + COB-ALLOW-LEFT-DOWN + COB-ALLOW-MIDDLE-DOWN + COB-ALLOW-RIGHT-DOWN SET ENVIRONMENT "COB_MOUSE_FLAGS" TO mouse-flags.
- Once that has been done, every (extended) ACCEPT, will return a value in COB_CRT_STATUS reflecting mouse activity, when such activity occurs. The applicable values are shown in screenio.cpy under ?Exception keys for mouse handling?. If you define a variable in SPECIAL NAMES as follows:
SPECIAL-NAMES. CURSOR IS data-name. *> where data-name is PIC 9(4) or 9(6).
- The cursor or mouse position will be returned as well. The position is expressed as row and column (rrcc or rrrccc).
- Numeric keypad keys are not recognizable on Windows MinGW/PDCurses builds of GnuCOBOL, regardless of the number lock settings. Windows Cygwin/NCurses builds recognize numeric keypad inputs properly. Although not tested during the preparation of this documentation, I would expect native Windows builds using PDCurses to behave as MinGW builds do and native Unix builds using NCurses to behave as do Cygwin builds.
- The optional
EXCEPTION-STATUS
clause may be used to detect exceptions from a prior arithmetic verb such as COMPUTE to recover any errors produced. These are recovered using the functionEXCEPTION-STATUS
.
7.8.1.5. ACCEPT FROM DATE/TIME
ACCEPT FROM DATE/TIME Syntax
ACCEPT identifier-1 FROM { DATE [ YYYYMMDD ] } ~~~~~~ ~~~~ { ~~~~ ~~~~~~~~ } { DAY [ YYYYDDD ] } { ~~~ ~~~~~~~ } { DAY-OF-WEEK } { ~~~~~~~~~~~ } [ END-ACCEPT ] { TIME } ~~~~~~~~~~
This format of the ACCEPT
statement is used to retrieve the current system date, time or current day of the week and store it into a data item.
- The data retrieved from the system and the format in which it is structured will vary, as follows:
Syntax Data Retrieved Format DATE
Current date in Gregorian form yymmdd DATE YYYYMMDD
Current date in Gregorian form yyyymmdd DAY
Current date in Julian form yyddd DAY YYYYDDD
Current date in Julian form yyyyddd TIME
Time, including hundredths of a second (nn) hhmmssnn
7.8.1.6. ACCEPT FROM Screen-Info
ACCEPT FROM Screen-Info Syntax
ACCEPT identifier-1 ~~~~~~ FROM { LINES|LINE-NUMBER } ~~~~ { ~~~~~ ~~~~~~~~~~~ } { COLS|COLUMNS } { ~~~~ ~~~~~~~ } { ESCAPE KEY } ~~~~~~ ~~~ [ END-ACCEPT ] ~~~~~~~~~~
This format of the ACCEPT
statement is used to retrieve information about the console window or about the user’s interactions with it.
- The reserved words
LINES
andLINE-NUMBER
are interchangeable. - The reserved words
COLS
andCOLUMNS
are interchangeable. - The following points pertain to the use of the
LINES
andCOLUMNS
options:- The
LINES
andCOLUMNS
options will retrieve the respective components of the size of the console display. - When the console is running in a windowed environment, this will be the sizing of the window in which the program is executing, in terms of horizontal (
COLUMNS
) or vertical (LINES
) character counts — not pixels. - When the system is not running a windowing environment, the physical console screen attributes will be returned.
- Values of 0 will be returned if GnuCOBOL was not generated to include screen I/O.
- See the documentation on the
CBL_GET_SCR_SIZE
built-in system subroutine (see CBL_GET_SCR_SIZE) for another way to retrieve this information.
- The
- The
ESCAPE KEY
option may be used after theACCEPT FROM Screen-Info
statement (see ACCEPT FROM Screen-Info) has executed. The result returned will be the four-digitCRT STATUS
(see SPECIAL-NAMES) identifier value. See CRT STATUS Codes, for the specific code values.
7.8.1.7. ACCEPT FROM Runtime-Info
ACCEPT FROM Runtime-Info Syntax
ACCEPT identifier-1 ~~~~~~ FROM { EXCEPTION STATUS } ~~~~ { ~~~~~~~~~ ~~~~~~ } { USER NAME } ~~~~ ~~~~ [ END-ACCEPT ] ~~~~~~~~~~
This format of the ACCEPT
statement is used to retrieve run-time information such as the most-recent error exception code and the current user’s user name.
- The following points pertain to the use of the
EXCEPTION STATUS
option:- identifier-1 must be defined as a
PIC X(4)
item. - See Error Exception Codes, for a complete list of the exception codes and their meanings.
- An alternative to the use of
ACCEPT FROM Runtime-Info
is to use theEXCEPTION-STATUS
intrinsic function (see EXCEPTION-STATUS).
- identifier-1 must be defined as a
- The following points pertain to the use of the
USER NAME
option:- The returned result is the userid that was used to login to the system with, and not any actual first and/or last name of the user in question (unless, of course, that is the information used as a logon id). It is not the PID or UID numbers but the name associated with the UID under *nix based systems.
- identifier-1 should be defined large enough to receive the longest user-name on the system.
- If insufficient space is allocated, the returned value will be truncated.
- If excess space is allocated, the returned value will be padded with spaces (to the right).
7.8.1.8. ACCEPT OMITTED
ACCEPT OMITTED Syntax
ACCEPT OMITTED ~~~~~~ 1. For console : See 6.17.1.1 (ACCEPT FROM CONSOLE Syntax) 2. For Screen : See 6.17.1.4 (ACCEPT screen-data-item Syntax) [ END-ACCEPT ] ~~~~~~~~~~
This format of the ACCEPT
statement will wait for a keyboard event that terminates input; function keys, or Enter/Return, among others. CRT STATUS (COB-CRT-STATUS CRT STATUS
(see SPECIAL-NAMES) if not explicitly defined) is set with the keycode, listed in copy/screenio.cpy. It also handles a few other keycode terminations not normally used to complete an extended accept.
- The following are examples of keycodes that can be used:
COB-SCR-INSERT COB-SCR-DELETE COB-SCR-BACKSPACE COB-SCR-KEY-HOME COB-SCR-KEY-END
- You can used extended attributes, useful for setting timeouts or positioning.
7.8.1.9. ACCEPT FROM EXCEPTION-STATUS
ACCEPT FROM EXCEPTION-STATUS Syntax
ACCEPT exception-status-pic-9-4 FROM EXCEPTION-STATUS ~~~~~~ ~~~~ ~~~~~~~~~~~~~~~~ [ END-ACCEPT ] ~~~~~~~~~~
This format of the ACCEPT
statement will receive the status for any exceptions resulting from a previous valid verb.
- The following is an example of usage:
In WS: 01 exception-status pic 9(4). .. In PD: ACCEPT unexpected-rounding FROM EXCEPTION-STATUS IF unexpected-rounding NOT EQUAL "0000" THEN DISPLAY "Unexpected rounding. Code " unexpected-rounding UPON SYSERR END-IF
7.8.2. ADD
7.8.2.1. ADD TO
ADD TO Syntax
ADD { literal-1 }... ~~~ { identifier-1 } TO { identifier-2 ~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-ADD ] ~~~~~~~
This format of the ADD
statement generates an intermediate arithmetic sum of the values of all identifier-1 and literal-1) items. The value of each identifier-2 will be replaced, in turn, by the sum of that identifier-2s value and the intermediate sum.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items while literal-1 must be a numeric literal.
- An identifier-1 data item may also be coded as an identifier-2. Note, however, that the value of such a data item will therefore be included twice in the result.
- The contents of each identifier-1 will remain unchanged by this statement.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.2.2. ADD GIVING
ADD GIVING Syntax
ADD { literal-1 }... ~~~ { identifier-1 } [ TO identifier-2 ] ~~ GIVING { identifier-3 ~~~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-ADD ] ~~~~~~~
This format of the ADD
statement generates the arithmetic sum of the values of all identifier-1, literal-1) and identifier-2 (if any) items and then saves that sum to each identifier-3.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items while literal-1 must be a numeric literal; identifier-3 may be either a numeric or numeric edited data item.
- An identifier-1 or identifier-2 data item may be used as an identifier-3, if desired.
- The contents of each identifier-1 and identifier-2 will remain unchanged by this statement, unless they happen to also be specified as an identifier-3.
- The current value in each identifier-3 at the start of the statement’s execution is irrelevant, since the contents of each identifier-3 will simply be replaced with the computed sum.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-3 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-3 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.2.3. ADD CORRESPONDING
ADD CORRESPONDING Syntax
ADD CORRESPONDING identifier-1 ~~~ TO identifier-2 ~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-ADD ] ~~~~~~~
This format of the ADD
statement generates code equivalent to individual ADD TO
(see ADD TO) statements for corresponding matches of data items found subordinate to the two identifiers.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be group items.
- See CORRESPONDING, for information on how corresponding matches will be found between identifier-1 and identifier-2.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-3 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-3 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.3. ALLOCATE
ALLOCATE Syntax
ALLOCATE { expression-1 CHARACTERS } [ { INITIALIZED } ] ~~~~~~~~ { identifier-1 ~~~~~~~~~~ } { ~~~~~~~~~~~ } { INITIALISED } [ RETURNING identifier-2 ] ~~~~~~~~~~~ ~~~~~~~~~
The ALLOCATE
statement is used to dynamically allocate memory at run-time.
- The reserved words
INITIALIZED
andINITIALISED
are interchangeable. - Both identifier-1 and
RETURNING identifier-2
may not be specified in the same statement. - If used, expression-1 must be an arithmetic expression with a non-zero positive integer value.
- If used, identifier-1 should be an 01-level item defined in working-storage or local-storage with the
BASED
(see BASED) attribute. It may be an 01 item defined in the linkage section without theBASED
attribute, but using such a data item is not recommended. - If used, identifier-2 should be a
POINTER
(see USAGE) data item. - The optional
RETURNING
clause will return the address of the allocated memory block into the specifiedUSAGE POINTER
identifier-2 data item. When this option is used, knowledge of the originally-requested size of the allocated memory block will be retained by the program in case aFREE
(see FREE) statement is ever issued against identifier-2. - When the identifier-1 option is used in conjunction with
INITIALIZED
(or its internationalized alternativeINITIALISED
), the allocated memory block will be initialized as if anINITIALIZE identifier-1 WITH FILLER ALL TO VALUE THEN TO DEFAULT
(see INITIALIZE) were executed. - When the
expression-1 CHARACTERS
option is used,INITIALIZED
will initialize the allocated memory block to binary zeros. IfINITIALIZED
is not used, the initial contents of allocated memory will be left to whatever rules of memory allocation are in effect for the operating system the program is running under. - There are two basic ways in which this statement is used. The simplest is:
ALLOCATE My-01-Item
With this form, a block of storage equal in size to the defined size of My-01-Item (which must have been defined with the
BASED
attribute) will be allocated. The address of that block of storage will become the base address of My-01-Item so that it and its subordinate data items become usable within the program.A second (and equivalent) approach is:
ALLOCATE LENGTH OF My-01-Item CHARACTERS RETURNING The-Pointer SET ADDRESS OF My-01-Item TO The-Pointer
- With this form My-01-Item can either be defined with the
BASED
attribute or be defined in LINKAGE SECTION. Instead of LENGTH OF My-01-Item you may also use a size smaller to the maximum field size as long as you ensure that the complete field is never used. - Referencing a
BASED
data item either before its storage has been allocated or after its storage has been released (via theFREE
statement) will lead to “unpredictable results”. That’s how reference manuals and standards specifications talk about this situation. In the author’s experience, the results are all too predictable: the program aborts from an attempt to reference an unallocated area of memory.
7.8.4. ALTER
ALTER Syntax
ALTER procedure-name-1 TO PROCEED TO procedure-name-2 ~~~~~ ~~
The ALTER
statement was used in the early years of the COBOL language to edit the object code of a program at execution time, changing a GO TO
(see Simple GO TO) statement to branch to a spot in the program different than where the GO TO
statement was originally compiled for.
- The reserved words
PROCEED
andTO
(the one afterPROCEED
) are optional and may be omitted. The presence or absence of these words has no effect upon the program. - procedure-name-1 must contain only a single statement, and that statement must be a simple
GO TO
. - The effect of this statement will be as if the generated machine-language code for the
GO TO
statement in procedure-name-1 is changed so that theGO TO
statement now transfers control to procedure-name-2, rather than to whatever procedure name was specified in the program source code. - Support for the
ALTER
verb has been added to GnuCOBOL for the purpose of enabling GnuCOBOL to pass those National Institute of Standards and Technology (NIST) tests for the COBOL programming language that require support forALTER
. - Because of the catastrophic effect this statement has on program readability and therefore the programmer’s ability to debug problems with program logic, the use of
ALTER
in new programs is STRONGLY discouraged.
7.8.5. CALL
CALL Syntax
CALL [ { STDCALL } ] { literal-1 } ~~~~ { ~~~~~~~ } { identifier-1 } { STATIC } { ~~~~~~ } { mnemonic-name-1 } [ USING CALL-Argument... ] ~~~~~ [ RETURNING|GIVING identifier-2 ] ~~~~~~~~~ ~~~~~~ [ ON OVERFLOW|EXCEPTION imperative-statement-1 ] ~~~~~~~~ ~~~~~~~~~ [ NOT ON OVERFLOW|EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~ ~~~~~~~~~ [ END-CALL ] ~~~~~~~~
CALL Argument Syntax
[ BY { REFERENCE } ] { ~~~~~~~~~ } { CONTENT } { ~~~~~~~ } { VALUE } ~~~~~ { OMITTED } { ~~~~~~~ } { [ UNSIGNED ] [ SIZE IS { AUTO } ] [ { literal-2 } } ~~~~~~~~ ~~~~ { ~~~~ } { identifier-2 } { DEFAULT } { ~~~~~~~ } { integer-1 }
The CALL
statement is used to transfer control to a subroutine. See Sub-Programming, for the specifics of using subprograms with GnuCOBOL programs.
- The reserved words
BY
,IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
EXCEPTION
andOVERFLOW
are interchangeable. - The reserved words
GIVING
andRETURNING
are interchangeable. - The expectation is that the subroutine will eventually return control back to the calling program, at which point the
CALL
ing program will resume execution starting with the statement immediately following theCALL
. Subprograms are not required to return to their callers, however, and are free to halt program execution if they wish. - The mnemonic-name-1 /
STATIC
/STDCALL
option, if used, affects the linkage conventions that will be used to the subroutine being called, as follows:STATIC
-
causes the linkage to the subroutine to be performed in such a way as to require the subroutine to be statically-linked with the calling program. Note that this enables static-linking to be used on a subroutine-by-subroutine selective basis.
STDCALL
-
allows system standard calling conventions (as opposed to GnuCOBOL calling conventions) to be used when calling a subroutine. The definition of what constitutes “system standard” may vary from operating system to operating system. Use of this requires special knowledge about the linkage requirements of subroutines you are intending to
CALL
. Subroutines written in GnuCOBOL do not need this option. - mnemonic-name-1
-
allows a custom defined calling convention to be used. Such mnemonic names are defined using the
CALL-CONVENTION
(see SPECIAL-NAMES) clause. That clause associates a decimal integer value with mnemonic-name-1 such that the individual bits set on or off in the binary equivalent of the integer affect linkage to the subroutine as described in the following chart. Those rows of the chart marked with a “No” in the Supported column represent bit positions (switch settings) in the integer value that are currently accepted (to provide compatibility to other COBOL implementations) if coded, but are otherwise unsupported.Note that bit 0 is the right-most bit in the binary value.
Bit Supported Meaning if 0 Meaning if 1 0 No Arguments will be passed in right-to-left sequence Arguments will be passed in left-to-right sequence. 1 No The calling program will flush processed arguments from the argument stack. The called program (subroutine) will flush processed arguments from the argument stack. 2 Yes The RETURN-CODE
special register (see Special Registers) will be updated in addition to anyRETURNING
orGIVING
data item.The RETURN-CODE
special register will not be updated (but anyRETURNING
orGIVING
data item still will).3 Yes If CALL literal
is used, the subroutine will be located and linked in with the calling program at compile time or may be dynamically located and loaded at execution time, depending on compiler switch settings and operating system capabilities.If CALL literal
is used, the subroutine can only be located and linked with the calling program at compilation time.4 No OS/2 “OPTLINK” conventions will not be used to CALL the subprogram. OS/2 “OPTLINK” conventions will be used to CALL the subprogram. 5 No Windows 16-bit “thunking” will not be in effect. Windows 16-bit “thunking” will be used to call the subroutine as a DLL. 6 Yes The STDCALL
convention will not be used.The STDCALL
convention, required to use the Microsoft Win32 API, will be used.Using the
STATIC
option on aCALL
statement is equivalent to usingCALL-CONVENTION 8
(only bit 3 set).Using the
STDCALL
option on aCALL
statement is equivalent to usingCALL CONVENTION 64
(only bit 6 set).
- The value of literal-1 or identifier-1 is the entry-point of the subprogram you wish to call.
- When you call a subroutine using identifier-1, you are forcing the runtime system to call a dynamically-loadable subprogram. The contents of identifier-1 will be the entry-point name within that module. If this is the first call to any entry-point within the module being made at run-time, the contents of identifier-1 must be the primary entry-point name of the module (which must also match the filename, minus any OS-mandated extension) of the executable file comprising the module).
- You can force the GnuCOBOL runtime system to pre-load all dynamically-loaded modules that could ever be called by the program, at the time the program starts executing. This is accomplished through the use of the
COB_PRE_LOAD
run-time environment variable (see Run Time Environment Variables). If used, this will only pre-load those modules invoked viaCALL literal-1
, as the runtime contents of identifier-1 cannot be predicted. - If the subprogram being called is a GnuCOBOL program, and if that program had the
INITIAL
(see IDENTIFICATION DIVISION) attribute specified on itsPROGRAM-ID
clause, all of the subprogram’s data division data will be restored to its initial state each time the subprogram is executed, regardless of which entry-point within the subprogram is being referenced.This [re]-initialization behaviour will always apply to any subprogram’s local-storage (if any), regardless of the use (or not) of
INITIAL
. - The
USING
clause defines a list of arguments that may be passed from the calling program to the subprogram. The manner in which any given argument is passed to the subroutine depends upon theBY
clause (if any) coded (or implied) for that argument, as follows:BY REFERENCE
-
passes the address of the argument to the subprogram. If the subprogram changes the contents of that argument, the change will be “visible” to the calling program.
BY CONTENT
-
passes the address of a copy of the argument to the subprogram. If the subprogram changes the value of such an argument, the change only affects the copy back in the calling program, not the original version.
BY VALUE
-
passes the actual numeric value of the literal or identifiers contents as the argument. This feature exists to provide compatibility with C, C++ and other languages and would not normally be used when calling GnuCOBOL subprograms. Only numeric literals or numeric data items should be passed in this manner.
If an argument lacks a
BY
clause, the most-recently encounteredBY
specification on thatCALL
statement will be assumed. If the first argument specified on aCALL
lacks aBY
clause,BY REFERENCE
will be assumed. - No more than 251 arguments may be passed to a subroutine, unless the GnuCOBOL compiler was built with a specifically different argument limit specified for it. If you have access to the GnuCOBOL source code, you may adjust this limit by changing the value of the
COB_MAX_FIELD_PARAMS
in the call.c file (found in the libcob folder) as well as the last shown#if MAX_CALL_FIELD_PARAMS
statement before you runmake
to build the compiler and run-time library. - The
RETURNING
clause allows you to specify a numeric data item into which the subroutine should return a numeric value. If you use this clause on theCALL
, the subroutine should include aRETURNING
(see PROCEDURE DIVISION RETURNING) clause on its procedure division header. Of course, a subroutine may pass a value of any kind back in any argument passedBY REFERENCE
. - The optional
ON OVERFLOW
andNOT ON OVERFLOW
clauses (orON EXCEPTION
andNOT ON EXCEPTION
— they are interchangeable) may be used to detect and react to the failure or success, respectively, of an attempt toCALL
the subroutine. Failure, in this context, is defined as the inability to either locate or load the object code of the subroutine at execution time. See ON OVERFLOW + NOT ON OVERFLOW, for additional information. - Call also supports using an entry point stored in a
PROGRAM-POINTER
, avoiding the dynamic runtime lookup. GnuCOBOL keeps a cache of lookups during a program run. Repeated use of a named function does not suffer much penalty, butPROGRAM-POINTER
will be just that little bit faster. To set aPROGRAM-POINTER
useSET program-reference TO ENTRY "name"
(or get the address from an API, and take part in callback programming). - An extension of
CALL
allows a call to a Program-Pointer-1 which is preset usingSET program-pointer-1 TO ENTRY x
. Additional theRETURNING
clause may return a data pointer or aPROGRAM-POINTER
7.8.6. CANCEL
CANCEL Syntax
CANCEL { literal-1 }... ~~~~~~ { identifier-1 }
The CANCEL
statement unloads the dynamically-loadable subprogram module containing the entry-point specified as literal-1 or identifier-1 from memory.
- If a dynamically-loadable module unloaded by the
CANCEL
statement is subsequently re-executed, all data division storage for that module will once again be in its initial state. - Whether the
CANCEL
statement actually physically unloads a dynamically-loaded module or simply marks it as logically-unloaded depends on the use and value of theCOB_PHYSICAL_CANCEL
run-time environment variable (see Run Time Environment Variables).
7.8.7. CLOSE
CLOSE Syntax
CLOSE { file-name-1 [ { REEL|UNIT [ FOR REMOVAL ] } ] }... ~~~~~ { ~~~~ ~~~~ ~~~~~~~ } { WITH LOCK } { ~~~~ } { WITH NO REWIND } ~~ ~~~~~~
The REEL
, LOCK
and NO REWIND
clauses are syntactically recognized but are otherwise non-functional, except for the CLOSE…NO REWIND
statement, which will generate a file status of 07 rather than the usual 00 (but take no other action).
The CLOSE
statement terminates the program’s access to the specified file(s).
- The reserved words
FOR
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
REEL
andUNIT
are interchangeable. - The
CLOSE
statement may only be executed against files that have been successfully opened. - A successful
CLOSE
will write any remaining unwritten record buffers to the file (similar to anUNLOCK
statement (see UNLOCK)) and release any file locks for the file, regardless of open mode. A closed file will then be no longer available for subsequent I/O statements until it is once again OPENED. - When a
ORGANIZATION LINE SEQUENTIAL
(see ORGANIZATION LINE SEQUENTIAL) orLINE ADVANCING
(see LINE ADVANCING) file is closed, a final delimiter sequence will be written to the file to signal the termination point of the final data record in the file. This will only be necessary if the final record written to the file was written with theAFTER ADVANCING
(see WRITE) option.
7.8.8. COMMIT
COMMIT Syntax
COMMIT ~~~~~~
The COMMIT
statement performs an UNLOCK
against every currently-open file, but does not close any of the files. See the UNLOCK
statement (see UNLOCK) for additional details.
7.8.9. COMPUTE
COMPUTE Syntax
COMPUTE { identifier-1 ~~~~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ =|EQUAL arithmetic-expression-1 ~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-COMPUTE ] ~~~~~~~~~~~
The COMPUTE
statement provides a means of easily performing complex arithmetic operations with a single statement, instead of using cumbersome and possibly confusing sequences of ADD
, SUBTRACT
, MULTIPLY
and DIVIDE
statements. COMPUTE
also allows the use of exponentiation — an arithmetic operation for which no other statement exists in COBOL.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved word
EQUAL
is interchangeable with the use of ‘=’. - Each identifier-1 must be a numeric or numeric-edited data item.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-1 will control how non-integer results will be saved. - See Arithmetic Expressions, for more information on arithmetic expressions.
- The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined either as having an identifier-3 with an insufficient number of digit positions available to the left of any implied decimal point or attempting to divide by zero. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.10. CONTINUE
CONTINUE Syntax
CONTINUE ~~~~~~~~ { identifier-1 } CONTINUE AFTER { literal-1 } SECONDS ~~~~~~~~ ~~~~~ { arithmetic-expression-1 } ~~~~~~~
The CONTINUE
statement is a no-operation statement that may be coded anywhere an imperative statement (see Imperative Statement) may be coded.
- The
CONTINUE
statement has no effect on the execution of the program. - This statement (perhaps in combination with an appropriate comment or two) makes a convenient “place holder” — particularly in
ELSE
(see IF) orWHEN
(see EVALUATE) clauses where no code is currently expected to be needed, but a place for code to handle the conditions in question is to be reserved in case it’s ever needed. - The optional extension of (AFTER) when used with the
CONTINUE
statement pauses execution for a specified length of time.
7.8.11. DELETE
DELETE Syntax
DELETE file-name-1 RECORD ~~~~~~ [ INVALID KEY imperative-statement-1 ] ~~~~~~~ [ NOT INVALID KEY imperative-statement-2 ] ~~~ ~~~~~~~ [ END-DELETE ] ~~~~~~~~~~
The DELETE
statement logically deletes a record from a COBOL file.
- The reserved words
KEY
andRECORD
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The
ORGANIZATION
of file-name-1 cannot beORGANIZATION LINE SEQUENTIAL
(see ORGANIZATION LINE SEQUENTIAL). - The file-name-1 file cannot be a sort/merge work file (a file described using a
SD
(see File/Sort-Description)). - For files in the
SEQUENTIAL
access mode, the last input-output statement executed against file-name-1 prior to the execution of theDELETE
statement must have been a successfully executed sequential-formatREAD
statement (see Sequential READ). ThatREAD
will therefore identify the record to be deleted. - If file-name-1 is a
RELATIVE
file whoseACCESS MODE
(see ORGANIZATION RELATIVE) is eitherRANDOM
orDYNAMIC
, the record to be deleted is the one whose relative record number is currently the value of the field specified as the filesRELATIVE KEY
in itsSELECT
statement. - If file-name-1 is an
INDEXED
file whoseACCESS MODE
(see ORGANIZATION INDEXED) isRANDOM
orDYNAMIC
, the record to be deleted is the one whose primary key is currently the value of the field specified as theRECORD KEY
in the file’sSELECT
statement. - The optional
INVALID KEY
andNOT INVALID KEY
clauses may be used to detect and react to the failure or success, respectively, of an attempt to delete a record. See INVALID KEY + NOT INVALID KEY, for additional information. - No
INVALID KEY
orNOT INVALID KEY
clause may be specified for a file who’sACCESS MODE IS SEQUENTIAL
.
7.8.12. DISPLAY
7.8.12.1. DISPLAY UPON device
DISPLAY UPON device Syntax
DISPLAY { literal-1 }... ~~~~~~~ { identifier-1 } [ UPON mnemonic-name-1 ] ~~~~ [ WITH NO ADVANCING ] ~~ ~~~~~~~~~ [ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~ [ END-DISPLAY ] ~~~~~~~~~~~
This format of the DISPLAY
statement displays the specified identifier contents and/or literal values on the system output device specified via the UPON
clause.
- The reserved words
ON
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - If no
UPON
clause is specified,UPON CONSOLE
will be assumed. If theUPON
clause is specified, mnemonic-name-1 must be one of the built-in output device namesCONSOLE
,PRINTER
,STDERR
,STDOUT
,SYSERR
,SYSLIST
,SYSLST
orSYSOUT
or a mnemonic name assigned to one of those devices via theSPECIAL-NAMES
(see SPECIAL-NAMES) paragraph.When displaying upon the
STDERR
orSYSERR
devices or to a mnemonic-name-1 attached to one of those two devices, the output will be written to output pipe #2, which will normally cause the output to appear in the console output window. You may, if desired, redirect that output to a file by appending 2> filename to the end of the command that executes the program. This applies to both Windows (any type) or Unix versions of GnuCOBOL.When displaying upon the
CONSOLE
,PRINTER
,STDOUT
,SYSLIST
,SYSLST
orSYSOUT
devices or to a mnemonic-name-1 attached to one of them, the output will be written to output pipe #1, which will normally cause the output to appear in the console output window. You may, if desired, redirect that output to a file by appending 1> filename or simply > filename to the end of the command that executes the program. This applies to both Windows (any type) or Unix versions of GnuCOBOL. - The
NO ADVANCING
clause, if used, will suppress the carriage-return / line-feed sequence that is normally added to the end of any console display. - The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to the failure or success, respectively, of an attempt to display output to the specified device. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.
7.8.12.2. DISPLAY UPON COMMAND-LINE
DISPLAY UPON COMMAND-LINE Syntax
DISPLAY { literal-1 }... ~~~~~~~ { identifier-1 } UPON { ARGUMENT-NUMBER|COMMAND-LINE } ~~~~ { ~~~~~~~~~~~~~~~ ~~~~~~~~~~~~ } [ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~ [ END-DISPLAY ] ~~~~~~~~~~~
This form of the DISPLAY
statement may be used to specify the command-line argument number to be retrieved by a subsequent ACCEPT FROM ARGUMENT-VALUE
statement (see ACCEPT FROM COMMAND-LINE) or to specify a new value for the command-line arguments themselves.
- The reserved word
ON
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - By displaying a numeric integer value
UPON
ARGUMENT-NUMBER
, you will specify which argument (by its relative number) will be retrieved by a subsequentACCEPT FROM ARGUMENT-VALUE
statement. - Executing a
DISPLAY UPON COMMAND-LINE
will influence subsequentACCEPT FROM COMMAND-LINE
statements (which will then return the value you displayed), but will not influence subsequentACCEPT FROM ARGUMENT-VALUE
statements — these will continue to return the original program execution parameters. - The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to the failure or success, respectively, of an attempt to display output to the specified item. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.
7.8.12.3. DISPLAY UPON ENVIRONMENT-NAME
DISPLAY UPON ENVIRONMENT-NAME Syntax
DISPLAY { literal-1 }... UPON { ENVIRONMENT-VALUE } ~~~~~~~ { identifier-1 } ~~~~ { ~~~~~~~~~~~~~~~~~ } { ENVIRONMENT-NAME } ~~~~~~~~~~~~~~~~ [ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~ [ END-DISPLAY ] ~~~~~~~~~~~
This form of the DISPLAY
statement can be used to create or modify environment variables.
- The reserved word
ON
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - To create or change an environment variable will require two
DISPLAY
statements. The following example sets the environment variableMY_ENV_VAR
to a value of ‘Demonstration Value’:DISPLAY "MY_ENV_VAR" UPON ENVIRONMENT-NAME DISPLAY "Demonstration Value" UPON ENVIRONMENT-VALUE
- Environment variables created or changed from within GnuCOBOL programs will be available to any sub-shell processes spawned by that program (i.e.
CALL 'SYSTEM'
(see SYSTEM)) but will not be known to the shell or console window that started the GnuCOBOL program. - Consider using
SET ENVIRONMENT
(see SET ENVIRONMENT) in lieu ofDISPLAY
to set environment variables as it is much simpler. - The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to the failure or success, respectively, of an attempt to display output to the specified item. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.
7.8.12.4. DISPLAY screen-data-item
DISPLAY screen-data-item Syntax
DISPLAY identifier-1 [ UPON CRT|CRT-UNDER ] ~~~~~~~ ~~~~ ~~~ ~~~~~~~~~ [ AT { | LINE NUMBER { integer-1 } | } ] ~~ { | ~~~~ { identifier-2 } | } { | COLUMN|COL|POSITION|POS NUMBER { integer-2 } { | ~~~~~~ ~~~ ~~~~~~~~ ~~~ { identifier-3 } { } { { integer-3 } } { { identifier-4 } } [ WITH [ Attribute-Specification ]... ~~~~ [ SCROLL { UP } [ { integer-4 } LINE|LINES ] ] ~~~~~~ { ~~ } { identifier-5 } { DOWN } ~~~~ [ SIZE { integer-5 } ~~~~ { identifier-6 } ] [ ON EXCEPTION imperative-statement-1 ] ~~~~~~~~~ [ NOT ON EXCEPTION imperative-statement-2 ] ~~~ ~~~~~~~~~ [ END-DISPLAY ] ~~~~~~~~~~~
The UPON CRT
, UPON CRT-UNDER
and CONVERSION
clauses are syntactically recognized but are otherwise non-functional. They are supported to provide compatibility with COBOL source written for other COBOL implementations.
This format of the DISPLAY
statement presents data onto a formatted screen.
- The reserved words
AFTER
,LINE
,LINES
,NUMBER
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
COLUMN
andPOSITION
are interchangeable. - The reserved words
LINE
andLINES
are interchangeable. - If identifier-1 is defined in the
SCREEN SECTION
(see SCREEN SECTION), anyAT
, Attribute-Specification andWITH
clauses will be ignored. All field definition, cursor positioning and screen control will occur as a result of the screen section definition of identifier-1. - The following points apply if identifier-1 is not defined in the screen section:
- The purpose of the
AT
clause is to define where on the screen identifier-1 should be displayed. See ACCEPT screen-data-item, for additional information. - The purpose of the
WITH
clause is to define the visual attributes that should be applied to identifier-1 when it is displayed on the screen as well as other presentation-control characteristics. - The following Attribute-Specification clauses are allowed on the
DISPLAY
statement — these are the same as those allowed forSCREEN SECTION
data items. A particular Attribute-Specification may be used only once in anyDISPLAY
:-
BACKGROUND-COLOR
(see BACKGROUND-COLOR) -
BEEP
(see BEEP),BELL
(see BELL) -
BLANK
(see BLANK) -
BLINK
(see BLINK) -
ERASE
(see ERASE) -
FOREGROUND-COLOR
(see FOREGROUND-COLOR) -
HIGHLIGHT
(see HIGHLIGHT) -
LOWLIGHT
(see LOWLIGHT) -
OVERLINE
(see OVERLINE) -
REVERSE-VIDEO
(see REVERSE-VIDEO) -
UNDERLINE
(see UNDERLINE)
-
- See ACCEPT screen-data-item, for additional information on the other
WITH
clause options.
- The purpose of the
- The optional
ON EXCEPTION
andNOT ON EXCEPTION
clauses may be used to detect and react to the failure or success, respectively, of the screen I/O attempt. See ON EXCEPTION + NOT ON EXCEPTION, for additional information.
When DISPLAY
is used with Line and column where multiple variables or literals are used before LINE
only the first will be displayed.
If this is needed then the use of CONCATENATE
to built more than one element together prior to the display, e.g., DISPLAY FUNCTION CONCATENATE (VARS-1 VARS-2) AT 0201
.
When DISPLAY
is used without line or column controls only one variable or literal may will appear on a line, so the use of the above example should also be employed.
7.8.13. DIVIDE
7.8.13.1. DIVIDE INTO
DIVIDE INTO Syntax
DIVIDE { literal-1 } INTO { identifier-2 ~~~~~~ { identifier-1 } ~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-DIVIDE ] ~~~~~~~~~~
This format of the DIVIDE
statement will divide a numeric value (specified as a literal or numeric data item) into one or more numeric data items, replacing the value in each of those data items with the result(s).
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items and literal-1 must be a numeric literal.
- A division operation will be performed for each identifier-2, in turn. Each of the results of those divisions will be saved to the corresponding identifier-2 data item(s).
- Should any identifier-2 be an integer numeric data item, the result computed when that identifier-2 is divided by literal-1 or identifier-1 will also be an integer — any remainder from that division will be discarded.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being numeric truncation caused by an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point, or an attempt to divide by zero. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.13.2. DIVIDE INTO GIVING
DIVIDE INTO GIVING Syntax
DIVIDE { literal-1 } INTO { literal-2 } GIVING { identifier-3 ~~~~~~ { identifier-1 } ~~~~ { identifier-2 } ~~~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } [ REMAINDER identifier-4 ] ~~~~~~~~~~ ~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-DIVIDE ] ~~~~~~~~~~
This format of the DIVIDE
statement will divide one numeric value (specified as a literal or numeric data item) into another numeric value (also specified as a literal or numeric data item) and will then replace the contents of one or more receiving data items with the results of that division.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items while both identifier-3 and identifier-4 must be numeric (edited or unedited) data items.
- Both literal-1 and literal-2 must be numeric literals.
- If the
REMAINDER
clause is coded, there may be only one identifier-3 specified. - The result obtained when the value of literal-2 or identifier-2 is divided by the value of literal-1 or identifier-1 is computed; this result is then moved into each identifier-3, in turn, applying the rules defined by the
ROUNDED
(see ROUNDED) clause (if any) for that identifier-3 to the move. - If a
REMAINDER
clause is specified, the value of the one and only identifier-3 (as stated earlier, ifREMAINDER
is specified there may only be a single identifier-3 coded on the statement) after it was assigned a value according to the previous rule will be multiplied by the value of literal-1 or identifier-1; that result is then subtracted from the value of literal-2 or identifier-2 and that result is the value which is moved to identifier-4. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point, or an attempt to divide by zero. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.13.3. DIVIDE BY GIVING
DIVIDE BY GIVING Syntax
DIVIDE { literal-1 } BY { literal-2 } GIVING { identifier-3 ~~~~~~ { identifier-1 } ~~ { identifier-2 } ~~~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } [ REMAINDER identifier-4 ] ~~~~~~~~~~ ~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-DIVIDE ] ~~~~~~~~~~
This format of the DIVIDE
statement will divide one numeric value (specified as a literal or numeric data item) into another numeric value (also specified as a literal or numeric data item) and will then replace the contents of one or more receiving data items with the results of that division.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items while both identifier-3 and identifier-4 must be numeric (edited or unedited) data items.
- Both literal-1 and literal-2 must be numeric literals.
- If the
REMAINDER
clause is coded, there may be only one identifier-3 specified. - The result obtained when the value of literal-1 or identifier-1 is divided by the value of literal-2 or identifier-2 is computed; this result is then moved into each identifier-3, in turn, applying the rules defined by the
ROUNDED
(see ROUNDED) clause (if any) for that identifier-3 to the move. - If a
REMAINDER
clause is specified, the value of the one and only identifier-3 (as stated earlier, ifREMAINDER
is specified there may only be a single identifier-3 coded on the statement) after it was assigned a value according to the previous rule will be multiplied by the value of literal-2 or identifier-2; that result is then subtracted from the value of literal-1 or identifier-1 and that result is the value which is moved to identifier-4. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point, or an attempt to divide by zero. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.14. ENTRY
ENTRY Syntax
ENTRY literal-1 [ USING ENTRY-Argument... ] ~~~~~ ~~~~~
ENTRY-Argument Syntax
[ BY { REFERENCE } ] identifier-1 { ~~~~~~~~~ } { CONTENT } { ~~~~~~~ } { VALUE } ~~~~~
The ENTRY
statement is used to define an alternate entry-point into a subroutine, along with the arguments that subroutine will be expecting.
- The reserved word
BY
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - You may not use an
ENTRY
statement in a nested subprogram, nor may you use it in any form of user-defined function. - The
USING
clause defines the arguments the subroutine entry-point supports. This list of arguments must match up against theUSING
clause of anyCALL
statement that will be invoking the subroutine using this entry-point. - Each ENTRY-Argument specified on the
ENTRY
statement must be defined in the linkage section of the subroutine in which theENTRY
statement exists. - The literal-1 value will specify the entry-point name of the subroutine. It must be specified exactly on
CALL
statements (with regard to the use of upper- and lower-case letters) as it is specified on theENTRY
statement. - The meaning of
REFERENCE
,CONTENT
andVALUE
are the same as the equivalent specifications on theCALL
statement (see CALL). Whatever specification will be used for an argument on theCALL
to this entry-point should match the specification used in the corresponding ENTRY-Argument. The same rules regarding the presence or absence of aBY
clause on aCALL
statement apply to the presence or absence of aBY
clause on the corresponding argument of theENTRY
statement.
7.8.15. EVALUATE
EVALUATE Syntax
EVALUATE Selection-Subject-1 [ ALSO Selection-Subject-2 ]... ~~~~~~~~ ~~~~ { { WHEN Selection-Object-1 [ ALSO Selection-Object-2 ] }... ~~~~ ~~~~ [ imperative-statement-1 ] }... [ WHEN OTHER ~~~~ ~~~~~ imperative-statement-other ] [ END-EVALUATE ] ~~~~~~~~~~~~
EVALUATE Selection Subject Syntax
{ TRUE } { ~~~~ } { FALSE } { ~~~~~ } { expression-1 } { identifier-1 } { literal-1 }
EVALUATE Selection Object Syntax
{ ANY } { ~~~ } { TRUE } { ~~~~ } { FALSE } { ~~~~~ } { partial-expression-1 } { } { { expression-2 } [ THRU|THROUGH { expression-3 } ] } { { identifier-2 } ~~~~ ~~~~~~~ { identifier-3 } } { { literal-2 } { literal-3 } }
The EVALUATE
statement provides a means of defining processing that should take place under any number of mutually-exclusive conditions.
- The reserved words
THRU
andTHROUGH
are interchangeable. - There must be at least one
WHEN
clause (in addition to anyWHEN OTHER
clause) specified on anyEVALUATE
statement. - There must be at least one Selection-Subject specified on the
EVALUATE
statement. Any number of additional Selection-Subject clauses may be specified, using theALSO
reserved word to separate each from the prior. - Each
WHEN
clause (other than theWHEN OTHER
clause, if any) must have the same number of Selection-Object clauses as there are Selection-Subject clauses. - When using
THRU
, the values on both sides of theTHRU
must be the same class (both numeric, both alphanumeric, etc.). - A partial-expression is one of the following:
- A Class Condition without a leading identifier-1 (see Class Conditions).
- A Sign Condition without a leading identifier-1 (see Sign Conditions).
- A Relation Condition with nothing to the left of the relational operator (see Relation Conditions).
- At execution time, each Selection-Subject on the
EVALUATE
statement will have its value matched against that of the corresponding Selection-Object on aWHEN
clause, in turn, until:- A
WHEN
clause has each of its Selection-Object(s) successfully matched by the corresponding Selection-Subject; this will be referred to as the ’Selected WHEN clause’. - The complete list of
WHEN
clauses (except for theWHEN OTHER
clause, if any) has been exhausted. In this case, there is no ’Selected WHEN Clause’.
- A
- If a ’Selected WHEN Clause’ was identified:
- The imperative-statement-1 (see Imperative Statement) immediately following the ’Selected WHEN Clause’ will be executed. If the ’Selected WHEN Clause’ is lacking an imperative-statement-1, the first imperative-statement-1 found after any following
WHEN
clause will be executed. - Once the imperative-statement-1 has been executed, or no imperative-statement-1 was found anywhere after the ’Selected WHEN Clause’, control will proceed to the statement following the
END-EVALUATE
or, if there is noEND-EVALUATE
, the first statement that follows the next period. If, however, the imperative-statement-1 included aGO TO
statement, and thatGO TO
was executed, then control will transfer to the procedure named on theGO TO
instead.
- The imperative-statement-1 (see Imperative Statement) immediately following the ’Selected WHEN Clause’ will be executed. If the ’Selected WHEN Clause’ is lacking an imperative-statement-1, the first imperative-statement-1 found after any following
- If no ’Selected WHEN Clause’ was identified:
- The
WHEN OTHER
clause’s imperative-statement-other will be executed, if such a clause was coded. - Control will then proceed to the statement following the
END-EVALUATE
or the first statement that follows the next period if there is noEND-EVALUATE
. If,however, the imperative-statement-other included aGO TO
statement, and thatGO TO
was executed, then control will transfer to the procedure named on theGO TO
instead.
- The
- In order for a Selection-Subject to match the corresponding Selection-Object on a
WHEN
clause, at least one of the following must be true:- The Selection-Object is
ANY
- The implied Relation Condition
Selection-Subject = Selection Object
isTRUE
— See Relation Conditions, for the rules on how the comparison will be made. - The value of the Selection-Subject falls within the range of values specified by the
THRU
clause of the Selection-Object - If the Selection-Object is a partial-expression, then the conditional expression that would be represented by coding
Selection-Subject Selection-Object
evaluates toTRUE
- The Selection-Object is
- Here is a sample program that illustrates the EVALUATE statement.
IDENTIFICATION DIVISION. PROGRAM-ID. DEMOEVALUATE. DATA DIVISION. WORKING-STORAGE SECTION. 01 Test-Digit PIC 9(1). 88 Digit-Is-Odd VALUE 1, 3, 5, 7, 9. 88 Digit-Is-Prime VALUE 1, 3, 5, 7. PROCEDURE DIVISION. P1. PERFORM UNTIL EXIT DISPLAY "Enter a digit (0 Quits): " WITH NO ADVANCING ACCEPT Test-Digit IF Test-Digit = 0 EXIT PERFORM END-IF EVALUATE Digit-Is-Odd ALSO Digit-Is-Prime WHEN TRUE ALSO FALSE DISPLAY Test-Digit " is ODD" WITH NO ADVANCING WHEN TRUE ALSO TRUE DISPLAY Test-Digit " is PRIME" WITH NO ADVANCING WHEN FALSE ALSO ANY DISPLAY Test-Digit " is EVEN" WITH NO ADVANCING END-EVALUATE EVALUATE Test-Digit WHEN < 5 DISPLAY " and it's small too" WHEN < 8 DISPLAY " and it's medium too" WHEN OTHER DISPLAY " and it's large too" END-EVALUATE END-PERFORM DISPLAY "Bye!" STOP RUN .
Console output when run (user input follows the colons on the prompts for input):
Enter a digit (0 Quits): 1 1 is PRIME and it's small too Enter a digit (0 Quits): 2 2 is EVEN and it's small too Enter a digit (0 Quits): 3 3 is PRIME and it's small too Enter a digit (0 Quits): 4 4 is EVEN and it's small too Enter a digit (0 Quits): 5 5 is PRIME and it's medium too Enter a digit (0 Quits): 6 6 is EVEN and it's medium too Enter a digit (0 Quits): 7 7 is PRIME and it's medium too Enter a digit (0 Quits): 8 8 is EVEN and it's large too Enter a digit (0 Quits): 9 9 is ODD and it's large too Enter a digit (0 Quits): 0 Bye!
7.8.16. EXIT
EXIT Syntax
EXIT [ { PROGRAM } ] ~~~~ { ~~~~~~~ } { FUNCTION } { ~~~~~~~~ } { PERFORM [ CYCLE ] } { ~~~~~~~ ~~~~~ } { SECTION } { ~~~~~~~ } { PARAGRAPH } ~~~~~~~~~
The EXIT
statement is a multi-purpose statement; it may provide a common end point for a series of procedures, exit an in-line PERFORM
, paragraph or section or it may mark the logical end of a subprogram, returning control back to the calling program.
- The
EXIT PROGRAM
statement is not legal anywhere within a user-defined function. - The
EXIT FUNCTION
statement cannot be used anywhere within a subroutine. - Neither
EXIT PROGRAM
norEXIT FUNCTION
may be used within aUSE GLOBAL
routine inDECLARATIVES
(see DECLARATIVES). - The following points describe the
EXIT
statement with none of the optional clauses:- When this form of an
EXIT
statement is used, it must be the only statement in the procedure (paragraph or section) in which it occurs. This is not enforced in GnuCOBOL. - This usage of the
EXIT
statement simply provides a common “GO TO” end point for a series of procedures, as may be seen in the following example:01 Switches. 05 Input-File-Switch PIC X(1). 88 EOF-On-Input-File VALUE ``Y'' FALSE ``N''. … SET EOF-On-Input-File TO FALSE. PERFORM 100-Process-A-Transaction THRU 199-Exit UNTIL EOF-On-Input-File. … 100-Process-A-Transaction. READ Input-File AT END SET EOF-On-Input-File TO TRUE GO TO 199-Exit END-READ. IF Input-Rec of Input-File = SPACES GO TO 199-Exit *> IGNORE BLANK RECORDS! END-IF. <<process the record just read>> 199-Exit. EXIT.
- In this case, the
EXIT
statement takes no other run-time action.
- When this form of an
- The following points apply to the
EXIT PARAGRAPH
andEXIT SECTION
statements:- If an
EXIT PARAGRAPH
statement orEXIT SECTION
statement resides in a paragraph within the scope of a proceduralPERFORM
(see Procedural PERFORM), control will be returned back to thePERFORM
for evaluation of anyTIMES
,VARYING
and/orUNTIL
clauses. - If an
EXIT PARAGRAPH
statement orEXIT SECTION
statement resides outside the scope of a proceduralPERFORM
, control simply transfers to the first executable statement in the next paragraph (EXIT PARAGRAPH
) or section (EXIT SECTION
). - The following shows how the previous example could have been coded without a
GO TO
by utilizing anEXIT PARAGRAPH
statement.01 Switches. 05 Input-File-Switch PIC X(1). 88 EOF-On-Input-File VALUE ``Y'' FALSE ``N''. … SET EOF-On-Input-File TO FALSE. PERFORM 100-Process-A-Transaction UNTIL EOF-On-Input-File. … 100-Process-A-Transaction. READ Input-File AT END SET EOF-On-Input-File TO TRUE EXIT PARAGRAPH END-READ. IF Input-Rec of Input-File = SPACES EXIT PARAGRAPH *> IGNORE BLANK RECORDS! END-IF. <<process the record just read>>
- If an
- The following points apply to the
EXIT PERFORM
andEXIT PERFORM CYCLE
statements:- The
EXIT PERFORM
andEXIT PERFORM CYCLE
statements are intended to be used in conjunction with an in-linePERFORM
statement (see Inline PERFORM). - An
EXIT PERFORM CYCLE
statement will terminate the current iteration of the in-linePERFORM
, giving control to anyTIMES
,VARYING
and/orUNTIL
clauses for them to determine if another cycle needs to be performed. - An
EXIT PERFORM
statement will terminate the in-line PERFORM outright, transferring control to the first statement following theEND-PERFORM
(if there is one) or to the next sentence following thePERFORM
if there is noEND-PERFORM
. - This last example shows the final modification to the previous examples by using an in-line
PERFORM
along withEXIT PERFORM
andEXIT PERFORM CYCLE
statements:PERFORM FOREVER READ Input-File AT END EXIT PERFORM END-READ IF Input-Rec of Input-File = SPACES EXIT PERFORM CYCLE *> IGNORE BLANK RECORDS! END-IF <<process the record just read>> END PERFORM
- The
- The following points apply to the
EXIT PROGRAM
andEXIT FUNCTION
statements:- The
EXIT PROGRAM
andEXIT FUNCTION
statements terminate the execution of a subroutine (i.e. a program that has been CALLed by another) or user-defined function, respectively, returning control back to the calling program. - An
EXIT PROGRAM
statement returns control back to the statement following theCALL
(see CALL) of the subprogram. AnEXIT FUNCTION
statement returns control back to the processing of the statement in the calling program that invoked the user-defined function. - If executed by a main program, neither the
EXIT PROGRAM
norEXIT FUNCTION
statements will take any action. - The COBOL2002 standard has made a common extension to the COBOL language — the
GOBACK
statement (see GOBACK) — a standard language element; theGOBACK
statement should be strongly considered as the preferred alternative to bothEXIT PROGRAM
andEXIT FUNCTION
for new subprograms.
- The
7.8.17. FREE
FREE Syntax
FREE { [ ADDRESS OF ] identifier-1 }... ~~~~ ~~~~~~~
The FREE
statement releases memory previously allocated to the program by the ALLOCATE
statement (see ALLOCATE).
- The
ADDRESS OF
clause is optional and may be omitted. The presence or absence of this clause has no effect upon the program. - identifier-1 must have a
USAGE
(see USAGE) ofPOINTER
, or it must be an 01-level data item with theBASED
(see BASED) attribute. - If identifier-1 is a
USAGE POINTER
data item and it contains a valid address, theFREE
statement will release the memory block the pointer references. In addition, anyBASED
data items that the pointer was used to provide an address for will become un-based and therefore unusable. If identifier-1 did not contain a valid address, no action will be taken. - If identifier-1 is a
BASED
data item and that data item is currently based (meaning it currently has memory allocated to it), its memory is released and identifier-1 will become un-based and therefore unusable. If identifier-1 was not based, no action will be taken.
7.8.18. GENERATE
GENERATE Syntax
GENERATE { report-name-1 } ~~~~~~~~ { identifier-1 }
The GENERATE
statement presents data to a report.
- The following points apply when identifier-1 is specified:
- identifier-1 must be the name of a
DETAIL
(see RWCS Lexicon) report group. - If necessary, identifier-1 may be qualified with a report name.
- The file in whose
FD
aREPORT
clause exists for the report in which identifier-1 is a detail group must be opened forOUTPUT
orEXTEND
at the time theGENERATE
is executed. See OPEN, for information on file open modes. - The report in which identifier-1 is a
DETAIL
group must have been successfully initiated via theINITIATE
statement (see INITIATE) and not yet terminated via theTERMINATE
statement (see TERMINATE) at the time theGENERATE
is executed. - If at least one
GENERATE
statement of this form is executed against a report, the report is said to be a detail report. If noGENERATE
statements of this form are executed against a report, the report is said to be a summary report.
- identifier-1 must be the name of a
- The following points apply when report-name-1 is specified:
- report-name-1 must be the name of a report having an
RD
defined for it in the report section. - There must be at least one
CONTROL
(see RWCS Lexicon) group defined for report-name-1. - There cannot be more than one
DETAIL
group defined for report-name-1. - The file in whose
FD
aREPORT report-name-1
clause exists must be open forOUTPUT
orEXTEND
at the time the GENERATE is executed. - report-name-1 must have been successfully initiated (via
INITIATE report-name-1
) and not yet terminated (via TERMINATE) at the time theGENERATE
is executed. See OPEN, for information on file open modes. - The
DETAIL
group which is defined for report-name-1 will be processed but will not actually be presented to any report page. This will allow summary processing to take place. If allGENERATE
statements are of this form, the report is said to be a summary report. If at least oneGENERATE identifier-1
is executed, the report is considered to be a detail report.
- report-name-1 must be the name of a report having an
- When the first
GENERATE
statement for a report is executed, the contents of all control fields are saved so they may be referenced during the processing of subsequentGENERATE
statements. - When, during the processing of a subsequent
GENERATE
, it is determined that a control field has changed value (ie. a control break has occurred), the appropriate control footing and control heading processing will take place and a snapshot of the current values of all control fields will again be saved.
7.8.19. GOBACK
GOBACK Syntax
GOBACK [ { RETURNING|GIVING { literal-1 } ] ~~~~~~ { ~~~~~~~~~ ~~~~~~ { identifier-1 }
The GOBACK
statement is used to logically terminate an executing program.
- If executed within a subprogram (i.e. a subroutine or user-defined function),
GOBACK
behaves like anEXIT PROGRAM
orEXIT FUNCTION
statement, respectively. - If executed within a main program,
GOBACK
will act as aSTOP RUN
statement. - The optional
RETURNING
clause provides the opportunity to return a numeric value to the operating system (technically, an exit status The manner in which the exit status value is interrogated by the operating system varies. Windows can use%ERRORLEVEL%
to query the exit status while Unix shells such assh
,bash
andksh
can query the exit status as$?
. Other Unix shells may have different ways to access the exit status.
7.8.20. GO TO
7.8.20.1. Simple GO TO
Simple GO TO Syntax
GO TO procedure-name-1 ~~
This form of the GO TO
statement unconditionally transfers control in a program to the first executable statement within the specified procedure-name-1.
- The reserved word
TO
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - If this format of the
GO TO
statement appears in a consecutive sequence of imperative statements (see Imperative Statement) within a sentence, it must be the final statement in the sentence. - If a
GO TO
is executed within the scope of…- ...an in-line
PERFORM
(see PERFORM), thePERFORM
is terminated as control of execution transfers to procedure-name-1. - ...a procedural
PERFORM
(see PERFORM), and procedure-name-1 lies outside the scope of thatPERFORM
, thePERFORM
is terminated as control of execution transfers to procedure-name-1. - ...a
MERGE
statement (see MERGE)OUTPUT PROCEDURE
or within the scope of either anINPUT PROCEDURE
orOUTPUT PROCEDURE
of aSORT
statement (see File-Based SORT), and procedure-name-1 lies outside the scope of that procedure, theSORT
orMERGE
operation is terminated as control of execution transfers to procedure-name-1. Any sorted or merged data accumulated to that point is lost.
- ...an in-line
7.8.20.2. GO TO DEPENDING ON
GO TO DEPENDING ON Syntax
GO TO procedure-name-1... ~~ DEPENDING ON identifier-1 ~~~~~~~~~
This form of the GO TO
statement will transfer control to any one of a number of specified procedure names depending on the numeric value of the identifier specified on the statement.
- The reserved word
TO
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The
PICTURE
(see PICTURE) and/orUSAGE
(see USAGE) of the specified identifier-1 must be such as to define it as a numeric, unedited, preferably unsigned integer data item. - If the value of identifier-1 has the value 1, control will be transferred to the 1st specified procedure name. If the value is 2, control will transfer to the 2nd procedure name, and so on.
If control of execution is transferred to a procedure named on the statement, and the
GO TO
is executed within the scope of…- ...an in-line
PERFORM
(see PERFORM), thePERFORM
is terminated as control of execution transfers to the procedure named on the statement. - ...a procedural
PERFORM
(see PERFORM), and procedure-name-1 lies outside the scope of thatPERFORM
, thePERFORM
is terminated as control of execution transfers to the procedure named on the statement. - ...a
MERGE
statement (see MERGE)OUTPUT PROCEDURE
or within the scope of either anINPUT PROCEDURE
orOUTPUT PROCEDURE
of aSORT
statement (see File-Based SORT), and procedure-name-1 lies outside the scope of that procedure, theSORT
orMERGE
operation is terminated as control of execution transfers to the procedure named on the statement. Any sorted or merged data accumulated to that point is lost.
- ...an in-line
- If the value of identifier-1 is less than 1 or exceeds the total number of procedure names specified on the statement, control will simply fall through into the next statement following the
GO TO
. - The following example shows how
GO TO ... DEPENDING ON
may be used in a real application situation, and compares it against an alternative —EVALUATE
(see EVALUATE).GO TO DEPENDING ON EVALUATE GO TO ACCT-TYPE-1 ACCT-TYPE-2 ACCT-TYPE-3 DEPENDING ON Acct-Type. <<< Invalid Acct Type >>> GO TO All-Done. Acct-Type-1. <<< Handle Acct Type 1 >>> GO TO All-Done. Acct-Type-2. <<< Handle Acct Type 2 >>> GO TO All-Done. Acct-Type-3. <<< Handle Acct Type 3 >>> All-Done.
EVALUATE Acct-Type WHEN 1 <<< Handle Acct Type 1 >>> WHEN 2 <<< Handle Acct Type 2 >>> WHEN 3 <<< Handle Acct Type 3 >>> WHEN OTHER <<< Invalid Acct Type >>> END-EVALUATE.
- Current programming philosophy would prefer the use of the
EVALUATE
statement to that of this form of theGO TO
statement.
7.8.21. IF
IF Syntax
IF conditional-expression ~~ THEN { imperative-statement-1 } { NEXT SENTENCE } ~~~~ ~~~~~~~~ [ ELSE { imperative-statement-2 } ] ~~~~ { NEXT SENTENCE } ~~~~ ~~~~~~~~ [ END-IF ] ~~~~~~
The IF
statement is used to conditionally execute an imperative statement (see Imperative Statement) or to select one of two different imperative statements to execute based upon the TRUE
/FALSE
value of a conditional expression.
- The reserved word
THEN
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - You cannot use both
NEXT SENTENCE
and theEND-IF
scope terminator in the sameIF
statement. - If conditional-expression evaluates to
TRUE
, imperative-statement-1 will be executed regardless of whether or not anELSE
clause is present. Once imperative-statement-1 has been executed, control falls into the first statement following theEND-IF
or to the first statement of the next sentence if there is noEND-IF
clause. - If the optional
ELSE
clause is present and conditional-expression evaluates to false, then (and only then) imperative-statement-2 will be executed. Once imperative-statement-2 has been executed, control falls into the first statement following theEND-IF
or to the first statement of the next sentence if there is noEND-IF
clause. - The clause
NEXT SENTENCE
may be substituted for either imperative-statement, but not both. If control reaches aNEXT SENTENCE
clause due to the truth or falsehood of conditional-expression, control will be transferred to the first statement of the next sentence found in the program (the first statement after the next period).NEXT SENTENCE
was needed for COBOL programs that were coded according to pre-1985 standards that wish to nest oneIF
statement inside another. See Use of VERB/END-VERB Constructs, for an explanation of whyNEXT SENTENCE
was necessary.Programs coded for 1985 (and beyond) standards don’t need it, instead using the explicit scope-terminator
END-IF
to inform the compiler where imperative-statement-2 (or imperative-statement-1 if there is noELSE
clause coded) ends. New GnuCOBOL programs should be coded to use theEND-IF
scope terminator forIF
statements. See Use of VERB/END-VERB Constructs, for additional information.
7.8.22. INITIALIZE
INITIALIZE Syntax
INITIALIZE|INITIALISE identifier-1... ~~~~~~~~~~ ~~~~~~~~~~ [ WITH FILLER ] ~~~~~~ [ { category-name-1 } TO VALUE ] { ALL } ~~~~~ ~~~ [ THEN REPLACING { category-name-2 DATA BY ~~~~~~~~~ ~~ [ LENGTH OF ] { literal-1 } }... ] ~~~~~~ { identifier-1 } [ THEN TO DEFAULT ] ~~~~~~~
The INITIALIZE
statement initializes each identifier-1 with certain specific values, depending upon the options specified.
- The reserved words
DATA
,OF
,THEN
,TO
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
INITIALIZE
andINITIALISE
are interchangeable. - The
WITH FILLER
,REPLACING
andDEFAULT
clauses are meaningful only if identifier-1 is a group item. They are accepted if it’s an elementary item, but will serve no purpose. TheVALUE
clause is meaningful in both cases. - A category-name-1 and/or category-name-2 may be any of the following:
- ALPHABETIC
-
The
PICTURE
(see PICTURE) of the data item only containsA
symbols. - ALPHANUMERIC
-
The
PICTURE
of the data item contains onlyX
or a combination ofA
and9
symbols. - ALPHANUMERIC-EDITED
-
The
PICTURE
of the data item contains onlyX
or a combination ofA
and9
symbols plus at least oneB
,0
(zero) or/
symbol. - NUMERIC
-
The data item is one that is described with a picture less
USAGE
(see USAGE) or has aPICTURE
composed of nothing butP
,9
,S
andV
symbols. - NUMERIC-EDITED
-
The
PICTURE
of the data item contains nothing but the symbol9
and at least one of the editing symbols$
,+
,-
,CR
,DB
,.
,,
,*
orZ
. - NATIONAL
-
The data item is one containing nothing but the
N
symbol. - NATIONAL-EDITED
-
The data item contains nothing but
N
,B
,/
and0
symbols.
- From the sequence of identifier-1 data items specified on the
INITIALIZE
statement, a list of initialized fields referred to as the field list in the remainder of this section, will include:- Every identifier-1 that is an elementary item, including any that may have the
REDEFINES
(see REDEFINES) clause in their descriptions. - Every non-
FILLER
3elementary item subordinate to identifier-1, provided that elementary item neither contains aREDEFINES
clause in its definition nor belongs to a group item subordinate to identifier-1 which contains aREDEFINES
clause in its definition. - If the optional
WITH FILLER
clause is included on theINITIALIZE
statement, then every FILLER elementary item subordinate to each identifier-1 will be included as well, provided that elementary item neither contains aREDEFINES
clause in its definition nor belongs to a group item subordinate to identifier-1 which contains aREDEFINES
clause in its definition..
- Every identifier-1 that is an elementary item, including any that may have the
- Once a field list has been determined, each item in that field list will be initialized as if an individual
MOVE
(see MOVE) statement to that effect had been coded. The rules for initialization are as follows: - If no
VALUE
,REPLACING
orDEFAULT
clauses are coded, each member of the field list will be initialized as if the figurative constantZERO
(if the field list item is numeric or numeric-edited) orSPACES
(otherwise) were being moved to it. - If a
VALUE
clause is specified on theINITIALIZE
statement, each qualifying member of the field list having a compile-timeVALUE
(see VALUE) specified in its definition will be initialized to that value. Field list members withVALUE
clauses will qualify for this treatment as follows:- If the
ALL
keyword was specified on theVALUE
clause, all members of the field list withVALUE
clauses will qualify. - If category-name-1 is specified instead of
ALL
, only those members of the field list withVALUE
clauses that also meet the criteria set down for the specified category-name (see the list above) will qualify. - If you need to apply
VALUE
initialization to multiple category-name-1 values, you will need to use multipleINITIALIZE
statements.
- If the
- If a
REPLACING
clause is specified on theINITIALIZE
statement, each qualifying member of the field list that was not already initialized by aVALUE
clause, if any, will be initialized to the specified literal-1 or identifier-1 value.Only those as-yet uninitialized list members meeting the criteria set forth for the specified category-name-2 will qualify for this initialization.
If you need to apply
REPLACING
initialization to multiple category-name-2 values, you may repeat the syntax after the reserved wordREPLACING
, as necessary. - If a
DEFAULT
clause is specified, any remaining uninitialized members of the field list will be initialized according to the default for their class (numeric and numeric-edited are initialized toZERO
, all others are initialized toSPACES
). - The following example may help your understanding of how the
INITIALIZE
statement works. The sample code makes use of theCOBDUMP
program to dump the storage that is (or is not) being initialized. See COBDUMP in GnuCOBOL Sample Programs, for a source and cross-reference listing of theCOBDUMP
program.IDENTIFICATION DIVISION. PROGRAM-ID. DemoInitialize. DATA DIVISION. WORKING-STORAGE SECTION. 01 Item-1. 05 I1-A VALUE ALL '*'. 10 FILLER PIC X(1). 10 I1-A-1 PIC 9(1) VALUE 9. 05 I1-B USAGE BINARY-CHAR. 05 I1-C PIC A(1) VALUE 'C'. 05 I1-D PIC X/X VALUE 'ZZ'. 05 I1-E OCCURS 2 TIMES PIC 9. PROCEDURE DIVISION. 000-Main. DISPLAY "MOVE HIGH-VALUES TO Item-1" PERFORM 100-Init-Item-1 CALL "COBDUMP" USING Item-1 DISPLAY " " DISPLAY "INITIALIZE Item-1" INITIALIZE Item-1 CALL "COBDUMP" USING Item-1 PERFORM 100-Init-Item-1 DISPLAY " " DISPLAY "INITIALIZE Item-1 WITH
FILLER
" MOVE HIGH-VALUES TO Item-1 INITIALIZE Item-1 WITHFILLER
CALL "COBDUMP" USING Item-1 PERFORM 100-Init-Item-1 DISPLAY " " DISPLAY "INITIALIZE Item-1 ALL TO VALUE" MOVE HIGH-VALUES TO Item-1 INITIALIZE Item-1 ALPHANUMERIC TO VALUE CALL "COBDUMP" USING Item-1 PERFORM 100-Init-Item-1 DISPLAY " " DISPLAY "INITIALIZE Item-1 REPLACING NUMERIC BY 1" MOVE HIGH-VALUES TO Item-1 INITIALIZE Item-1 REPLACING NUMERIC BY 1 CALL "COBDUMP" USING Item-1 PERFORM 100-Init-Item-1 DISPLAY " " STOP RUN . 100-Init-Item-1. MOVE HIGH-VALUES TO Item-1 .When executed, this program produces the following output:
MOVE HIGH-VALUES TO Item-1 <-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ----> ======== ==== =============================================== ================ 00404058 1 FF FF FF FF FF FF FF FF FF ......... INITIALIZE Item-1 <-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ----> ======== ==== =============================================== ================ 00404058 1 FF 30 00 20 20 2F 20 30 30 .0. / 00 INITIALIZE Item-1 WITH
FILLER
<-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ----> ======== ==== =============================================== ================ 00404058 1 20 30 00 20 20 2F 20 30 30 0. / 00 INITIALIZE Item-1 ALL TO VALUE <-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ----> ======== ==== =============================================== ================ 00404058 1 2A 2A FF 43 5A 5A 20 FF FF **.CZZ .. INITIALIZE Item-1 REPLACING NUMERIC BY 1 <-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ----> ======== ==== =============================================== ================ 00404058 1 FF 31 01 FF FF FF FF 31 31 .1.....11
7.8.23. INITIATE
INITIATE Syntax
INITIATE report-name-1 ~~~~~~~~
The INITIATE
statement starts Report-Writer Control System (RWCS) processing for a report.
- Each report-name-1 must be the name of a report having an
RD
(see REPORT SECTION) defined for it. - The file in whose
FD
(see File/Sort-Description) aREPORT report-name-1
clause exists must be open forOUTPUT
orEXTEND
at the time theINITIATE
statement is executed. See OPEN, for more information on file open modes. - The
INITIATE
statement will initialize all of the following for each report named on the statement:- All sum counters, if any, will be set to 0
- The report’s
LINE-COUNTER
special register (see Special Registers) will be set to 0 - The report’s
PAGE-COUNTER
special register will be set to 1
- No report content will actually presented to the report file as a result of a successful
INITIATE
statement — that will not occur until the firstGENERATE
statement (see GENERATE) is executed.
7.8.24. INSPECT
INSPECT Syntax
INSPECT { literal-1 } ~~~~~~~ { identifier-1 } { function-reference-1 } [ TALLYING { identifier-2 FOR { ALL|LEADING|TRAILING { literal-2 } } ~~~~~~~~ ~~~ { ~~~ ~~~~~~~ ~~~~~~~~ { identifier-3 } } { CHARACTERS } ~~~~~~~~~~ [ | { AFTER|BEFORE } INITIAL { literal-3 } | ] }... ] | ~~~~~ ~~~~~~ { identifier-4 } | [ REPLACING { { { ALL|FIRST|LEADING|TRAILING { literal-4 } } ~~~~~~~~~ { { ~~~ ~~~~~ ~~~~~~~ ~~~~~~~~ { identifier-5 } } { CHARACTERS } { ~~~~~~~~~~ } BY { [ ALL ] literal-5 } ~~ { ~~~ } { identifier-6 } [ | { AFTER|BEFORE } INITIAL { literal-6 } | ] }... ] | ~~~~~ ~~~~~~ { identifier-7 } | [ CONVERTING { { literal-7 } TO { literal-8 } ~~~~~~~~~~ { identifier-8 } ~~ { identifier-9 } [ | { AFTER|BEFORE } INITIAL { literal-9 } | ] ] | ~~~~~ ~~~~~~ { identifier-10 } |
The INSPECT
statement is used to perform various counting and/or data-alteration operations against strings.
- The reserved word
INITIAL
is optional and may be omitted. The presence or absence of this words has no effect upon the program. - If a
CONVERTING
clause is specified, neither theTALLYING
norREPLACING
clauses may be used. - If either the
TALLYING
orREPLACING
clauses are specified, theCONVERTING
clause cannot be used. - If both the
TALLYING
andREPLACING
clauses are specified, they must be specified in the order shown. - All literals and identifiers must be explicitly or implicitly defined as alphanumeric or alphabetic.
- If function-reference-1 is specified, it must be an invocation of an intrinsic function that returns a string result. Additionally, only the
TALLYING
clause may be specified. - If literal-1 is specified, only the
TALLYING
clause may be specified. - Whichever is specified — literal-1, identifier-1 or function-reference-1 — that item will be referred to in the discussions that follows as the ’inspect subject’.
- The three optional clauses control the operation of this statement as follows:
- The
CONVERTING
clause replaces one or more individual characters found in the inspect subject with a different character in much the same manner as is possible with theTRANSFORM
statement (see TRANSFORM). - The
REPLACING
clause replaces one or more sub strings located in the inspect subject with a different, but equally-sized replacement sub string. If you need to replace a sub string with another of a different length, consider using either theSUBSTITUTE
intrinsic function (see SUBSTITUTE) or theSUBSTITUTE-CASE
intrinsic function (see SUBSTITUTE-CASE). - The
TALLYING
clause counts the number of occurrences of one or more strings of characters in the inspect subject.
- The
- The optional
INITIAL
clauses may be used to limit the range of characters in the inspect subject that theCONVERTING
,REPLACING
orTALLYING
instruction in which they occur will apply. We call this the ’target range’ of the inspect subject. The target range is defined as follows:- If there is no
INITIAL
clause specified, the target range is the entire inspect subject. - Either a
BEFORE
phrase, anAFTER
phrase or both may be specified. They may be specified in any order. - The starting point of the target range will be the first character following the sub string identified by the
AFTER
specification. The ending point will be the last character immediately preceding the sub string identified by theBEFORE
specification. - If no
AFTER
is specified, the first character position of the target range will be character position #1 of the inspect subject. - If no
BEFORE
is specified, the last character position of the target range will be the last character position of the inspect subject.
- If there is no
- The following points apply to the use of the
TALLYING
clause:- While there will typically be only be a single set of counting instructions on an
INSPECT
:INSPECT Character-String TALLYING C-ABC FOR ALL "ABC"
There could be multiple counting instructions specified:
INSPECT Character-String TALLYING C-ABC FOR ALL "ABC" C-BCDE FOR ALL "BCDE"
When there are multiple instructions, the one specified first will take priority over the one specified second, (and so forth) as the
INSPECT
proceeds forward through the inspect subject, character-by-character.With the above example, if the inspect subject were
--ABCDEF----BCDEF--
, the final result of the counting would be thatC-ABC
would be incremented by 1 whileC-BCDE
would be incremented only once; although the human eye clearly sees two ‘BCDE’ sequences, theINSPECT ... TALLYING
would only “see” the second — the first would have been processed by the first (higher-priority) counting instruction. - Each set of counting instructions contains the following information:
- A target range, specified by the presence of an
AFTER INITIAL
and/orBEFORE INITIAL
clause; the rules for specifying target ranges were covered previously. - A Target Sub string — this is a sequence of characters to be located somewhere in the inspect subject and counted. Target sub strings may be defined as a literal value (figurative constants are allowed) or by the contents of an identifier. If the target sub string is specified as a figurative constant, it will be assumed to have a length of one (‘1’) character. The keywords before the literal or identifier control how many target sub strings could be identified from that replacement instruction, as follows:
ALL
— identifies every possible target sub string that occurs within the target range. There are three occurrences ofALL 'XX'
found inaXXabbXXccXXdd
.LEADING
— identifies only an occurrence of the target sub string found either at the first character position of the target range or immediately following a previously-found occurrence. There are no occurrences ofLEADING 'XX'
found inaXXabbXXccXXdd
, but there is one occurrence ofLEADING 'a'
(the first character).TRAILING
— identifies only an occurrence of the target sub string found either at the very end of the target range or toward the end, followed by nothing but other occurrences. There are no occurrences ofLEADING 'XX'
found inaXXabbXXccXXdd
, but there are two occurrences ofTRAILING 'd'
.The
CHARACTERS
option will match any one single character, regardless of what that character is.
- A target range, specified by the presence of an
- identifier-2 will be incremented by 1 each time the target sub string is found within the target range of the inspect subject. The
INSPECT
statement will not zero-out identifier-2 at the start of execution of theINSPECT
— it is the programmer’s responsibility to ensure that all identifier-2 data items are properly initialized to the desired starting values prior to execution of theINSPECT
.
- While there will typically be only be a single set of counting instructions on an
- The following points apply to the use of the
REPLACING
clause:- While there will typically be only be a single set of replacement instructions on an
INSPECT
:INSPECT Character-String REPLACING ALL "ABC" BY "DEF"
There could be multiple replacement instructions:
INSPECT Character-String REPLACING ALL "ABC" BY "DEF" ALL "BCDE" BY "WXYZ"
When there are multiple replacement instructions, the one specified first will take priority over the one specified second, (and so forth) as the
INSPECT
proceeds forward through the inspect subject, character-by-character.With the above example, if the inspect subject were
--ABCDEF----BCDEF--
, the final result of the replacement would be--DEFDEF----WXYZF--
. - Each set of replacement instructions contains the following information:
- A target range, specified by the presence of an
AFTER INITIAL
and/orBEFORE INITIAL
clause; the rules for specifying target ranges were covered previously. - A Target Sub string — this is a sequence of characters to be located somewhere in the inspect subject and subsequently replaced with a new value. Target sub strings, which are specified before the
BY
keyword, may be defined as a literal value (figurative constants are allowed) or by the contents of an identifier. If the target sub string is specified as a figurative constant, it will be assumed to have a length of one (‘1’) character. The keywords before the literal or identifier control how many target sub strings could be identified from that replacement instruction, as follows:ALL
— identifies every possible target sub string that occurs within the target range. There are three occurrences ofALL 'XX'
found inaXXabbXXccXXdd
.FIRST
— the first occurrence of the target sub string found within the target range. TheFIRST 'XX'
found inaXXabbXXccXXdd
would be the one found between the ‘a’ and ‘b’ characters.LEADING
— an occurrence of the target sub string found either at the first character position of the target range or immediately following a previously-found occurrence. There are no occurrences ofLEADING 'XX'
found inaXXabbXXccXXdd
, but there is one occurrence ofLEADING 'a'
(the first character).TRAILING
— an occurrence of the target sub string found either at the very end of the target range or toward the end, followed by nothing but other occurrences. There are no occurrences ofLEADING 'XX'
found inaXXabbXXccXXdd
, but there are two occurrences ofTRAILING 'd'
.The
CHARACTERS
option will match any one single character. When you use this option, the replacement sub string (see the next item) must be exactly one character in length. - A Replacement Sub string — this is the sequence of characters that should replace the target sub string. Replacement sub strings are specified after the
BY
keyword. They too may be specified as a literal, either with or without anALL
prefix (again, figurative constants are allowed) or the value of an identifier. If a figurative constant is coded, theALL
keyword will be assumed, even if it wasn’t specified. Literals withoutALL
will either be truncated or padded with spaces on the right to match the length of the target sub string. Literals withALL
or figurative constants will be repeated as necessary to match the length of the target sub string. Identifiers specified as replacement sub strings must be defined with a length equal to that of the target sub string.
- A target range, specified by the presence of an
- While there will typically be only be a single set of replacement instructions on an
- When both
REPLACING
andTALLYING
are specified:- The
INSPECT
statement will make a single pass through the sequence of characters comprising the inspect subject. As the pointer to the current inspect target character reaches a point where it falls within the explicit or implicit target ranges specified on the operational instructions of the two clauses, the actions specified by those instructions will become eligible to be taken. As the character pointer reaches a point where it falls past the end of target ranges, the instructions belonging to those target ranges will become disabled. - At any point in time, there may well be multiple
REPLACING
and/orTALLYING
operational instructions active. Only one of theTALLYING
and one of theREPLACING
instructions (if any) can be executed for any one character pointer position. In each case, it will be the first of the instructions in each category that produces a match with its target string specification. - When both a
TALLYING
and aREPLACING
instruction have been selected for execution, theTALLYING
instruction will be executed first. This guarantees thatTALLYING
will compute occurrences based upon the initial value of the inspect subject before any replacements occur.
- The
- The following points apply to the use of the
CONVERTING
clause:- A
CONVERTING
clause performs a series of single-character substitutions against a data item in much the same manner as is possible with theTRANSFORM
statement (see TRANSFORM). - Unlike the
TALLYING
andREPLACING
clauses, both of which may have multiple operations specified, there may be only oneCONVERTING
operation perINSPECT
. - If the length of literal-7 or identifier-8 (the “from” string) exceeds the length of literal-8 or identifier-9 (the “to” string), then the “to” string will be assumed to be padded to the right with enough spaces to make it the same length as the “from” string.
- If the length of the “from” string is less than the length of the “to” string, then the “to” string will be truncated to the length of the “from” string.
- Each character, in turn, within the “from” string will be searched for in the target range of the inspect subject. Each located occurrence will be replaced by the corresponding character of the “to” string.
- A
7.8.25. MERGE
MERGE Syntax
MERGE sort-file-1 ~~~~~ { ON { ASCENDING } KEY identifier-1... }... { ~~~~~~~~~ } { DESCENDING } ~~~~~~~~~~ [ WITH DUPLICATES IN ORDER ] ~~~~~~~~~~ [ COLLATING SEQUENCE IS alphabet-name-1 ] ~~~~~~~~~ USING file-name-1 file-name-2... ~~~~~ { OUTPUT PROCEDURE IS procedure-name-1 } { ~~~~~~ ~~~~~~~~~ } { [ THRU|THROUGH procedure-name-2 ] } { ~~~~ ~~~~~~~ } { GIVING file-name-3... } { ~~~~~~ }
The DUPLICATES
clause is syntactically recognized but is otherwise non-functional.
The MERGE
statement merges the contents of two or more files that have each been pre-sorted on a set of specified identical keys.
- The reserved words
IN
,IS
,KEY
,ON
,ORDER
,SEQUENCE
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
THRU
andTHROUGH
are interchangeable. - GnuCOBOL always behaves as if the
WITH DUPLICATES IN ORDER
clause is specified, even if it isn’t.While any COBOL implementation’s sort or merge facilities guarantee that records with duplicate key values will be in proper sequence with regard to other records with different key values, they generally make no promises as to the resulting relative sequence of records having duplicate key values with one another.
Some COBOL implementations provide this optional clause to force their sort and merge facilities to retain duplicate key-value records in their original input sequence, relative to one another.
- The sort-file-1 named on the
MERGE
statement must be defined using a sort description (SD
(see File/Sort-Description)). This file is referred to in the remainder of this discussion as the merge work file. - Each file-name-1, file-name-2 and file-name-3 (if specified) must reference
ORGANIZATION LINE SEQUENTIAL
(see ORGANIZATION LINE SEQUENTIAL) orORGANIZATION SEQUENTIAL
(see ORGANIZATION SEQUENTIAL) files. These files must be defined using a file description (FD
(see File/Sort-Description)). - The identifier-1 … field(s) must be defined as field(s) within a record of sort-file-1.
- The record descriptions of file-name-1, file-name-2, file-name-3 (if any) and sort-file-1 are assumed to be identical in layout and size. While the actual data names used for fields in these files’ records may differ, the structure of records,
PICTURE
(see PICTURE) of fields,USAGE
(see USAGE) of fields, size of fields and location of fields within the records should match field-by-field across all files, at least as far as theKEY
fields are concerned. - A common programming technique when using the
MERGE
statement is to define the records of all files involved as simple elementary items of the form01 record-name PIC X(n).
where n is the record size. The only file where records are actually described in detail would then be sort-file-1. - The following rules apply to the files named on the
USING
clause:- None of them may be open at the time the
MERGE
is executed. - Each of those files is assumed to be already sorted according to the specifications set forth on the
MERGE
statement’sKEY
clause. - No two of those files may be referenced on a
SAME RECORD AREA
(see SAME RECORD AREA),SAME SORT AREA
orSAME SORT-MERGE AREA
statement.
- None of them may be open at the time the
- The merging process is as follows:
- As the
MERGE
statement begins execution, the first record in each of theUSING
files is read automatically. - As the
MERGE
statement executes, the current record from each of theUSING
files is examined and compared to each other according to the rules set forth by theKEY
clause and the alphabet (see Alphabet-Name-Clause) specified on theCOLLATING SEQUENCE
clause. The record that should be next in sequence will be written to the merge work file and theUSING
file from which that record came will be read so that its next record is available. As end-of-file conditions are reached onUSING
files, those files will be excluded from further processing — processing continues with the remaining files until all the contents of all of them have been exhausted. - After the merge work file has been populated, the merged data will be written to each file-name-3 if the
GIVING
clause was specified, or will be processed by utilizing anOUTPUT PROCEDURE
. - When
GIVING
is specified, none of the file-name-3 files can be open at the time theMERGE
statement is executed. - When an output procedure is used, the procedure(s) specified on the
OUTPUT PROCEDURE
clause will be invoked as if by a proceduralPERFORM
(see Procedural PERFORM) statement with noVARYING
,TIMES
orUNTIL
options specified. Merged records may be read from the merge work file — one at a time — within the output procedure using theRETURN
(see RETURN) statement.A
GO TO
statement (see GO TO) that transfers control out of the output procedure will terminate theMERGE
statement but allows the program to continue executing from the point where theGO TO
statement transferred control to. Once an output procedure has been “aborted” using aGO TO
it cannot be resumed, and the contents of the merge work file are lost. You may, however, re-execute theMERGE
statement itself. Using aGO TO
statement to prematurely terminate a merge, or re-starting a previously-cancelled merge is not considered good programming style and should be avoided.An output procedure should be terminated in the same way a procedural
PERFORM
statement would be. Usually, this action will be taken once theRETURN
statement indicates that all records in the merge work file have been processed, but termination could occur at any time — via anEXIT
statement (see EXIT) — if required.Neither a file-based
SORT
statement (see File-Based SORT) nor anotherMERGE
statement may be executed within the scope of the procedures comprising the output procedure unless those statements utilize a different sort or merge work file. - Once the output procedure terminates, or the last file-name-3 file has been populated with merged data, the output phase — and the
MERGE
statement itself — is complete.
- As the
7.8.26. MOVE
7.8.26.1. Simple MOVE
Simple MOVE Syntax
MOVE { literal-1 } TO identifier-2... ~~~~ { identifier-1 } ~~
The Simple MOVE
statement moves a specific value to one or more receiving data items.
- The
MOVE
statement will replace the contents of one or more receiving data items (identifier-2) with a new value — the one specified by literal-1 or identifier-1. - Only numeric data can be moved to a numeric or numeric-edited identifier-2. A
MOVE
involving numeric data will perform any necessary format conversions that might be necessary due to differingUSAGE
(see USAGE) specifications. - The contents of the identifier-1 data item will not be changed, unless that same data item appears as an identifier-2. Note that such situations will cause a warning message to be issued by the compiler, if warning messages are enabled.
7.8.26.2. MOVE CORRESPONDING
MOVE CORRESPONDING Syntax
MOVE CORRESPONDING identifier-1 TO identifier-2... ~~~~ ~~~~ ~~
The MOVE CORRESPONDING
statement similarly-named items from one group item to another.
- The reserved word
CORRESPONDING
may be abbreviated asCORR
. - Both identifier-1 and identifier-2 must be group items.
- See CORRESPONDING, for a discussion of how corresponding matches between two group items are established.
- When corresponding matches are established, the effect of a
MOVE CORRESPONDING
on those matches will be as if a series of individualMOVE
s were done — one for each match.
7.8.27. MULTIPLY
7.8.27.1. MULTIPLY BY
MULTIPLY BY Syntax
MULTIPLY { literal-1 } BY { identifier-2 ~~~~~~~~ { identifier-1 } ~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-MULTIPLY ] ~~~~~~~~~~~~
The MULTIPLY BY
statement computes the product of one or more data items (identifier-2) and either a numeric literal or another data item.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric un-edited data items; literal-1 must be a numeric literal.
- The product of identifier-1 or literal-1 and each identifier-2, in turn, will be computed and moved to each of the identifier-2 data items, replacing the prior contents.
- The value of identifier-1 is not altered, unless that same data item appears as an identifier-2.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.27.2. MULTIPLY GIVING
MULTIPLY GIVING Syntax
MULTIPLY { literal-1 } BY { literal-2 } GIVING { identifier-3 ~~~~~~~~ { identifier-1 } ~~ { identifier-2 } ~~~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-MULTIPLY ] ~~~~~~~~~~~~
The MULTIPLY GIVING
statement computes the product of two literals and/or data items and saves that result in one or more other data items.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric un-edited data items; literal-1 and literal-2 must be numeric literals.
- The product of identifier-1 or literal-1 and identifier-2 or literal-2 will be computed and moved to each of the identifier-3 data items, replacing their old contents.
- Neither the value of identifier-1 nor identifier-2 will be altered, unless either appears as an identifier-3.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.28. OPEN
OPEN Syntax
OPEN { { INPUT } [ SHARING WITH { ALL OTHER } ] file-name-1 ~~~~ { ~~~~~ } ~~~~~~~ { ~~~ } { OUTPUT } { NO OTHER } { ~~~~~~ } { ~~ } { I-O } { READ ONLY } { ~~~ } ~~~~ ~~~~ { EXTEND } ~~~~~~ [ { REVERSED } ] }... { ~~~~~~~~ } { WITH { NO REWIND } } { { ~~ ~~~~~~ } } { { LOCK } } ~~~~
The NO REWIND
, and REVERSED
clauses are syntactically recognized but are otherwise non-functional.
The OPEN
statement makes one or more files described in your program available for use.
- The reserved words
OTHER
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The
SHARING
andWITH LOCK
clauses may not both be specified in the sameOPEN
statement. - Any file defined in a GnuCOBOL program must be successfully opened before it or any of its record descriptions may be referenced on:
A
CLOSE
statement (see CLOSE)A
DELETE
statement (see DELETE)A
READ
statement (see READ)A
REWRITE
statement (see REWRITE)A
START
statement (see START)An
UNLOCK
statement (see UNLOCK)A
WRITE
statement (see WRITE) - Any attempt to open a file that is already open will fail with a file status of 41 (see File Status Codes).
- Any open failure (including status 41) may be trapped using
DECLARATIVES
(see DECLARATIVES) or an error procedure established using theCBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine or even just checking the status field defined. It is up to the programmer to check for bad statuses and respond accordingly such as issue a CLOSE before dealing with the problem. - The
INPUT
,OUTPUT
,I-O
andEXTEND
open modes inform GnuCOBOL of the manner in which you wish to use the file, as follows:INPUT
-
You may only read the existing contents of the file — only the
CLOSE
,READ
,START
andUNLOCK
statements will be allowed. This enforcement takes place at execution time, not compilation time. OUTPUT
-
You may only write new content (which will completely replace any previous file contents) to the file — only the
CLOSE
,UNLOCK
andWRITE
statements will be allowed. This enforcement takes place at execution time, not compilation time. I-O
-
You may perform any operation you wish against the file — all file I/O statements will be allowed.
EXTEND
You may only write new content (which will be appended after the previously existing file contents) to the file — only the
CLOSE
,UNLOCK
andWRITE
statements will be allowed. This enforcement takes place at execution time, not compilation time. You cannot extend an empty file; this will not generate a runtime error, but no output will appear in the file.
- The
SHARING
clause informs the GnuCOBOL file runtime modules how you are willing to co-exist with any other GnuCOBOL programs that may attempt to open the same file after your program does. See File Sharing, for an explanation of theSHARING
clause. - The
WITH LOCK
option will be functional only if your GnuCOBOL build can support it. GnuCOBOL built for MinGW or native Windows will not, because the Unixfcntl
primitive doesn’t exist in those environments. GnuCOBOL built for Cygwin or Unix will.
7.8.29. PERFORM
7.8.29.1. Procedural PERFORM
Procedural PERFORM Syntax
PERFORM procedure-name-1 [ THRU|THROUGH procedure-name-2 ] ~~~~~~~ ~~~~ ~~~~~~~ [ { [ WITH TEST { BEFORE } ] { VARYING-Clause } } ] { ~~~~ { ~~~~~~ } { UNTIL conditional-expression-1 } } { { AFTER } ~~~~~ } { ~~~~~ } { UNTIL EXIT|FOREVER } { ~~~~~ ~~~~ ~~~~~~~ } { { literal-1 } TIMES } { { identifier-1 } ~~~~~ }
This format of the PERFORM
statement is used to transfer control to one or more procedures, which will return control back when complete. Execution of the procedure(s) can be done a single time, multiple times, repeatedly until a condition becomes TRUE
or forever (with some way of breaking out of the control of the PERFORM
or of halting program execution within the procedure(s)).
- The reserved word
WITH
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The reserved words
THRU
andTHROUGH
are interchangeable. - The reserved word and phrase
FOREVER
andUNTIL EXIT
are interchangeable. - Both procedure-name-1 and procedure-name-2 must be procedure division sections or paragraphs defined in the same program as the
PERFORM
statement. If procedure-name-2 is specified, it must follow procedure-name-1 in the program’s source code. - The perform scope is defined as being the statements within procedure-name-1, the statements within procedure-name-2 and all statements in all procedures defined between them.
- literal-1 must be a numeric literal or a reference to a function that returns a numeric value. The value must be an integer greater than zero.
- identifier-1 must be an elementary un-edited numeric data item with an integer value greater than zero.
- Without the
UNTIL
,UNTIL EXIT
,TIMES
, VARYING-Clause (see VARYING) orFOREVER
clauses, the code within the perform scope will be executed once, after which control will return to the statement following thePERFORM
. - The
FOREVER
option will repeatedly execute the code within the perform scope with no conditions defined for termination of the repetition — it will be up to the programmer to include anEXIT SECTION
statement (see EXIT) orEXIT PARAGRAPH
statement within the procedure(s) being performed that will break out of the loop. - The
TIMES
option will repeat the execution of the code within the perform scope a fixed number of times. When thePERFORM
statement begins execution, an internal repeat counter (not accessible to the programmer) will be set to the value of literal-1 or the value within identifier-1.If the counter has a value greater than zero, the statement(s) within the
PERFORM
scope will be executed, after which the counter will be decremented by 1 with each repetition. Once that counter reaches zero, repetition will cease and control will fall into the next statement following thePERFORM
.If the identifier-1 option was used, altering the value of that data item within the perform scope will not affect the repetition count.
- The
UNTIL conditional-expression-1
option will repeat the code within the perform scope until the specified conditional expression evaluates to aTRUE
value. - The optional
WITH TEST
clause will control whetherUNTIL
testing occursBEFORE
the statements within the perform scope are executed on each iteration (creating the possibility — if conditional-expression-1 is initiallyTRUE
— that the statements within the perform scope will never be executed) orAFTER
(guaranteeing the statements within the perform scope will be executed at least once).The default, if this clause is absent, is
WITH TEST BEFORE
.This clause may not be coded when the
TIMES
clause is used. - The optional
VARYING-Clause
is a mechanism that creates an advanced loop-management mechanism complete with one or more numeric data items being automatically incremented (or decremented) on each loop iteration as well as the termination control of anUNTIL
clause. See VARYING, for the details.
7.8.29.2. Inline PERFORM
Inline PERFORM Syntax
PERFORM ~~~~~~~ [ { [ WITH TEST { BEFORE } ] { VARYING-Clause } } ] { ~~~~ { ~~~~~~ } { UNTIL conditional-expression-1 } } { { AFTER } ~~~~~ } { ~~~~~ } { UNTIL EXIT|FOREVER } { ~~~~~ ~~~~ ~~~~~~~ } { { literal-1 } TIMES } { { identifier-1 } ~~~~~ } imperative-statement-1 [ END-PERFORM ] ~~~~~~~~~~~
This format of the PERFORM
statement is identical in operation to the procedural PERFORM
, except for the fact that the statement(s) comprising the perform scope (imperative-statement-1) (see Imperative Statement) are now specified in-line with the PERFORM
code rather than in procedures located elsewhere within the program.
7.8.29.3. VARYING
VARYING Syntax
VARYING identifier-2 FROM { literal-2 } [ BY { literal-3 } ] ~~~~~~~ ~~~~ { identifier-3 } ~~ { identifier-4 } [ UNTIL conditional-expression-1 ] ~~~~~ [ AFTER identifier-5 FROM { literal-4 } [ BY { literal-5 } ] ~~~~~ ~~~~ { identifier-6 } ~~ { identifier-7 } [ UNTIL conditional-expression-2 ] ]... ~~~~~
The VARYING
clause, available on both formats of the PERFORM
statement, is a looping mechanism that allows for the specification of one or more numeric data items that will be initialized to a programmer-specified value and automatically incremented by another programmer-specified value after each loop iteration.
- All identifiers used in a VARYING-Clause must be elementary, un-edited numeric data items. All literals must be numeric literals.
- The following points describe the sequence of events that take place as a result of the
VARYING
portion of the clause:- When the
PERFORM
begins execution, theFROM
value will be moved to identifier. - If the
PERFORM
specifies or impliesWITH TEST BEFORE
, conditional-expression-1 will be evaluated and processing of thePERFORM
will halt if the expression evaluates toTRUE
. IfWITH TEST BEFORE
was not specified or implied, or if the conditional expression evaluated toFALSE
, processing proceeds with step C. - The statements within the perform scope will be executed. If a
GO TO
executed within the perform scope transfers control to a point outside the perform scope, processing of thePERFORM
will halt. - When the statements within the perform scope terminate the loop iteration, by one of:
- allowing the flow of execution to attempt to fall past the last statement in the perform scope
- executing an
EXIT PERFORM CYCLE
statement (see EXIT) - executing an
EXIT PARAGRAPH
statement orEXIT SECTION
statement when there is only one paragraph (or section) in the perform scope ( this option only applies to a proceduralPERFORM
)
If
WITH TEST AFTER
was specified, control will return back to thePERFORM
, where conditional-expression-1 will be evaluated, and processing of thePERFORM
will halt if the expression evaluates toTRUE
. IfWITH TEST AFTER
was not specified, or if the conditional expression evaluated toFALSE
, processing continues with the next step. - The
BY
value, if any, will be added to identifier-2. If noBY
is specified, it will be treated as ifBY 1
had been specified. - Return to step C.
- When the
- Most
VARYING-Clause
s have noAFTER
specified. Those that do, however, are establishing a loop-within-a-loop situation where the process described above in steps (‘A’) through (‘F’) will take place from theAFTER
, and those six processing steps actually replace step C of theVARYING
. This “nesting” process can continue indefinitely, with each additionalAFTER
.
An example should really help you see this at work. Observe the following code which defines a two-dimensional (3 row by 4 column) table and a pair of numeric data items to be used to subscript references to each element of the table:
01 PERFORM-DEMO. 05 PD-ROW OCCURS 3 TIMES. 10 PD-COL OCCURS 4 TIMES 15 PD PIC X(1). 01 PD-Col-No PIC 9 COMP. 01 PD-Row-No PIC 9 COMP.
Let’s say the 3x4 “grid” defined by the above structure has these values:
A B C D E F G H I J K L
This code will display ABCDEFGHIJKL
on the console output window:
PERFORM WITH TEST AFTER VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3 AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4 DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING END-PERFORM
While this code will display AEIBFJCGKDHL
on the console output window:
PERFORM WITH TEST AFTER VARYING PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4 AFTER PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3 DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING END-PERFORM
While we’re looking at sample code, this code displays ABCEFG
:
PERFORM VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3 AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4 DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING END-PERFORM
By removing the WITH TEST
clause, the statement is now assuming WITH TEST BEFORE
. Since testing now happens before the DISPLAY
statement gets executed, when PD-Row-No is 3 and PD-Col-No is 4 the DISPLAY
statement won’t be executed.
Most COBOL programmers, when using WITH TEST BEFORE
explicitly or implicitly have developed the habit of using ‘>’ rather than ‘=’ on UNTIL
clauses. This would make the sample code:
PERFORM VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No > 3 AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No > 4 DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING END-PERFORM
With this change, ABCDEFGHIJKL
is once again displayed.
7.8.30. READ
7.8.30.1. Sequential READ
Sequential READ Syntax
READ file-name-1 [ { NEXT|PREVIOUS } ] RECORD [ INTO identifier-1 ] ~~~~ { ~~~~ ~~~~~~~~ } ~~~~ [ { IGNORING LOCK } ] { ~~~~~~~~ ~~~~ } { WITH [ NO ] LOCK } { ~~ ~~~~ } { WITH KEPT LOCK } { ~~~~ ~~~~ } { WITH IGNORE LOCK } { ~~~~~~ ~~~~ } { WITH WAIT } ~~~~ [ AT END imperative-statement-1 ] ~~~ [ NOT AT END imperative-statement-2 ] ~~~ ~~~ [ END-READ ] ~~~~~~~~
This form of the READ
statement retrieves the next (or previous) record from a file.
- The reserved words
AT
,RECORD
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The file-name-1 file must have been defined via an
FD
(see File/Sort-Description), not anSD
. - The file-name-1 file must currently be open for
INPUT
(see File OPEN Modes) orI-O
. - If file-name-1 is an
ORGANIZATION RELATIVE
(see ORGANIZATION RELATIVE) orORGANIZATION INDEXED
(see ORGANIZATION INDEXED) file with anACCESS MODE RANDOM
, this statement cannot be used. - If file-name-1 was specified as
ACCESS MODE SEQUENTIAL
, this is the only format of theREAD
statement that is available. - If file-name-1 is an
ORGANIZATION RELATIVE
(see ORGANIZATION RELATIVE) orORGANIZATION INDEXED
(see ORGANIZATION INDEXED) file withACCESS MODE DYNAMIC
, this statement as well as a randomREAD
(see Random READ) may be used. - The keywords
NEXT
andPREVIOUS
specify what “direction of travel” the reading process will take through the file. If neither is specified,NEXT
is assumed. - The
PREVIOUS
option is available only forORGANIZATION INDEXED
files. - When reading any sequential (any organization) or relative file, the “next” direction refers to the physical sequence of records in the file. When reading an indexed file, the “next” and “previous” directions refer to the sequence of primary or alternate record key values in the file’s records, regardless of where the records physically occur within the file.
- The minimal statement
READ file-name-1
is perfectly legal according to both READ formats. For that reason, whenACCESS MODE DYNAMIC
has been specified and you want to tell the GnuCOBOL compiler that this minimal statement should be treated as a sequentialREAD
, you must add eitherNEXT
orPREVIOUS
to the statement (otherwise it will be treated as a randomREAD
). - A successful sequential READ will retrieve the next available record from file-name-1, in either a “next” or “previous” direction from the most-recently-read record, depending upon the use of the
NEXT
orPREVIOUS
option. The newly-retrieved record data will be saved into the 01-level record structure(s) that immediately follow the file’sFD
. If the optionalINTO
clause is present, a copy of the just-retrieved record will be automatically moved to identifier-1. - When an
ORGANIZATION RELATIVE
file has been successfully read, the file’sRELATIVE KEY
(see ORGANIZATION RELATIVE) field will be automatically populated with the relative record number (ordinal occurrence number) of the record in the file. - The optional
LOCK
options may be used to manually control access to the retrieved record by other programs while this program is running. See Record Locking, to review the various record locking behaviours. - The optional
AT END
clause, if coded, is used to detect and react to the failure of an attempt to retrieve another record from the file due to an end-of-file (i.e. no more records) condition. - The optional
NOT AT END
clause, if coded, will check for a file status value of 00. See File Status Codes, for additional information.
7.8.30.2. Random READ
Random READ Syntax
READ file-name-1 RECORD [ INTO identifier-1 ] ~~~~ ~~~~ [ { IGNORING LOCK } ] { ~~~~~~~~ ~~~~ } { WITH [ NO ] LOCK } { ~~ ~~~~ } { WITH KEPT LOCK } { ~~~~ ~~~~ } { WITH IGNORE LOCK } { ~~~~~~ ~~~~ } { WITH WAIT } ~~~~ [ KEY IS identifier-2 ] ~~~ [ INVALID KEY imperative-statement-1 ] ~~~~~~~ [ NOT INVALID KEY imperative-statement-2 ] ~~~ ~~~~~~~ [ END-READ ] ~~~~~~~~
This form of the READ
statement retrieves an arbitrary record from an ORGANIZATION RELATIVE
(see ORGANIZATION RELATIVE) or ORGANIZATION INDEXED
(see ORGANIZATION INDEXED) file.
- The reserved words
IS
,KEY
(on theINVALID
andNOT INVALID
clauses),RECORD
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The file-name-1 file must have been defined via an
FD
(see File/Sort-Description), not anSD
. - The file-name-1 file must currently be open for
INPUT
(see File OPEN Modes) orI-O
. - If the
ACCESS MODE
of file-name-1 isSEQUENTIAL
, or theORGANIZATION
of the file is any form of sequential, this format of theREAD
statement cannot be used. - If the
ACCESS MODE
of file-name-1 isRANDOM
, this is the only format of theREAD
statement that is available. - If file-name-1 is an
ORGANIZATION RELATIVE
(see ORGANIZATION RELATIVE) orORGANIZATION INDEXED
(see ORGANIZATION INDEXED) file withACCESS MODE DYNAMIC
, this statement as well as a sequentialREAD
(see Sequential READ) may be used. - The minimal statement
READ file-name-1
is perfectly legal according to both READ formats. For that reason, whenACCESS MODE DYNAMIC
has been specified and you want to tell the GnuCOBOL compiler that this minimal statement should be treated as a randomREAD
, you must omit theNEXT
orPREVIOUS
available to the sequential format of theREAD
statement to ensure the statement will be treated as a randomREAD
. - The optional
KEY
clause tells the compiler how a record is to be located in the file.If the
KEY
clause is absent, and the file isORGANIZATION RELATIVE
-
the contents of the field declared as the file’s
RELATIVE KEY
will be used to identify a record ORGANIZATION INDEXED
the contents of the field declared as the file’s
RECORD KEY
will be used to identify a record.
If the
KEY
clause is specified, and the file isORGANIZATION RELATIVE
-
the contents of identifier-2 will be used as the relative record number of the record to be accessed. identifier-2 need not be the
RELATIVE KEY
(see ORGANIZATION RELATIVE) field of the file (although it could be if you wish). ORGANIZATION INDEXED
identifier-2 must be the
RECORD KEY
(see ORGANIZATION INDEXED) or one of the file’sALTERNATE RECORD KEY
fields (if any). The current contents of that field will identify the record to be accessed. If an alternate record key is used, and that key allows duplicate values, the record accessed will be the first one having that key value.
- Once read from the file, the newly-retrieved record data will be saved into the 01-level record structure(s) that immediately follow the file’s
FD
. If the optionalINTO
clause is present, a copy of the just-retrieved record will be automatically moved to identifier-1. - When an
ORGANIZATION RELATIVE
file has been successfully read, the file’sRELATIVE KEY
(see ORGANIZATION RELATIVE) field will be automatically populated with the relative record number (ordinal occurrence number) of the record in the file. - The optional
LOCK
options may be used to manually control access to the retrieved record by other programs while this program is running. See Record Locking, to review the various record locking behaviours. - The optional
INVALID KEY
andNOT INVALID KEY
clauses may be used to detect and react to the failure or success, respectively, by detecting non-zero (typically 23 = key not found = record not found) and 00 file status codes, respectively. See File Status Codes, for additional information.
7.8.31. READY TRACE
READY TRACE Syntax
READY TRACE ~~~~~ ~~~~~
The READY TRACE
statement turns procedure or procedure-and-statement tracing on.
- In order for this statement to be functional, tracing code must have been generated into the compiled program using either the -ftrace switch (procedures only) or -ftraceall switch (procedures and statements).
- Tracing may be turned off at any point by executing the
RESET TRACE
statement (see RESET TRACE). - The
COB_SET_TRACE
run-time environment variable (see Run Time Environment Variables) provides another way to control tracing. If this environment variable is set to a value of ‘Y’ prior to the start of program execution, tracing starts at the point the program begins execution, as ifREADY TRACE
were the first executed statement.
7.8.32. RELEASE
RELEASE Syntax
RELEASE record-name-1 [ FROM { literal-1 } ] ~~~~~~~ ~~~~ { identifier-1 }
The RELEASE
statement adds a new record to a sort work file.
- This statement is valid only within the
INPUT PROCEDURE
of a file-basedSORT
statement (see File-Based SORT). - The specified record-name-1 must be a record defined to the sort description (
SD
(see File/Sort-Description)) of the sort work file being processed by the current sort. - The optional
FROM
clause will cause literal-1 or identifier-1 to be automatically moved into record-name-1 prior to writing record-name-1’s contents to the file-name-1. If this clause is not specified, it is the programmer’s responsibility to populate record-name-1 with the desired data prior to executing theRELEASE
.
7.8.33. RESET TRACE
RESET TRACE Syntax
RESET TRACE ~~~~~ ~~~~~
The RESET TRACE
statement turns procedure or procedure-and-statement tracing off.
- By default, procedure and procedure-and-statement tracing is off as programs begin execution. The
READY TRACE
statement (see READY TRACE) can be used to turn tracing on. - In order for this statement to be functional, tracing code must have been generated into the compiled program using either the -ftrace switch (procedures only) or -ftraceall switch (procedures and statements).
- The
COB_SET_TRACE
run-time environment variable (see Run Time Environment Variables) provides another way to control tracing. If this environment variable is set to a value of ‘Y’ prior to the start of program execution, tracing started at the point the program begins execution, as ifREADY TRACE
were the first executed statement. TheRESET TRACE
statement, if executed, will then turn off tracing.
7.8.34. RETURN
RETURN Syntax
RETURN sort-file-name-1 RECORD ~~~~~~ [ INTO identifier-1 ] ~~~~ AT END imperative-statement-1 ~~~ [ NOT AT END imperative-statement-2 ] ~~~ ~~~ [ END-RETURN ] ~~~~~~~~~~
The RETURN
statement reads a record from a sort or merge work file.
- The reserved words
AT
andRECORD
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The
RETURN
statement is valid only within theOUTPUT PROCEDURE
of a file-basedSORT
(see File-Based SORT) or aMERGE
statement (see MERGE) statement. - The sort-file-name-1 file must be a sort- or merge work file defined with a
SD
(see File/Sort-Description), not anFD
. - A successful
RETURN
will retrieve the next available record from sort-file-name-1. The newly-retrieved record data will be saved into the 01-level record structure(s) that immediately follow the file’s SD. If the optionalINTO
clause is present, a copy of the just-retrieved record will be automatically moved to identifier-1. - The mandatory
AT END
clause is used to detect and react to the failure of an attempt to retrieve another record from the file due to an end-of-file (i.e. no more records) condition. - The optional
NOT AT END
clause, if coded, will check checking for a file status value of 00. See File Status Codes, for additional information.
7.8.35. REWRITE
REWRITE Syntax
REWRITE record-name-1 ~~~~~~~ [ FROM { literal-1 } ] ~~~~ { identifier-1 } [ WITH [ NO ] LOCK ] ~~ ~~~~ [ INVALID KEY imperative-statement-1 ] ~~~~~~~ [ NOT INVALID KEY imperative-statement-2 ] ~~~ ~~~~~~~ [ END-REWRITE ] ~~~~~~~~~~~
The REWRITE
statement replaces a logical record on a disk file.
- The reserved words
KEY
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The record-name-1 specified on the statement must be defined as an 01-level record subordinate to the File Description (
FD
(see File/Sort-Description)) of a file that is currently open forI-O
(see File OPEN Modes). - The optional
FROM
clause will cause literal-1 or identifier-1 to be automatically moved into record-name-1 prior to writing record-name-1’s contents to the file-name-1. If this clause is not specified, it is the programmer’s responsibility to populate record-name-1 with the desired data prior to executing theREWRITE
. - This statement may not be used with
ORGANIZATION LINE SEQUENTIAL
(see ORGANIZATION LINE SEQUENTIAL) files. - Rewriting a record does not cause the contents of the file to be physically updated until the next block of the file is read, a
COMMIT
(see COMMIT) orUNLOCK
statement (see UNLOCK) is issued or that file is closed. - If the file has
ORGANIZATION SEQUENTIAL
(see ORGANIZATION SEQUENTIAL):- The record to be rewritten will be the one retrieved by the most-recently executed
READ
(see READ) of the file. - If the
FD
of the file contains theRECORD CONTAINS
orRECORD IS VARYING
clause, and that clause allows the record size to vary, the size of record-name-1 cannot be altered.
- The record to be rewritten will be the one retrieved by the most-recently executed
- If the file has
ORGANIZATION RELATIVE
(see ORGANIZATION RELATIVE) orORGANIZATION INDEXED
(see ORGANIZATION INDEXED):- If the file has
ACCESS MODE SEQUENTIAL
, the record to be rewritten will be the one retrieved by the most-recently executedREAD
of the file. If the file hasACCESS MODE RANDOM
orACCESS MODE DYNAMIC
, noREAD
is required before a record may be rewritten — theRELATIVE KEY
orRECORD KEY
definition for the file, respectively, will specify the record to be updated. - If the
FD
of the file contains theRECORD CONTAINS
orRECORD IS VARYING
clause, and that clause allows the record size to vary, the size can be altered.
- If the file has
- The optional
LOCK
options may be used to manually control access to the re-written record by other programs while this program is running. See Record Locking, to review the various record locking behaviours. - The optional
INVALID KEY
andNOT INVALID KEY
clauses may be used to detect and react to the failure or success, respectively, by detecting non-zero (typically 23 = key not found = record not found) and 00 file status codes, respectively. See File Status Codes, for additional information.
7.8.36. ROLLBACK
ROLLBACK Syntax
ROLLBACK ~~~~~~~~
The ROLLBACK
statement has the same effect as if an UNLOCK
statement (see UNLOCK) were executed against every open file in the program.
- All locks currently being held for all open files will be released.
- See Record Locking, to review the various record locking behaviours.
7.8.37. SEARCH
SEARCH Syntax
SEARCH table-name-1 ~~~~~~ [ VARYING index-name-1 ] ~~~~~~~ [ AT END imperative-statement-1 ] ~~~ { WHEN conditional-expression-1 imperative-statement-2 }... ~~~~ [ END-SEARCH ] ~~~~~~~~~~
The SEARCH
statement is used to sequentially search a table, stopping either once a specific value is located within the table or when the table has been completely searched.
- The reserved word
AT
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - The searching process will be controlled through a Search Index — a data item with a
USAGE
(see USAGE) ofINDEX
. The search index is either the index-name-1 identifier specified on theVARYING
clause or — if noVARYING
is specified — theUSAGE INDEX
data item implicitly created by anINDEXED BY
(see OCCURS) clause in the table’s definition. - At the time the
SEARCH
statement is executed, the current value of the search index data item will define the starting position in the table where the searching process will begin. Typically, one initializes that index to a value of 1 before starting theSEARCH
viaSET search-index TO 1
. - Each of the conditional-expression-ns on the
WHEN
clause(s) should involve a data element within the table, subscripted using the search index. - The searching process is as follows:
- Each conditional-expression-n will be evaluated, in turn, until either one evaluates to a value of
TRUE
or all have evaluated toFALSE
. - The imperative-statement-n (see Imperative Statement) specified on the
WHEN
clause whose conditional-expression-n evaluated toTRUE
will be executed; after that, the search will be considered complete and control will fall into the first executable statement following theSEARCH
. - If all conditional-expression-ns evaluated to FALSE:
- The search index will be incremented by 1
- If the search index now has a value greater than the number of entries in the table, the search is considered to have failed and the imperative-statement-1 on the optional
AT END
clause, if any, will be executed. After that, control will fall into the first executable statement following theSEARCH
. - If the search index now has a value less than or equal to the number of entries in the table, search processing returns back to step A.
- Each conditional-expression-n will be evaluated, in turn, until either one evaluates to a value of
7.8.38. SEARCH ALL
SEARCH ALL Syntax
SEARCH ALL table-name-1 ~~~~~~ ~~~ [ AT END imperative-statement-1 ] ~~~ WHEN conditional-expression-1 imperative-statement-2 ~~~~ [ END-SEARCH ] ~~~~~~~~~~
The SEARCH ALL
statement performs a binary, or half-interval, search against a sorted table. This is generally significantly faster than performing a sequential SEARCH
of a table, especially if the table contains a large number of entries.
- The reserved word
AT
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - To be eligible for searching via
SEARCH ALL
:- The
OCCURS
clause of table-name-1 must contain the following elements:- An
INDEXED BY
entry to define an implicit search index data item with aUSAGE
(see USAGE) ofINDEX
. - An
ASCENDING KEY
orDESCENDING KEY
clause to specify the field within the table by which all entries in the table are sorted.
- An
- Just because the table has one or more
KEY
clauses doesn’t mean the data is actually in that sequence in the table — the actual sequence of the data must agree with the KEY clause(s)! A table-basedSORT
(see Table SORT) can prove very useful in this regard. - No two records in the table may have the same
KEY
field values. If the table has multipleKEY
definitions, then no two records in the table may have the same combination ofKEY
field values.
- The
- If rule A is violated, the compiler will reject the
SEARCH ALL
. If rules B and/or C are violated, there will be no message issued by the compiler, but the run-time results of aSEARCH ALL
against the table will probably be incorrect. - The conditional-expression-1 should involve the
KEY
field(s), using the search index (the table’sINDEXED BY
index name) as a subscript. - The function of the single, mandatory,
WHEN
clause is to compare the key field(s) of the table, as indexed by the search index data item, against whatever literal and/or identifier values you are comparing the key field(s) to in the conditional-expression-1 in order to locate the desired entry in the table. The search index will be automatically varied in a manner designed to require the minimum number of tests. - The internal processing of the SEARCH ALL statement begins by setting internal “first” and “last” pointers to the 1st and last entry locations of the table. Processing then proceeds as follows:
- The entry half-way between “first” and “last” is identified. We’ll call this the “current” entry, and will set its table entry location into index-name-1.
- The conditional-expression-1 is evaluated. This comparison of the key(s) against the target literal/identifier values will have one of three possible outcomes:
- If the key(s) and value(s) match, imperative-statement-2 (see Imperative Statement) is executed, after which control falls through into the next statement following the
SEARCH ALL
. - If the key(s) are LESS THAN the value(s), then the table entry being searched for can only occur in the “current” to “last” range of the table, so a new “first” pointer value is set (it will be set to the “current” pointer).
- If the key(s) are GREATER THAN the value(s), then the table entry being searched for can only occur in the “first” to “current” range of the table, so a new “last” pointer value is set (it will be set to the “current” pointer).
- If the key(s) and value(s) match, imperative-statement-2 (see Imperative Statement) is executed, after which control falls through into the next statement following the
- If the new “first” and “last” pointers are different than the old “first” and “last” pointers, there’s more left to be searched, so return to step A and continue.
- If the new “first” and “last” pointers are the same as the old “first” and “last” pointers, the table has been exhausted and the entry being searched for cannot be found; imperative-statement-1 is executed, after which control falls through into the next statement following the
SEARCH ALL
. If there is noAT END
clause coded, control simply falls into the next statement following theSEARCH ALL
.
- The net effect of the above algorithm is that only a fraction of the number of elements in the table need ever be tested in order to decide whether or not a particular entry exists. This is because the half the remaining entries in the table are discarded each time an entry is checked.
- Computer scientists will compare the two techniques implemented by the
SEARCH
andSEARCH ALL
statements as follows: - When searching a table with N entries, a sequential search will need an average of N/2 tests and a worst case of N tests in order to find an entry and N tests to identify that an entry doesn’t exist.
- When searching a table with N entries, a binary search will need a worst-case of log2(N) tests in order to find an entry and log2(N) tests to identify that an entry doesn’t exist (N = the number of entries in the table), where log2 is the base-2 logarithm function.
Here’s a more practical view of the difference. Let’s say that a table has 1,000 entries in it. With a sequential search, on average, you’ll have to check 500 of them to find an entry and you’ll have to look at all 1,000 of them to find that an entry doesn’t exist.
With a binary search, express the number of entries as a binary number (1,000 = 1111101000), count the number of digits in the result (which is, essentially, what a logarithm is, when rounded up to the next integer — the number of digits a decimal number would have if expressed in the logarithm’s number base). In this case, we end up with 10 — that is the worst-case number of tests required to find an entry or to identify that it doesn’t exist. That’s quite an improvement!
7.8.39. SET
7.8.39.1. SET ENVIRONMENT
SET ENVIRONMENT Syntax
SET ENVIRONMENT { literal-1 } TO { literal-2 } ~~~ ~~~~~~~~~~~ { identifier-1 } ~~ { identifier-2 }
The SET ENVIRONMENT
statement provides a straight-forward means of setting environment values from within a program.
- The value of literal-1 or identifier-1 specifies the name of the environment variable to set.
- The value of literal-2 or identifier-2 specifies the value to be assigned to the environment variable.
- Environment variables created or changed from within GnuCOBOL programs will be available to any sub-shell processes spawned by that program (i.e.
CALL "SYSTEM"
) but will not be known to the shell or console window that started the GnuCOBOL program.
This is a much simpler and more readable means of setting environment variables than by using the DISPLAY UPON ENVIRONMENT-NAME
statement (see DISPLAY UPON ENVIRONMENT-NAME). For example, these two code sequences produce identical results:
DISPLAY "VARNAME" UPON ENVIRONMENT-NAME DISPLAY "VALUE" UPON ENVIRONMENT-VALUE SET ENVIRONMENT "VARNAME" TO "VALUE"
7.8.39.2. SET Program-Pointer
SET Program-Pointer Syntax
SET program-pointer-1 TO ENTRY { literal-1 } ~~~ ~~ ~~~~~ { identifier-1 }
The SET Program-Pointer
statement allows you to retrieve the address of a procedure division code module — specifically the PROGRAM-ID
, FUNCTION-ID
or an entry-point established via the ENTRY
statement (see ENTRY).
- The
USAGE
(see USAGE) of program-pointer-1 must bePROGRAM-POINTER
. - The literal-1 or identifier-1 value specified must name a primary entry-point name (
PROGRAM-ID
of a subroutine orFUNCTION-ID
of a user-defined function) or an alternate entry-point defined via anENTRY
statement within a subprogram. - Once the address of a procedure division code area has been acquired in this way, the address could be passed to a subroutine (usually written in C) for whatever use it needs it for. For examples of
PROGRAM-POINTER
s at work, see the discussions of theCBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) andCBL_EXIT_PROC
built-in system subroutine (see CBL_EXIT_PROC).
7.8.39.3. SET ADDRESS
SET ADDRESS Syntax
SET [ ADDRESS OF ] { pointer-name-1 }... ~~~ ~~~~~~~ ~~ { identifier-1 } TO [ ADDRESS OF ] { pointer-name-2 } ~~ ~~~~~~~ ~~ { identifier-2 }
The SET ADDRESS
statement can be used to work with the addresses of data items rather than their contents.
- When the
ADDRESS OF
clause is used before theTO
you will be using this statement to alter the address of a linkage section orBASED
(see BASED) data item. Without that clause you will be assigning an address to one or more data items whoseUSAGE
(see USAGE) isPOINTER
. - When the
ADDRESS OF
clause is used after theTO
, this statement will be identifying the address of identifier-2 as the address to be assigned to identifier-1 or stored in pointer-name-1. - If the
ADDRESS OF
clause is absent after theTO
, the contents of pointer-name-2 will serve as the address to be assigned.
7.8.39.4. SET Index
SET Index Syntax
SET index-name-1 TO { literal-1 } ~~~ ~~ { identifier-2 }
This statement assigns a value to a USAGE INDEX
data item.
- Either the
USAGE
(see USAGE) of index-name-1 should beINDEX
, or index-name-1 must be identified in a tableINDEXED BY
clause.
7.8.39.5. SET UP/DOWN
SET UP/DOWN Syntax
SET identifier-1 { UP } BY [ LENGTH OF ] { literal-1 } ~~~ { ~~ } ~~ ~~~~~~ ~~ { identifier-2 } { DOWN } ~~~~
Use this statement to increment or decrement the value of an index or pointer by a specified amount.
- The
USAGE
(see USAGE) of identifier-1 must beINDEX
,POINTER
orPROGRAM-POINTER
. - The typical usage when identifier-1 is a
USAGE INDEX
data item is to increment its valueUP
orDOWN
by 1, since an index is usually being used to sequentially walk through the elements of a table.
7.8.39.6. SET Condition Name
SET Condition Name Syntax
SET condition-name-1... TO { TRUE } ~~~ ~~ { ~~~~ } { FALSE } ~~~~~
The SET Condition Name
statement provides one method of specifying the TRUE
/ FALSE
value of a level-88 condition name.
- By setting the specified condition-name-1(s) to a
TRUE
orFALSE
value, you will actually be assigning a value to the parent data item(s) to which the condition name data item(s) is(are) subordinate to. - When specifying
TRUE
, the value assigned to each parent data item will be the first value specified on the condition name’sVALUE
clause. - When specifying
FALSE
, the value assigned to each parent data item will be the value specified for theFALSE
clause of the condition name’s definition; if any condition-name-1 occurrence lacks aFALSE
clause, theSET
statement will be rejected by the compiler.
7.8.39.7. SET Switch
SET Switch Syntax
SET mnemonic-name-1... TO { ON } ~~~ ~~ { ~~ } { OFF } ~~~
This form of the SET
statement is used to turn switches on or off.
- Switches are defined using the
SPECIAL-NAMES
(see SPECIAL-NAMES) paragraph. - Switches may be tested via the
IF
statement (see IF) and a Switch-Status Condition. See Switch-Status Conditions, for more information.
7.8.39.8. SET ATTRIBUTE
SET ATTRIBUTE Syntax
SET identifier-1 ATTRIBUTE { { BELL } { ON }... ~~~ ~~~~~~~~~ { ~~~~ } { ~~ } { BLINK } { OFF } { ~~~~~ } ~~~ { HIGHLIGHT } { ~~~~~~~~~ } { LEFTLINE } { ~~~~~~~~ } { LOWLIGHT } { ~~~~~~~~ } { OVERLINE } { ~~~~~~~~ } { REVERSE-VIDEO } { ~~~~~~~~~~~~~ } { UNDERLINE } ~~~~~~~~~
The SET ATTRIBUTE
statement may be used to modify one or more attributes of a screen section data item at run-time.
- When making an attribute change to identifier-1, the change will not become visible on the screen until the screen section data item containing identifier-1 is next accepted (if identifier-1 is an input field) or is next displayed (if identifier-1 is not an input field).
- The attributes shown in the syntax diagram are the only ones that may be altered by this statement. See Data Description Clauses, for information on their usage.
7.8.39.9. SET LAST EXCEPTION
SET ATTRIBUTE Syntax
SET LAST EXCEPTION TO { OFF } ~~~ ~~~~ ~~~~~~~~~ ~~ ~~~
The SET LAST EXCEPTION
statement will set the last program exception status to indicate no exception.
- The predefined object reference EXCEPTION-OBJECT is set to null, and the last exception status is set to indicate no exception.
- This action resets the global exception object completely (FUNCTION EXCEPTION-{FILE, LOCATION, STATEMENT, STATUS } ), and will not show anything afterwards), no matter what the last exception was (such as a divide by zero). Use with care.
7.8.40. SORT
7.8.40.1. File-Based SORT
File-Based SORT Syntax
SORT sort-file-1 ~~~~ { ON { ASCENDING } KEY identifier-1... }... { ~~~~~~~~~ } { DESCENDING } ~~~~~~~~~~ [ WITH DUPLICATES IN ORDER ] ~~~~~~~~~~ [ COLLATING SEQUENCE IS alphabet-name-1 ] ~~~~~~~~~ { INPUT PROCEDURE IS procedure-name-1 } { ~~~~~~ ~~~~~~~~~ } { [ THRU|THROUGH procedure-name-2 ] } { ~~~~ ~~~~~~~ } { USING file-name-1... } ~~~~~ { OUTPUT PROCEDURE IS procedure-name-3 } { ~~~~~~ ~~~~~~~~~ } { [ THRU|THROUGH procedure-name-4 ] } { ~~~~ ~~~~~~~ } { GIVING file-name-2... } ~~~~~~
The DUPLICATES
clause is syntactically recognized but is otherwise non-functional.
This format of the SORT
statement is designed to sort large volumes of data according to one or more key fields.
- The reserved words
IN
,IS
,KEY
,ON
,ORDER
,SEQUENCE
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
THRU
andTHROUGH
are interchangeable. - GnuCOBOL always behaves as if the
WITH DUPLICATES IN ORDER
clause is specified, even if it isn’t.While any COBOL implementation’s sort or merge facilities guarantee that records with duplicate key values will be in proper sequence with regard to other records with different key values, they generally make no promises as to the resulting relative sequence of records having duplicate key values with one another.
Some COBOL implementations provide this optional clause to force their sort and merge facilities to retain duplicate key-value records in their original input sequence, relative to one another.
- The sort-file-1 named on the
SORT
statement must be defined using a sort description (SD
(see File/Sort-Description)). This file is referred to in the remainder of this discussion as the sort work file. - If specified, file-name-1 and file-name-2 must reference
ORGANIZATION LINE SEQUENTIAL
(see ORGANIZATION LINE SEQUENTIAL) orORGANIZATION SEQUENTIAL
(see ORGANIZATION SEQUENTIAL) files. These files must be defined using a file description (FD
(see File/Sort-Description)). The same file(s) may be used for file-name-1 and file-name-2. - The identifier-1 … field(s) must be defined as field(s) within a record of sort-file-1.
- A sort work file is never opened or closed.
- The sorting process works in three stages — the Input Stage, the Sort Stage and the Output Stage.
- The following points pertain to the Input Stage:
- The data to be sorted is loaded into the sort work file either by copying the entire contents of the file(s) named on the
USING
clause (done automatically by the sort) or by utilizing an input procedure. - When
USING
is specified, none of the file-name-1 files may be open at the time theSORT
statement is executed. - When an input procedure is used, the procedure(s) specified on the
INPUT PROCEDURE
clause will be invoked as if by a proceduralPERFORM
statement (see Procedural PERFORM) with noVARYING
,TIMES
orUNTIL
options specified. Records will be loaded into the sort work file — one at a time — within the input procedure using theRELEASE
statement (see RELEASE). This, by the way, is how you could sort the contents of relative or indexed files.A
GO TO
statement (see GO TO) that transfers control out of the input procedure will terminate theSORT
statement but allows the program to continue executing from the point where theGO TO
statement transferred control to. Once an input procedure has been “aborted” using aGO TO
it cannot be resumed, and the contents of the sort work file are lost. You may, however, re-execute theSORT
statement itself.3An input procedure should be terminated in the same way a procedural
PERFORM
statement would be.Neither a another file-based
SORT
statement nor aMERGE
statement may be executed within the input procedure unless those statements utilize a different sort or merge work file. - Once the input procedure terminates, the input phase is complete.
- As data is loaded into the sort work file, it is actually being buffered in dynamically-allocated memory. Only if the amount of data to be sorted exceeds the amount of available sort memory (128 MB) will actual disk files be allocated and utilized. There is a
COB_SORT_MEMORY
run-time environment variable (see Run Time Environment Variables) that you may use to allocate more or less memory to the sorting process.
- The data to be sorted is loaded into the sort work file either by copying the entire contents of the file(s) named on the
- The following points pertain to the Sort Stage:
- The sort will take place by arranging the data records in the sequence defined by the
KEY
specification(s) on theSORT
statement according to theCOLLATING SEQUENCE
specified on theSORT
(if any) or — if none was defined — thePROGRAM COLLATING SEQUENCE
(see OBJECT-COMPUTER). Keys may be any supported data type andUSAGE
(see USAGE) except for level-78 or level-88 data items. - For example, let’s assume we’re sorting a series of financial transactions. The SORT statement might look like this:
SORT Sort-File ASCENDING KEY Transaction-Date ASCENDING KEY Account-Number DESCENDING KEY Transaction-Amount
The effect of this statement will be to sort all transactions into ascending order of the date the transaction took place (oldest first, newest last). Unless the business running this program is going out of business, there are most-likely many transactions for any given date. Therefore, within each grouping of transactions all with the same date, transactions will be sub-sorted into ascending sequence of the account number the transactions apply to. Since it’s quite possible there might be multiple transactions for an account on any given date, a third level sub-sort will arrange all transactions for the same account on the same date into descending sequence of the actual amount of the transaction (largest first, smallest last). If two or more transactions of $100.00 were recorded for account #12345 on the 31st of August 2009, those transactions will be retained in the order in which they were loaded into the sort work file.
- Should disk work files be necessary due to the amount of data being sorted, they will be automatically allocated to disk in a folder defined by the
TMPDIR
run-time environment variable,TMP
run-time environment variable orTEMP
run-time environment variable run-time environment variables (see Run Time Environment Variables) (checked for existence in that sequence). These disk files will be automatically purged uponSORT
termination or program execution termination (normal or otherwise).
- The sort will take place by arranging the data records in the sequence defined by the
- The following points pertain to the Output Stage:
- Once the sort stage is complete, a copy of the sorted data will be written to each file-name-2 if the
GIVING
clause was specified. None of the file-name-2 files can be open at the time the sort is executed. - When an output procedure is used, the procedure(s) specified on the
OUTPUT PROCEDURE
clause will be invoked as if by a proceduralPERFORM
statement (see Procedural PERFORM) with noVARYING
,TIMES
orUNTIL
options specified. Records will be retrieved from the sort work file — one at a time — within the output procedure using theRETURN
statement (see RETURN).A
GO TO
statement (see GO TO) that transfers control out of the output procedure will terminate theSORT
statement but allows the program to continue executing from the point where theGO TO
statement transferred control to. Once an output procedure has been “aborted” using aGO TO
it cannot be resumed, and the contents of the sort work file are lost. You may, however, re-execute theSORT
statement itself. USING AGO TO
statement4An output procedure should be terminated in the same way a procedural
PERFORM
statement would be.Neither a another file-based
SORT
statement nor aMERGE
statement may be executed within the output procedure unless those statements utilize a different sort or merge work file. - Once the output procedure terminates, the sort is complete.
- Once the sort stage is complete, a copy of the sorted data will be written to each file-name-2 if the
7.8.40.2. Table SORT
Table SORT Syntax
SORT table-name-1 ~~~~ { ON { ASCENDING } KEY identifier-1... }... { ~~~~~~~~~ } { DESCENDING } ~~~~~~~~~~ [ WITH DUPLICATES IN ORDER ] ~~~~~~~~~~ [ COLLATING SEQUENCE IS alphabet-name-1 ] ~~~~~~~~~
The DUPLICATES
clause is syntactically recognized but is otherwise non-functional.
This format of the SORT
statement sorts relatively small quantities of data — namely data contained in a data division table — according to one or more key fields.
- The reserved words
IN
,IS
,KEY
,ON
,ORDER
,SEQUENCE
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - GnuCOBOL always behaves as if the
WITH DUPLICATES IN ORDER
clause is specified, even if it isn’t.While any COBOL implementation’s sort or merge facilities guarantee that records with duplicate key values will be in proper sequence with regard to other records with different key values, they generally make no promises as to the resulting relative sequence of records having duplicate key values with one another.
Some COBOL implementations provide this optional clause to force their sort and merge facilities to retain duplicate key-value records in their original input sequence, relative to one another.
- The table-name-1 data item must be a table defined in any data division section except the report or screen sections.
- The data within table-name-1 will be sorted in-place (i.e. no sort file is required).
- The sort will take place by rearranging the data in table-name-1 into the sequence defined by the
KEY
specification(s) on theSORT
statement, according to theCOLLATING SEQUENCE
specified on theSORT
(if any) or — if none was defined — thePROGRAM COLLATING SEQUENCE
(see OBJECT-COMPUTER). Keys may be any supported data type andUSAGE
(see USAGE) except for level-78 or level-88 data items. - If you are sorting table-name-1 for the purpose of preparing the table for use with a
SEARCH ALL
statement (see SEARCH ALL), care must be taken that theKEY
specifications on theSORT
agree with those in the table’s definition. - Although the specification of one or more
KEY
clauses is optional, currently, a table sort with noKEY
specification(s) made on theSORT
statement is unsupported by GnuCOBOL and will be rejected by the compiler.
7.8.41. START
START Syntax
START file-name-1 ~~~~~ [ { FIRST } ] { ~~~~~ } { LAST } { ~~~~ } { KEY { IS EQUAL TO | IS = | EQUALS } identifier-1 } { ~~~~~ ~~~~~~ } { IS GREATER THAN | IS > } { ~~~~~~~ } { IS GREATER THAN OR EQUAL TO | IS >= } { ~~~~~~~ ~~ ~~~~~ } { IS NOT LESS THAN } { ~~~ ~~~~ } { IS LESS THAN | IS < } { ~~~~ } { IS LESS THAN OR EQUAL TO | IS <= } { ~~~~ ~~ ~~~~~ } { IS NOT GREATER THAN } ~~~ ~~~~~~~ [ INVALID KEY imperative-statement-1 ] ~~~~~~~ [ NOT INVALID KEY imperative-statement-2 ] ~~~ ~~~~~~~ [ END-START ] ~~~~~~~~~
The START
statement defines the logical starting point within a relative or indexed file for subsequent sequential read operations. It positions an internal logical record pointer to a particular record in the file, but does not actually transfer any of that record’s data into the record buffer.
- The reserved words
IS
,KEY
,THAN
andTO
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - To use this statement, file-name-1 must be an
ORGANIZATION RELATIVE
(see ORGANIZATION RELATIVE) orORGANIZATION INDEXED
(see ORGANIZATION INDEXED) file that must have been defined with anACCESS MODE DYNAMIC
orACCESS MODE SEQUENTIAL
in itsSELECT
statement (see SELECT). - At the time this statement is executed, file-name-1 must be open in either
INPUT
orI-O
(see File OPEN Modes) mode. - If file-name-1 is a relative file, identifier-1 must be the defined
RELATIVE KEY
of the file. - If file-name-1 is an indexed file, identifier-1 must be the defined
RECORD KEY
of the file or any of theALTERNATE RECORD KEY
fields for the file. - If no
FIRST
,LAST
orKEY
clause is specified,KEY IS EQUAL TO xxx
will be assumed, wherexxx
is the definedRELATIVE KEY
of (if file-name-1 is a relative file) or the definedRECORD KEY
(if file-name-1 is an indexed file). - After successful execution of a
START
statement, the internal logical record pointer into the file-name-1 data will be positioned to the record which satisfied the actual or impliedFIRST
,LAST
orKEY
clause specification, as follows:FIRST
-
the logical record pointer will point to the first record in the file.
LAST
-
the logical record pointer will point to the last record in the file.
KEY
-
(specified or implied), and the relation used is
-
EQUAL TO
,GREATER THAN
orGREATER THAN OR EQUAL TO
(or equivalent) the logical record pointer will be specified to the first record satisfying the relation condition; to identify this record. The file’s contents are searched in a first-to-last (in sequence of the key implied by the
KEY
clause), provided the relation is-
LESS THAN
,LESS THAN OR EQUAL TO
orNOT GREATER THAN
(or equivalent) the logical record pointer will be specified to the last record satisfying the relation condition; to identify this record. The file’s contents are searched in a last-to-first (in sequence of the key implied by the
KEY
clause)
-
The next sequential
READ
statement will read the record that is pointed to by the logical record pointer. - The optional
INVALID KEY
andNOT INVALID KEY
clauses may be used to detect and react to the failure or success, respectively, by detecting non-zero (typically 23 = key not found = record not found) and 00 file status codes, respectively. See File Status Codes, for additional information.
7.8.42. STOP
STOP Syntax
STOP { RUN [ { RETURNING|GIVING { literal-1 } } ] } ~~~~ { ~~~ { ~~~~~~~~~ ~~~~~~ { identifier-1 } } } { { } } { { WITH { ERROR } STATUS [ { literal-2 } ] } } { { { ~~~~~ } { identifier-2 } } } { { { NORMAL } } } { ~~~~~~ } { literal-3 }
The STOP
statement suspends program execution. Some options will allow program execution to resume while others return control to the operating system.
- The reserved words
STATUS
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
RETURNING
andGIVING
are interchangeable. - The
RUN
clause halts the program without displaying any special message to that effect. - The literal-3 clause displays the specified text on the
SYSOUT
/STDOUT
device, waits for the user to press the Enter key and then — once the key has been pressed — allows the program to continue execution. - The optional
RETURNING
clause provides the opportunity to return a numeric value to the operating system (an exit status). The manner in which the exit status may be interrogated by the operating system varies, but Windows can use%ERRORLEVEL%
to query the exit status while Unix shells such as sh, bash and ksh can query the exit status as$?
. Other Unix shells may have different ways to access return code values. - The
STATUS
clause provides another means of returning an exit status. Using theSTATUS
clause is functionally equivalent to using theRETURNING
clause. - Using the
STATUS
clause without a literal-2 or identifier-2 will return an exit status of 0 if theNORMAL
keyword is used or a 1 ifERROR
was specified. - Your program will always return an exit status, even if no
RETURNING
orSTATUS
clause is specified. In the absence of the use of these clauses, the value in theRETURN-CODE
special register (see Special Registers) at the time theSTOP
statement is executed will be used as the exit status. - Any programmer-defined exit procedure (established via the
CBL_EXIT_PROC
built-in system subroutine (see CBL_EXIT_PROC)) will be executed bySTOP RUN
, but not bySTOP literal-3
. - Valid return code values can be in the range -2147483648 to +2147483647.
- The three code snippets below are all equivalent. They show different ways in which a GnuCOBOL program may be coded to pass an exit status value of 16 back to the operating system and then halt.
-
STOP RUN RETURNING 16
-
MOVE 16 TO RETURN-CODE STOP RUN
-
STOP RUN WITH ERROR STATUS 16
-
7.8.43. STRING
STRING Syntax
STRING ~~~~~~ { { literal-1 } [ DELIMITED BY { SIZE } ] }... { identifier-1 } ~~~~~~~~~ { ~~~~ } { literal-2 } { identifier-2 } INTO identifier-3 ~~~~ [ WITH POINTER identifier-4 ] ~~~~~~~ [ ON OVERFLOW imperative-statement-1 ] ~~~~~~~~ [ NOT ON OVERFLOW imperative-statement-2 ] ~~~ ~~~~~~~~ [ END-STRING ] ~~~~~~~~~~
The STRING
statement is used to concatenate all or a part of one or more strings together, forming a new string.
- The reserved words
BY
,ON
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - All literals and identifiers (except for identifier-4) must be explicitly or implicitly defined with a
USAGE
(see USAGE) ofDISPLAY
. Any of the identifiers may be group items. - The
POINTER
data item — identifier-4 — must be a non-edited elementary integer numeric data item with a value greater than zero. - Each literal-1 / identifier-1 will be referred to as a source item. The receiving data item is identifier-3.
- The
STRING
statement’s processing is based upon a current character pointer. The initial value of the current character pointer will be the value of identifier-4 at the time theSTRING
statement began execution. If noPOINTER
clause is coded, a value of 1 (meaning “the 1st character position”) will be assumed for the current character pointer’s initial value. - For each source item, the contents of the sending item will be copied — character-by-character — into identifier-3 at the character position specified by the current character pointer. After each character is copied, the current character pointer will be incremented by 1 so that it points to the position within identifier-3 where the next character should be copied.
- The
DELIMITED BY
clause specifies how much of each source item will be copied into identifier-3.DELIMITED BY SIZE
(the default if noDELIMITED BY
clause is specified) causes the entire contents of the source item to be copied into identifier-3. - Using
DELIMITED BY literal-2
orDELIMITED BY identifier-2
causes only the contents of the source item up to but not including the character sequence specified by the literal or identifier to be copied. -
STRING
processing will cease when one of the following occurs:- The initial value of the current character pointer is less than 1 or greater than the number of characters in identifier-3, or…
- The value of the current character pointer exceeds the size of identifier-3 at the point the STRING statement wants to copy a character into identifier-3, or…
- All sending items have been fully processed
- If event A occurs, identifier-3 will remain unchanged.
- The occurrence of either event A or B triggers what is referred to as an overflow condition.
- The identifier-3) is neither automatically initialized (to spaces or any other value) at the start of a
STRING
statement nor will it be space-filled should the total number of sending item characters copied into it be less than its size. You may explicitly initialize identifier-3 yourself via theINITIALIZE
(see INITIALIZE) orMOVE
(see MOVE) statements before executing theSTRING
if you wish. - The optional
ON OVERFLOW
andNOT ON OVERFLOW
clauses may be used to detect and react to the occurrence or not, respectively, of an overflow condition. See ON OVERFLOW + NOT ON OVERFLOW, for additional information.
7.8.44. SUBTRACT
7.8.44.1. SUBTRACT FROM
SUBTRACT FROM Syntax
SUBTRACT { literal-1 }... FROM { identifier-2 ~~~~~~~~ { identifier-1 } ~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-SUBTRACT ] ~~~~~~~~~~~~
This format of the SUBTRACT
statement generates the arithmetic sum of all arguments that appear before the FROM
(identifier-1 or literal-1) and subtracts that sum from each identifier-2.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items.
- literal-1 must be a numeric literal.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.44.2. SUBTRACT GIVING
SUBTRACT GIVING Syntax
SUBTRACT { literal-1 }... FROM identifier-2 ~~~~~~~~ { identifier-1 } ~~~~ GIVING { identifier-3 ~~~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] }... ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-SUBTRACT ] ~~~~~~~~~~~~
The SUBTRACT GIVING
statement generates the arithmetic sum of all arguments that appear before the FROM
(identifier-1 or literal-1), subtracts that sum from the contents of identifier-2 and then replaces the contents of the identifiers listed after the GIVING
(identifier-3) with that result.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be numeric unedited data items.
- literal-1 must be a numeric literal.
- identifier-3 must be a numeric (edited or unedited) data item.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.44.3. SUBTRACT CORRESPONDING
SUBTRACT CORRESPONDING Syntax
SUBTRACT CORRESPONDING identifier-1 FROM identifier-2 ~~~~~~~~ ~~~~ [ ROUNDED [ MODE IS { AWAY-FROM-ZERO } ] ] ~~~~~~~ ~~~~ { ~~~~~~~~~~~~~~ } { NEAREST-AWAY-FROM-ZERO } { ~~~~~~~~~~~~~~~~~~~~~~ } { NEAREST-EVEN } { ~~~~~~~~~~~~ } { NEAREST-TOWARD-ZERO } { ~~~~~~~~~~~~~~~~~~~ } { PROHIBITED } { ~~~~~~~~~~ } { TOWARD-GREATER } { ~~~~~~~~~~~~~~ } { TOWARD-LESSER } { ~~~~~~~~~~~~~ } { TRUNCATION } ~~~~~~~~~~ [ ON SIZE ERROR imperative-statement-1 ] ~~~~ ~~~~~ [ NOT ON SIZE ERROR imperative-statement-2 ] ~~~ ~~~~ ~~~~~ [ END-SUBTRACT ] ~~~~~~~~~~~~
The SUBTRACT CORRESPONDING
statement generates code equivalent to individual SUBTRACT FROM
statements for corresponding matches of data items found subordinate to the two identifiers.
- The reserved words
IS
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - Both identifier-1 and identifier-2 must be group items.
- See CORRESPONDING, for information on how corresponding matches will be found between identifier-1 and identifier-2.
- The optional
ROUNDED
(see ROUNDED) clause available to each identifier-2 will control how non-integer results will be saved. - The optional
ON SIZE ERROR
andNOT ON SIZE ERROR
clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation. In this case, failure is defined as being an identifier-2 with an insufficient number of digit positions available to the left of any implied decimal point. See ON SIZE ERROR + NOT ON SIZE ERROR, for additional information.
7.8.45. SUPPRESS
SUPPRESS Syntax
SUPPRESS PRINTING ~~~~~~~~
The SUPPRESS
statement causes the presentation of a report group to be suppressed.
- The reserved word
PRINTING
is optional and may be omitted. The presence or absence of this word has no effect upon the program. - This statement may only appear within a
USE BEFORE REPORTING
procedure (inDECLARATIVES
(see DECLARATIVES)). -
SUPPRESS
only prevents the presentation of the report group within whoseUSE BEFORE REPORTING
procedure the statement occurs. - This statement must be executed each time presentation of the report group is to be suppressed.
- When a report group’s presentation is suppressed, none of the following operations for the report will take place:
- Actual presentation of the report group in question.
- Processing of any
LINE
(see LINE) clauses within the report group in question. - Processing of the
NEXT GROUP
(see NEXT GROUP) clause (if any) within the report group in question. - Any modification to the
LINE-COUNTER
special register (see Special Registers). - Any modification to the
PAGE-COUNTER
special register.
7.8.46. TERMINATE
TERMINATE Syntax
TERMINATE report-name-1... ~~~~~~~~~
The TERMINATE
statement causes the processing of the specified report(s) to be completed.
- Each report-name-1 must be the name of a report having an
RD
(see REPORT SECTION) defined for it. - The specified report name(s) must be currently initiated (via
INITIATE
(see INITIATE)) and cannot yet have been terminated. - The
TERMINATE
statement will present eachCONTROL FOOTING
(if any), in reverse sequence of the control hierarchy, starting with the most minor up toFINAL
(if any). During the presentation of these groups and the processing of anyUSE BEFORE REPORTING
procedures for those groups, the prior set of control data item values will be available, as though a control break had been detected at the most major control data name. - During the presentation of the
CONTROL FOOTING
groups, any necessaryPAGE FOOTING
andPAGE HEADING
groups will be presented as well. - Finally,the
REPORT FOOTING
group, if any, will be presented. - If an
INITIATE
is followed by aTERMINATE
with no interveningGENERATE
(see GENERATE) statements (all pertaining to the same report, of course), no report groups will be presented to the output file.
7.8.47. TRANSFORM
TRANSFORM Syntax
TRANSFORM identifier-1 FROM { literal-1 } TO { literal-2 } ~~~~~~~~~ ~~~~ { identifier-2 } ~~ { identifier-3 }
The TRANSFORM
statement scans a data item performing a series of mono-alphabetic substitutions, defined by the arguments before and after the TO
clause.
- Both literal-1 and/or literal-2 must be alphanumeric literals.
- All of identifier-1, identifier-2 and identifier-3 must either be group items or alphanumeric data items. Numeric data items with a
USAGE
(see USAGE) ofDISPLAY
are accepted, but will generate warning messages from the compiler. - The
TRANSFORM
statement will replace characters within identifier-1 that are found in the string specified before theTO
keyword with the corresponding characters from the string specified after theTO
keyword. - This statement exists within GnuCOBOL to provide compatibility with COBOL programs written to pre-1985 standards. The
TRANSFORM
statement was made obsolete in the 1985 standard of COBOL, having been replaced by theCONVERTING
clause of theINSPECT
statement (see INSPECT). New programs should be coded to useINSPECT CONVERTING
rather thanTRANSFORM
.
7.8.48. UNLOCK
UNLOCK Syntax
UNLOCK filename-1 RECORD|RECORDS ~~~~~~
This statement synchronizes any as-yet unwritten file I/O buffers to the specified file (if any) and releases any record locks held for records belonging to file-name-1.
- The reserved words
RECORD
andRECORDS
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - If file-name-1 is a Sort/Merge work file, no action will be taken.
- Not all GnuCOBOL implementations support locking. Whether they do or not depends upon the operating system they were built for and the build options that were used when GnuCOBOL was generated. When a program using one of those GnuCOBOL implementations issues an UNLOCK, it will ignored. There will be no compiler message issued. Buffer syncing, if needed, will still occur.
- See Record Locking, for additional information on record locking.
7.8.49. UNSTRING
UNSTRING Syntax
UNSTRING identifier-1 ~~~~~~~~ DELIMITED BY { [ ALL ] literal-1 } [ OR { [ ALL ] literal-2 } ]... ~~~~~~~~~ { ~~~ } ~~ { ~~~ } { identifier-2 } { identifier-3 } INTO { identifier-4 ~~~~ [ DELIMITER IN identifier-5 ] [ COUNT IN identifier-6 ] }... ~~~~~~~~~ ~~~~~ [ WITH POINTER identifier-7 ] ~~~~~~~ [ TALLYING IN identifier-8 ] ~~~~~~~~ [ ON OVERFLOW imperative-statement-1 ] ~~~~~~~~ [ NOT ON OVERFLOW imperative-statement-2 ] ~~~ ~~~~~~~~ [ END-UNSTRING ] ~~~~~~~~~~~~
The UNSTRING
statement parses a string, extracting any number of sub strings from it.
- The reserved words
BY
,IN
andON
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - identifier-1 through identifier-5 must be explicitly or implicitly defined with a
USAGE
(see USAGE) ofDISPLAY
. Any of those identifiers may be group items. - Both literal-1 and literal-2 must be alphanumeric literals.
- Each of identifier-6, identifier-7 and identifier-8 must be elementary non-edited integer numeric items.
- At the time the
UNSTRING
statement begins execution, identifier-7 must have a value greater than 0. - identifier-1 will be referred to as the source string and each identifier-4 will be referred to as a destination field in the following discussions.
- The
UNSTRING
statement’s processing is based upon a current character pointer, the initial value of which will be the value of identifier-7 at the time theUNSTRING
statement began execution. If noPOINTER
clause is coded, a value of 1 (meaning “the 1st character position”) will be assumed for the current character pointer’s initial value. - The source string will be parsed into sub strings starting from the current character pointer position. Sub strings are identified by using the various delimiter strings specified on the
DELIMITED BY
clause as inter-sub string separators. - Using the
ALL
option allows a delimiter sequence to be an arbitrarily long sequence of occurrences of the delimiter literal whereas its absence treats each occurrence as a separate delimiter. When multiple delimiters are specified, they will be looked for in the source string in the sequence in which they are coded. - Two consecutive delimiter sequences will identify a null sub string.
- Identified sub strings will be moved into each destination field in the sequence they are identified; values moved into a destination field will be truncated if the sub string length exceeds the destination field length, or padded with spaces if the destination field length exceeds the sub string length. Both truncation and padding will be controlled by the presence or absence of a
JUSTIFIED
(see JUSTIFIED) clause on the destination field. - Each destination field may have an optional
DELIMITER
clause. If aDELIMITER
clause is specified, identifier-5 will have the delimiter character string used to identify the sub string for the destination field moved into it. If a destination field was not altered (because an insufficient number of sub strings were identified), identifier-5 for that destination field will also be unchanged. - Each destination field may have an optional
COUNT
clause. If aCOUNT
clause is specified, identifier-6 will have the size of the sub string (in characters) for the destination field moved into it. If a destination field was not altered (because an insufficient number of sub strings were identified), identifier-6 for that destination field will also be unchanged. - If a
TALLYING
clause is coded, identifier-8 will be incremented by 1 each time a destination field is populated. - None of identifier-4, identifier-5, identifier-6, identifier-7 or identifier-8 are initialized by the
UNSTRING
statement. You need to do that yourself via aMOVE
(see MOVE) orINITIALIZE
statement (see INITIALIZE). -
UNSTRING
processing will cease when one of the following occurs:- The initial value of the current character pointer is less than 1 or greater than the number of character positions in identifier-1, or…
- All destination fields have been fully processed
- If event A occurs, none of the destination field contents (or the contents of their
DELIMITER
or COUNT identifiers) will be changed. - An overflow condition exists if either event A occurs, or if event B occurs with at least one character position in identifier-1 not having been processed.
- The optional
ON OVERFLOW
andNOT ON OVERFLOW
clauses may be used to detect and react to the occurrence or not, respectively, of an overflow condition. See ON OVERFLOW + NOT ON OVERFLOW, for additional information.
The following sample program illustrates the UNSTRING
statement statement.
IDENTIFICATION DIVISION. PROGRAM-ID. DEMOUNSTRING. DATA DIVISION. WORKING-STORAGE SECTION. 01 Full-Name PIC X(40). 01 Parsed-Info. 05 Last-Name PIC X(15). 05 First-Name PIC X(15). 05 MI PIC X(1). 05 Delim-LN PIC X(1). 05 Delim-FN PIC X(1). 05 Delim-MI PIC X(1). 05 Count-LN BINARY-CHAR. 05 Count-FN BINARY-CHAR. 05 Count-MI BINARY-CHAR. 05 Tallying-Ctr BINARY-CHAR. PROCEDURE DIVISION. P1. PERFORM UNTIL EXIT DISPLAY "Enter Full Name (null quits):" WITH NO ADVANCING ACCEPT Full-Name IF Full-Name = SPACES EXIT PERFORM END-IF INITIALIZE Parsed-Info UNSTRING Full-Name DELIMITED BY ", " OR "," OR ALL SPACES INTO Last-Name DELIMITER IN Delim-LN COUNT IN Count-LN First-Name DELIMITER IN Delim-FN COUNT IN Count-FN MI DELIMITER IN Delim-MI COUNT IN Count-MI TALLYING Tallying-Ctr DISPLAY "First-Name=" First-Name " Delim='" Delim-FN "' Count=" Count-FN DISPLAY "MI =" MI " " " Delim='" Delim-MI "' Count=" Count-MI DISPLAY "Last-Name =" Last-Name " Delim='" Delim-LN "' Count=" Count-LN DISPLAY "Tally= " Tallying-Ctr END-PERFORM DISPLAY "Bye!" STOP RUN .
The following is sample output from the program:
Enter Full Name (null quits):Cutler, Gary L First-Name=Gary Delim=' ' Count=+004 MI =L Delim=' ' Count=+001 Last-Name =Cutler Delim=',' Count=+006 Tally= +003 Enter Full Name (null quits):Snoddgrass,Throckmorton,P First-Name=Throckmorton Delim=',' Count=+012 MI =P Delim=' ' Count=+001 Last-Name =Snoddgrass Delim=',' Count=+010 Tally= +003 Enter Full Name (null quits):Munster Herman First-Name=Herman Delim=' ' Count=+006 MI = Delim=' ' Count=+000 Last-Name =Munster Delim=' ' Count=+007 Tally= +002 Enter Full Name (null quits): Bye!
7.8.50. WRITE
WRITE Syntax
WRITE record-name-1 ~~~~~ [ FROM { literal-1 } ] ~~~~ { identifier-1 } [ WITH [ NO ] LOCK ] ~~ ~~~~ [ { BEFORE } ADVANCING { { literal-2 } LINE|LINES } ] { ~~~~~~ } { { identifier-2 } { AFTER } { PAGE } ~~~~~ { ~~~~ } { mnemonic-name-1 } [ AT END-OF-PAGE|EOP imperative-statement-1 ] ~~~~~~~~~~~ ~~~ [ NOT AT END-OF-PAGE|EOP imperative-statement-2 ] ~~~ ~~~~~~~~~~~ ~~~ [ INVALID KEY imperative-statement-3 ] ~~~~~~~ [ NOT INVALID KEY imperative-statement-4 ] ~~~ ~~~~~~~ [ END-WRITE ] ~~~~~~~~~
The WRITE
statement writes a new record to an open file.
- The reserved words
ADVANCING
,AT
,KEY
,LINE
,LINES
andWITH
are optional and may be omitted. The presence or absence of these words has no effect upon the program. - The reserved words
END-OF-PAGE
andEOP
are interchangeable. - The record-name-1 specified on the statement must be defined as an 01-level record subordinate to the File Description (
FD
(see File/Sort-Description)) of a file that is currently open forOUTPUT
(see File OPEN Modes),EXTEND
orI-O
. - The optional
FROM
clause will cause literal-1 or identifier-1 to be automatically moved into record-name-1 prior to writing record-name-1’s contents to the appropriate file. If this clause is not specified, it is the programmer’s responsibility to populate record-name-1 with the desired data prior to executing theWRITE
. - The optional
LOCK
options may be used to manually control access to the just-written record by other programs while this program is running. See Record Locking, to review the various record locking behaviour. - The optional
INVALID KEY
andNOT INVALID KEY
clauses may be used when writing to relative or indexed files to detect and react to the failure (non-zero file status code) or success (00 file status code), respectively, of the statement. See File Status Codes, for additional information. - When
WRITE
is used against anORGANIZATION LINE SEQUENTIAL
(see ORGANIZATION LINE SEQUENTIAL) file, with or without theLINE ADVANCING
(see LINE ADVANCING) option, an end-of-record delimiter character sequence will be written to the file to signify where one record ends and the next record begins. This delimiter sequence will be either of the following:- A line-terminator sequence consisting of an ASCII carriage-return/line-feed character sequence (
X'0D0A'
) if you are running a MinGW or native Windows build of GnuCOBOL - A line-terminator sequence consisting of an ASCII line-feed character (
X'0A'
) if you are running a Cygwin, Linux, Unix or OSX build of GnuCOBOL
- A line-terminator sequence consisting of an ASCII carriage-return/line-feed character sequence (
- The following points pertain to the use (or not) of the
ADVANCING
clause:- Using this clause with any organization other than
ORGANIZATION LINE SEQUENTIAL
will either be rejected outright by the compiler (relative or indexed files) or may introduce unwanted characters into the file (ORGANIZATION SEQUENTIAL
(see ORGANIZATION SEQUENTIAL)). - If no
ADVANCING
clause is specified on aWRITE
to a line-advancing file,AFTER ADVANCING 1 LINE
will be assumed; on other than line-advancing files,BEFORE ADVANCING 1 LINE
will be assumed. - When
BEFORE ADVANCING
is used (or implied), the record is written to the file before theADVANCING
action writes line-terminator characters to the file. - If
AFTER ADVANCING
is used (or implied), theADVANCING
action writes line-terminator characters to the file and then the record data is written to the file. - The
ADVANCING n LINES
clause will introduce the specified number of line-terminator character sequences into the file either before the written record (AFTER ADVANCING
) or after the written record (BEFORE ADVANCING
). - If the
LINAGE
(see File/Sort-Description) clause is absent from the file’sFD
:- The
ADVANCING PAGE
clause will introduce an ASCII formfeed character into the file either before the written record (AFTER PAGE
) or after the written record (BEFORE PAGE
). - Management of areas on the printed page such as top-of page headers, bottom-of-page footers, dealing with “full page” situations and the like are the complete responsibility of the programmer.
- The
- If the LINAGE clause is present in the file’s
FD
:- The
ADVANCING PAGE
clause will introduce the appropriate number of line-terminator character sequences into the file either before the written record (AFTER ADVANCING
) or after the written record (BEFORE ADVANCING
) so as to force the printer to automatically advance to a new sheet of paper when the file prints. No formfeed characters will be generated whenLINAGE
is specified — instead, it is assumed that the printer to which the report will be printed will be loaded with special forms that conform to the specifications defined by theLINAGE
clause. - Management of areas on the printed page such as top-of page headers, bottom-of-page footers, dealing with “full page” situations and the like are now the joint responsibility of the programmer and the GnuCOBOL run-time library, which provides tools such as the
LINAGE-COUNTER
special register (see Special Registers) and theEND-OF-PAGE
clause to deal with page formatting issues. - The
AT END-OF-PAGE
clause will be triggered, thus executing imperative-statement-1 (see Imperative Statement), if theWRITE
statement introduces a data line or line-feed character into the file at a line position within the Page Footer area defined by theLINAGE
clause. TheNOT AT END-OF-PAGE
clause will be triggered (thus executing imperative-statement-2) if no end-of-page condition occurred during theWRITE
.
- The
- Using this clause with any organization other than
8. Functions
8.1. Intrinsic Functions
GnuCOBOL supports a wide variety of “intrinsic functions” that may be used anywhere in the PROCEDURE DIVISION where a literal is allowed. For example:
MOVE FUNCTION LENGTH(Employee-Last-Name) TO Employee-LN-Len
Note how the word FUNCTION
is part of the syntax when you use an intrinsic function. You can use intrinsic functions without having to include the reserved word FUNCTION
via settings in the REPOSITORY
(see REPOSITORY) paragraph. You may accomplish the same thing by specifying the -fintrinsics switch to the GnuCOBOL compiler when you compile your programs.
User-written functions (see Subprogram Types) never require the FUNCTION
keyword when they are executed, because each user-written function a program uses must be included in that program’s REPOSITORY
paragraph, which therefore makes the FUNCTION
keyword optional.
The following intrinsic functions, known to other “dialects” of COBOL, are defined to GnuCOBOL as reserved words but are not otherwise implemented currently. Any attempts to use these functions will result in a compile-time error message. However they are described at the end of this chapter.
BOOLEAN-OF-INTEGER CHAR-NATIONAL DISPLAY-OF EXCEPTION-FILE-N EXCEPTION-LOCATION-N INTEGER-OF-BOOLEAN NATIONAL-OF STANDARD-COMPARE
The supported intrinsic functions are listed in the following sections, along with their syntax and usage notes.
8.1.1. ABS
ABS Function Syntax
ABS(number) ~~~
This function determines and returns the absolute value of number (a numeric literal or data item) supplied as an argument.
Note that ABSOLUTE-VALUE
has an alias for this function.
8.1.2. ACOS
ACOS Function Syntax
ACOS(cosine) ~~~~
The ACOS
function determines and returns the trigonometric arc-cosine, or inverse cosine, of cosine value (a numeric literal or data item) supplied as an argument.
The result will be an angle, expressed in radians. You may convert this to an angle measured in degrees, as follows:
COMPUTE degrees = ( radians * 180 ) / FUNCTION PI
8.1.3. ANNUITY
ANNUITY Function Syntax
ANNUITY(interest-rate, number-of-periods) ~~~~~~~
This function returns a numeric value approximating the ratio of an annuity paid at interest-rate (numeric data item or literal) for each of number-of-periods (numeric data items or literals).
interest-rate is the rate of interest paid at each payment. If you only have an annual interest rate and you wish to compute monthly annuity payments, divide the annual interest rate by 12 and use that value for interest-rate.
Multiply the result of this function times the desired principal amount to determine the amount of each period’s payment.
A note for the financially challenged: an annuity is basically a reverse loan; an accountant would take the result of this function multiplied by -1 times the principal amount to compute a loan payment you are making.
8.1.4. ASIN
ASIN Function Syntax
ASIN(sine) ~~~~
The ASIN
function determines and returns the trigonometric arc-sine, or inverse sine, of sine value (a numeric literal or data item) supplied as an argument.
The result will be an angle, expressed in radians. You may convert this to an angle measured in degrees, as follows:
COMPUTE degrees = ( radians * 180 ) / FUNCTION PI
8.1.5. ATAN
ATAN Function Syntax
ATAN(tangent) ~~~~
Use this function to determine and return the trigonometric arc-tangent, or inverse tangent, of tangent value (a numeric literal or data item) supplied as an argument.
The result will be an angle, expressed in radians. You may convert this to an angle measured in degrees, as follows:
COMPUTE degrees = ( radians * 180 ) / FUNCTION PI
8.1.6. BYTE-LENGTH
BYTE-LENGTH Function Syntax
BYTE-LENGTH(string) ~~~~~~~~~~~
BYTE-LENGTH
returns the length — in bytes — of string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal). This intrinsic function is identical to the LENGTH-AN
(see LENGTH-AN) function. Note that the value returned by this function is not necessarily the number of characters comprising string, but rather the number of actual bytes required to store it.
For example, if string is encoded using a double-byte character set such as Unicode UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to character sets like ASCII or EBCDIC), then calling this function with a string argument whose PICTURE
(see PICTURE) is X(4)
would return a value of 8 rather than the value 4.
Contrast this with the LENGTH
(see LENGTH) function.
8.1.7. CHAR
CHAR Function Syntax
CHAR(integer) ~~~~
This function returns the character in the ordinal position specified by integer (a numeric integer literal or data item with a value of 1 or greater) from the COLLATING SEQUENCE
(see OBJECT-COMPUTER) being used by the program.
For example, if the program is using the (default) ASCII character set, CHAR(34) returns the 34th character in the ASCII character set — an exclamation-point (‘!’). If you are using this function to convert a numeric value to its corresponding ASCII character, you must use an argument value one greater than the numeric value.
If an argument whose value is less than 1 or greater than 256 is specified, the character in the program collating sequence corresponding to a value of all zero bits is returned.
The following code is an alternative approach when you just wish to convert a number to its ASCII equivalent:
01 Char-Value. 05 Numeric-Value USAGE BINARY-CHAR. … MOVE numeric-character-value TO Numeric-Value
The Char-Value
item now has the corresponding ASCII character value.
8.1.8. COMBINED-DATETIME
COMBINED-DATETIME Function Syntax
COMBINED-DATETIME(days, seconds) ~~~~~~~~~~~~~~~~~
This function returns a 12-digit numeric result, the first seven digits of which are the integer value of days argument (a numeric data item or literal) and the last five of which are the integer value of seconds argument (also a numeric data item or literal).
If days is less than 1 or greater than 3,067,671, or if seconds is less than 1 or greater than 86,400, a value of 0 is returned and a runtime error will result.
8.1.9. CONCATENATE
CONCATENATE Function Syntax
CONCATENATE(string-1 [, string-2 ]...) ~~~~~~~~~~~
This function concatenates the string-1, string-2, … (group items, USAGE DISPLAY
elementary items and/or alphanumeric literals) together into a single string result.
If a numeric literal or PIC 9
identifier is specified as an argument, decimal points, if any, will be removed and negative signs in PIC S9
fields or numeric literals will be inserted as defined by the SIGN IS
(see SIGN IS) clause (or absence thereof) of the field. Numeric literals are processed as if SIGN IS TRAILING SEPARATE
were in effect.
8.1.10. COS
COS Function Syntax
COS(angle) ~~~
The COS
function determines and returns the trigonometric cosine of angle (a numeric literal or data item) supplied as an argument.
angle is assumed to be a value expressed in radians. If you need to determine the cosine of an angle measured in degrees, you first need to convert that angle to radians as follows:
COMPUTE radians = ( degrees * FUNCTION PI) / 180
8.1.11. CURRENCY-SYMBOL
CURRENCY-SYMBOL Function Syntax
CURRENCY-SYMBOL ~~~~~~~~~~~~~~~
The CURRENCY-SYMBOL
function returns the currency symbol character currently in effect for the locale under which your program is running. On UNIX systems, your locale is established via the LANG
run-time environment variable (see Run Time Environment Variables) environment variable. On Windows, the Control Panel’s "Regional and Language Options" define the locale.
Changing the currency symbol via the SPECIAL-NAMES
(see SPECIAL-NAMES) paragraph’s CURRENCY SYMBOL
setting will not affect the value returned by this function.
8.1.12. CURRENT-DATE
CURRENT-DATE Function Syntax
CURRENT-DATE ~~~~~~~~~~~~
Returns the current date and time as the following 21-character structure:
01 CURRENT-DATE-AND-TIME. 05 CDT-Year PIC 9(4). 05 CDT-Month PIC 9(2). *> 01-12 05 CDT-Day PIC 9(2). *> 01-31 05 CDT-Hour PIC 9(2). *> 00-23 05 CDT-Minutes PIC 9(2). *> 00-59 05 CDT-Seconds PIC 9(2). *> 00-59 05 CDT-Hundredths-Of-Secs PIC 9(2). *> 00-99 05 CDT-GMT-Diff-Hours PIC S9(2) SIGN LEADING SEPARATE. 05 CDT-GMT-Diff-Minutes PIC 9(2). *> 00 or 30
Since this function has no arguments, no parenthesis should be specified.
8.1.13. DATE-OF-INTEGER
DATE-OF-INTEGER Function Syntax
DATE-OF-INTEGER(integer) ~~~~~~~~~~~~~~~
This function returns a numeric calendar date in yyyymmdd (i.e. Gregorian) format. The date is determined by adding the number of days specified as integer (a numeric integer data item or literal) to the date December 31, 1600. For example, DATE-OF-INTEGER(1)
returns 16010101 while DATE-OF-INTEGER(150000)
returns 20110908.
A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0.
8.1.14. DATE-TO-YYYYMMDD
DATE-TO-YYYYMMDD Function Syntax
DATE-TO-YYYYMMDD(yymmdd [, yy-cutoff [, yy-execution-time ]]) ~~~~~~~~~~~~~~~~
You can use this function to convert the six-digit Gregorian date specified as yymmdd (a numeric integer data item or literal) to an eight-digit format (yyyymmdd).
The optional yy-cutoff (a numeric integer data item or literal) argument is the year cutoff used to delineate centuries; if the year component of the date meets or exceeds this cutoff value, the result will be 19yymmdd; if the year component of the date is less than the cutoff value, the result will be 20yymmdd. The default cutoff value if no second argument is given will be 50.
The optional yy-execution-time argument (a numeric integer data item or literal) The default execution time value if no third argument is given will be now equivalent to specifying (FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4)))
.
8.1.15. DAY-OF-INTEGER
DAY-OF-INTEGER Function Syntax
DAY-OF-INTEGER(integer) ~~~~~~~~~~~~~~
This function returns a calendar date in yyyyddd (i.e. Julian) format. The date is determined by adding the number of days specified as integer (a numeric integer data item or literal) to December 31, 1600. For example, DAY-OF-INTEGER(1)
returns 1601001 while DAY-OF-INTEGER(250000)
returns 2011251.
A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0.
8.1.16. DAY-TO-YYYYDDD
DAY-TO-YYYYDDD Function Syntax
DAY-TO-YYYYDDD(yyddd [, yy-cutoff [, yy-execution-time ]]) ~~~~~~~~~~~~~~
You can use this function to convert the five-digit Julian date specified as yyddd (a numeric integer data item or literal) to a seven-digit numeric Julian format (yyyyddd).
The optional yy-cutoff argument (a numeric integer data item or literal) is the year cutoff used to delineate centuries; if the year component of the date meets or exceeds this cutoff value, the result will be 19yyddd; if the year component of the date is less than the cutoff, the result will be 20yyddd. The default cutoff value if no second argument is given will be 50.
The optional yy-execution-time argument (a numeric integer data item or literal) The default execution time value if no third argument is given will be now equivalent to specifying (FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))).
8.1.17. E
E Function Syntax
E ~
This function returns the mathematical constant E (the base of natural logarithms). The maximum precision with which this value may be returned is 2.7182818284590452353602874713526625.
Since this function has no arguments, no parenthesis should be specified.
8.1.18. EXCEPTION-FILE
EXCEPTION-FILE Function Syntax
EXCEPTION-FILE ~~~~~~~~~~~~~~
This function returns I/O exception information from the most-recently executed input or output statement. The information is returned as a 34-character string, where the first two characters are the two-digit file status value (see File Status Codes) and the remaining 32 are the file-name-1 specification from the file’s SELECT
(see SELECT) statement.
The name returned after the file status information will be returned only if the returned file status value is not 00.
Since this function has no arguments, no parenthesis should be specified.
The documentation of the CBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine illustrates the use of this function.
8.1.19. EXCEPTION-LOCATION
EXCEPTION-LOCATION Function Syntax
EXCEPTION-LOCATION ~~~~~~~~~~~~~~~~~~
This function returns exception information from the most-recently failing statement. The information is returned to a 1023 character string in one of the following formats, depending on the nature of the failure:
- primary-entry-point-name; paragraph OF section; statement-number
- primary-entry-point-name; section; statement-number
- primary-entry-point-name; paragraph; statement-number
- primary-entry-point-name; statement-number
Since this function has no arguments, no parenthesis should be specified.
The program must be compiled with the -debug switch, -ftraceall switch or -g switch for this function to return any meaningful information.
The documentation of the CBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine illustrates the use of this function.
8.1.20. EXCEPTION-STATEMENT
EXCEPTION-STATEMENT Function Syntax
EXCEPTION-STATEMENT ~~~~~~~~~~~~~~~~~~~
This function returns the most-recent COBOL statement that generated an exception condition.
Since this function has no arguments, no parenthesis should be specified.
The program must be compiled with the -debug switch, -ftraceall switch or -g switch for this function to return any meaningful information.
The documentation of the CBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine illustrates the use of this function.
8.1.21. EXCEPTION-STATUS
EXCEPTION-STATUS Function Syntax
EXCEPTION-STATUS ~~~~~~~~~~~~~~~~
This function returns the error type (a text string — see column 2 of the upcoming table for the possible values) from the most-recent COBOL statement that generated an exception condition.
Since this function has no arguments, no parenthesis should be specified.
The documentation of the CBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine illustrates the use of this function.
The following are the error type strings, and their corresponding exception codes and descriptions.
Code | Error Type | Description |
---|---|---|
0101 |
EC-ARGUMENT-FUNCTION |
Function argument error |
0202 |
EC-BOUND-ODO |
OCCURS … DEPENDING ON data item out of bounds |
0204 |
EC-BOUND-PTR |
Data-pointer contains an address that is out of bounds |
0205 |
EC-BOUND-REF-MOD |
Reference modifier out of bounds |
0207 |
EC-BOUND-SUBSCRIPT |
Subscript out of bounds |
0303 |
EC-DATA-INCOMPATIBLE |
Incompatible data exception |
0500 |
EC-I-O |
input-output exception |
0501 |
EC-I-O-AT-END |
I-O status 1x
|
0502 |
EC-I-O-EOP |
An end of page condition occurred |
0504 |
EC-I-O-FILE-SHARING |
I-O status 6x
|
0505 |
EC-I-O-IMP |
I-O status 9x
|
0506 |
EC-I-O-INVALID-KEY |
I-O status 2x
|
0508 |
EC-I-O-LOGIC-ERROR |
I-O status 4x
|
0509 |
EC-I-O-PERMANENT-ERROR |
I-O status 3x
|
050A |
EC-I-O-RECORD-OPERATION |
I-O status 5x
|
0601 |
EC-IMP-ACCEPT |
Implementation-defined accept condition |
0602 |
EC-IMP-DISPLAY |
Implementation-defined display condition |
0A00 |
EC-OVERFLOW |
Overflow condition |
0A02 |
EC-OVERFLOW-STRING |
STRING overflow condition |
0A03 |
EC-OVERFLOW-UNSTRING |
UNSTRING overflow condition |
0B05 |
EC-PROGRAM-NOT-FOUND |
Called program not found |
0D03 |
EC-RANGE-INSPECT-SIZE |
Size of replace item in inspect differs |
1000 |
EC-SIZE |
Size error exception |
1004 |
EC-SIZE-OVERFLOW |
Arithmetic overflow in calculation |
1005 |
EC-SIZE-TRUNCATION |
Significant digits truncated in store |
1007 |
EC-SIZE-ZERO-DIVIDE |
Division by zero |
1202 |
EC-STORAGE-NOT-ALLOC |
The data-pointer specified in a FREE statement does not identify currently allocated storage |
1203 |
EC-STORAGE-NOT-AVAIL |
The amount of storage requested by an ALLOCATE statement is not available |
8.1.22. EXP
EXP Function Syntax
EXP(number) ~~~
Computes and returns the value of the mathematical constant e raised to the power specified by number (a numeric literal or data item).
8.1.23. EXP10
EXP10 Function Syntax
EXP10(number) ~~~~~
Computes and returns the value of 10 raised to the power specified by number (a numeric literal or data item).
8.1.24. FACTORIAL
FACTORIAL Function Syntax
FACTORIAL(number) ~~~~~~~~~
This function computes and returns the factorial value of number (a numeric literal or data item).
8.1.25. FORMATTED-CURRENT-DATE
FORMATTED-CURRENT-DATE Function Syntax
FORMATTED-CURRENT-DATE ( argument-1 ) ~~~~~~~~~~~~~~~~~~~~~~
FORMATTED-CURRENT-DATE
returns the current date and time provided by the system at run-time, formatted according to date-and-time-format according to the argument type.
The function argument must be a national or alphanumeric literal and the content, a combined date and time format.
The returned value is formatted to the same form as argument-1.
8.1.26. FORMATTED-DATE
FORMATTED-DATE Function Syntax
FORMATTED-DATE ( argument-1, argument-2 ) ~~~~~~~~~~~~~~
FORMATTED-DATE
uses a format to convert a date in integer date form to a date in the requested format. The returned value will be in date format.
argument-1 shall be a national or alphanumeric literal.
argument-2 shall be a value in integer date form.
8.1.27. FORMATTED-DATETIME
FORMATTED-DATETIME Function Syntax
FORMATTED-DATETIME ( argument-1, argument-2, argument-3, argument-4 ) ~~~~~~~~~~~~~~~~~~
FORMATTED-DATETIME
uses a combined time and date form to convert and combine a date in integer form and a numeric time expressed as seconds past midnight in UTC.
argument-1 shall be a national or alphanumeric literal.
argument-2 shall be a value in integer date form.
argument-3 shall be a value in standard numeric time form.
argument-4 is an integer specifying the offset from UTC expressed in minutes. If specified but have a value equal or less than 1439.
Note: The offset value 1439 represents 23 hours 59 minutes which is one minutes less than a day.
argument-4 must not be specified if the time portion in argument-1 is neither a UTC nor an offset format.
The returned value is a representation of the date contained in argument-2 combined with the time contained in argument-3 according to the format in argument-1.
If the format in argument-1 indicates that the returned value is to be expressed in UTC, the time portion of the returned value reflects the adjustment of the value in argument-3 by the offset in argument-4.
If the format in argument-1 indicates that the time is to be returned as an offset from UTC, the value in argument-3 is reflected directly in the time portion of the returned value and the offset in argument-4 is reflected directly in the offset portion of the returned value.
8.1.28. FORMATTED-TIME
FORMATTED-TIME Function Syntax
FORMATTED-TIME ( argument-1, argument-2, argument-3 ) ~~~~~~~~~~~~~~
FORMATTED-TIME
converts a value representing seconds past midnight formatted time of day with optional offset.
argument-1 shall be a national or alphanumeric literal.
argument-2 shall be a value in integer time form.
argument-3 is an integer specifying the offset from UTC expressed in minutes. If specified but have a value equal or less than 1439.
Note: The offset value 1439 represents 23 hours 59 minutes which is one minutes less than a day.
argument-3 must not be specified if the time portion in argument-1 is neither a UTC nor an offset format.
Returned value :
Is a representation of the standard numeric time contained in argument-2 according to the format in argument-1.
If the format in argument-1 indicates that the returned value is to be expressed in UTC, the time portion of the returned value reflects the adjustment of the value in argument-2 by the offset in argument-3.
If the format in argument-1 indicates that the time is to be returned as an offset from UTC, the value in argument-2 is reflected directly in the time portion of the returned value and the offset in argument-3 is reflected directly in the offset portion of the returned value.
8.1.29. FRACTION-PART
FRACTION-PART Function Syntax
FRACTION-PART(number) ~~~~~~~~~~~~~
This function returns that portion of number (a numeric data item or a numeric literal) that occurs to the right of the decimal point. FRACTION-PART(3.1415)
, for example, returns a value of 0.1415. This function is equivalent to the expression:
number -- FUNCTION INTEGER-PART(number)
8.1.30. HIGHEST-ALGEBRAIC
HIGHEST-ALGEBRAIC Function Syntax
HIGHEST-ALGEBRAIC(numeric-identifier) ~~~~~~~~~~~~~~~~~
This function returns the highest (i.e. largest or farthest away from 0 in a positive direction if numeric-identifier is signed) value that could possibly be stored in numeric-identifier.
8.1.31. INTEGER
INTEGER Function Syntax
INTEGER(number) ~~~~~~~
The INTEGER
function returns the greatest integer value that is less than or equal to number (a numeric literal or data item).
8.1.32. INTEGER-OF-DATE
INTEGER-OF-DATE Function Syntax
INTEGER-OF-DATE(date) ~~~~~~~~~~~~~~~
This function converts date (a numeric integer data item or literal) — presumed to be a Gregorian calendar form standard date (YYYYMMDD) — to internal date form (the number of days that have transpired since 1600/12/31).
Once in that form, mathematical operations may be performed against the internal date before it is transformed back into a date using the DATE-OF-INTEGER
(see DATE-OF-INTEGER) or DAY-OF-INTEGER
(see DAY-OF-INTEGER) function.
8.1.33. INTEGER-OF-DAY
INTEGER-OF-DAY Function Syntax
INTEGER-OF-DAY(date) ~~~~~~~~~~~~~~
This function converts date (a numeric integer data item or literal) — presumed to be a Julian calendar form standard date (YYYYDDD) — to internal date form (the number of days that have transpired since 1600/12/31).
Once in that form, mathematical operations may be performed against the internal date before it is transformed back into a date using the DATE-OF-INTEGER
(see DATE-OF-INTEGER) or DAY-OF-INTEGER
(see DAY-OF-INTEGER) function.
8.1.34. INTEGER-OF-FORMATTED-DATE
INTEGER-OF-FORMATTED-DATE Function Syntax
INTEGER-OF-FORMATTED-DATE ( argument-1, argument-2 ) ~~~~~~~~~~~~~~~~~~~~~~~~~
INTEGER-OF-FORMATTED-DATE
converts a date that is in specified format to integer date form.
argument-1 shall be a national or alphanumeric literal. The content must be either a date format or a combined date and time format.
argument-2 shall be a data item of the same type as argument-1.
If argument-1 is a date format the content of argument-2 shall be a valid date in that format.
If argument-1 is a combined date and time format, the content of argument-2 shall be a valid combined date and time in same format.
8.1.35. INTEGER-PART
INTEGER-PART Function Syntax
INTEGER-PART(number) ~~~~~~~~~~~~
Returns the integer portion of number (a numeric literal or data item).
8.1.36. LENGTH
LENGTH Function Syntax
LENGTH(string) ~~~~~~
Returns the length — in characters — of string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal).
The value returned by this function is not the number of bytes of storage occupied by string, but rather the number of actual characters making up the string. For example, if string is encoded using a double-byte character set such as Unicode UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to character sets like ASCII or EBCDIC), then calling this function with a string argument whose PICTURE is X(4)
would return a value of 4 rather than the value 8 (the actual number of bytes of storage occupied by that item).
Contrast this function with the BYTE-LENGTH
(see BYTE-LENGTH) and LENGTH-AN
(see LENGTH-AN) functions.
8.1.37. LENGTH-AN
LENGTH-AN Function Syntax
LENGTH-AN(string) ~~~~~~~~~
This function returns the length — in bytes of storage — of string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal).
This intrinsic function is identical to the BYTE-LENGTH
(see BYTE-LENGTH) function.
Note that the value returned by this function is not the number of characters making up the string, but rather the number of actual bytes of storage required to store string. For example, if string is encoded using a double-byte character set such as Unicode UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to character sets like ASCII or EBCDIC), then calling this function with a string argument whose PICTURE is X(4)
would return a value of 8 rather than the value 4.
Contrast this with the LENGTH
(see LENGTH) function.
8.1.38. LOCALE-COMPARE
LOCALE-COMPARE Function Syntax
LOCALE-COMPARE(argument-1, argument-2 [ , locale ]) ~~~~~~~~~~~~~~
The LOCALE-COMPARE
function returns a character indicating the result of comparing argument-1 and argument-2 using a culturally-preferred ordering defined by a locale.
Either or both of the 1st two arguments may be an alphanumeric literal, a group item or an elementary item appropriate to storing alphabetic or alphanumeric data. If the lengths of the two arguments are unequal, the shorter will be assumed to be padded to the right with spaces.
The two arguments will be compared, character by character, against each other until their relationship to each other can be determined. The comparison is made according to the cultural rules in effect for locale name or for the current locale if no locale argument is specified. Once that relationship is determined, a one-character alphanumeric value will be returned as follows:
- ‘<’ — If argument-1 is determined to be less than argument-2
- ‘=’ — If the two arguments are equal to each other
- ‘>’ — If argument-1 is determined to be greater than argument-2
See LOCALE Names, for a list of typically-available locale names.
8.1.39. LOCALE-DATE
LOCALE-DATE Function Syntax
LOCALE-DATE(date [, locale ]) ~~~~~~~~~~~
Converts the eight-digit Gregorian date (a numeric integer data item or literal) from yyyymmdd format to the format appropriate to the current locale. On a Windows system, this will be the “short date” format as set using Control Panel.
You may include an optional second argument to specify the locale name (group item or PIC X
identifier) you’d like to use for date formatting. If used, this second argument must be an identifier. Locale names are specified using UNIX-standard names.
8.1.40. LOCALE-TIME
LOCALE-TIME Function Syntax
LOCALE-TIME(time [, locale ]) ~~~~~~~~~~~
Converts the four- (hhmm) or six-digit (hhmmss) time (a numeric integer data item or literal) to a format appropriate to the current locale. On a Windows system, this will be the “time” format as set using Control Panel.
You may include an optional locale name (a group item or PIC X
identifier) you’d like to use for time formatting. If used, this second argument must be an identifier. Locale names are specified using UNIX-standard names.
8.1.41. LOCALE-TIME-FROM-SECONDS
LOCALE-TIME-FROM-SECONDS Function Syntax
LOCALE-TIME-FROM-SECONDS(seconds [, locale ]) ~~~~~~~~~~~~~~~~~~~~~~~~
Converts the number of seconds since midnight (a numeric integer data item or literal) to a format appropriate to the current locale. On a Windows system, this will be the “time” format as set using Control Panel.
You may include an optional locale name (a group item or PIC X
identifier) you’d like to use for time formatting. If used, this second argument must be an identifier. Locale names are specified using UNIX-standard names.
See LOCALE Names, for a list of typically-available locale names.
8.1.42. LOG
LOG Function Syntax
LOG(number) ~~~
Computes and returns the natural logarithm (base e) of number (a numeric literal or data item).
8.1.43. LOG10
LOG10 Function Syntax
LOG10(number) ~~~~~
Computes and returns the base 10 logarithm of number (a numeric literal or data item).
8.1.44. LOWER-CASE
LOWER-CASE Function Syntax
LOWER-CASE(string) ~~~~~~~~~~
This function returns the value of string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal), converted entirely to lower case.
What constitutes a “letter” (or upper/lower case too, for that manner) may be influenced through the use of a CHARACTER CLASSIFICATION
(see OBJECT-COMPUTER).
8.1.45. LOWEST-ALGEBRAIC
LOWEST-ALGEBRAIC Function Syntax
LOWEST-ALGEBRAIC(numeric-identifier) ~~~~~~~~~~~~~~~~
This function returns the lowest (i.e. smallest or farthest away from 0 in a negative direction if numeric-identifier is signed) value that could possibly be stored in numeric-identifier.
8.1.46. MAX
MAX Function Syntax
MAX(number-1 [, number-2 ]...) ~~~
This function returns the maximum value from the specified list of numbers (each number-n may be a numeric data item or a numeric literal).
8.1.47. MEAN
MEAN Function Syntax
MEAN(number-1 [, number-2 ]...) ~~~~
This function returns the statistical mean value of the specified list of numbers (each number-n may be a numeric data item or a numeric literal).
8.1.48. MEDIAN
MEDIAN Function Syntax
MEDIAN(number-1 [, number-2 ]...) ~~~~~~
This function returns the statistical median value of the specified list of numbers (each number-n may be a numeric data item or a numeric literal).
8.1.49. MIDRANGE
MIDRANGE Function Syntax
MIDRANGE(number-1 [, number-2 ]...) ~~~~~~~~
The MIDRANGE
(middle range) function returns a numeric value that is the arithmetic mean (average) of the values of the minimum and maximum numbers from the supplied list. Each number-n may be a numeric data items or a numeric literal.
8.1.50. MIN
MIN Function Syntax
MIN(number-1 [, number-2 ]...) ~~~
This function returns the minimum value from the specified list of numbers (each number-n may be a numeric data item or a numeric literal).
8.1.51. MOD
MOD Function Syntax
MOD(value, modulus) ~~~
This function returns the value of value modulo modulus (essentially the remainder from the division of value by modulus). Both arguments may be numeric data items or numeric literals. Either (or both) may have a non-integer value.
8.1.52. MODULE-CALLER-ID
MODULE-CALLER-ID Function Syntax
MODULE-CALLER-ID ~~~~~~~~~~~~~~~~
This function returns the null string if it is executed within a main program. When executed with a subprogram, it returns the entry-point name of the program that called the subprogram.
The discussion of the MODULE-TIME
(see MODULE-TIME) function includes a sample program that uses this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.53. MODULE-DATE
MODULE-DATE Function Syntax
MODULE-DATE ~~~~~~~~~~~
This function Returns the date the GnuCOBOL program that is executing the function was compiled, in the form yyyymmdd.
The discussion of the MODULE-TIME
(see MODULE-TIME) function includes a sample program that uses this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.54. MODULE-FORMATTED-DATE
MODULE-FORMATTED-DATE Function Syntax
MODULE-FORMATTED-DATE ~~~~~~~~~~~~~~~~~~~~~
This function returns the fully-formatted date and time when the program executing the function was compiled. The exact format of this returned string value may vary depending on the operating system and GnuCOBOL build type.
The discussion of the MODULE-TIME
(see MODULE-TIME) function includes a sample program that uses this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.55. MODULE-ID
MODULE-ID Function Syntax
MODULE-ID ~~~~~~~~~
This function returns the primary entry-point name (i.e. the PROGRAM-ID
or FUNCTION-ID
of the program. See IDENTIFICATION DIVISION, for information on those clauses.
The discussion of the MODULE-TIME
(see MODULE-TIME) function includes a sample program that uses this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.56. MODULE-PATH
MODULE-PATH Function Syntax
MODULE-PATH ~~~~~~~~~~~
This function returns the full path to the executable version of this GnuCOBOL program. The filename component of this value will be exactly as typed on the command line, down to the use of upper- and lower-case letters and presence (or absence) of any extension.
The discussion of the MODULE-TIME
(see MODULE-TIME) function includes a sample program that uses this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.57. MODULE-SOURCE
MODULE-SOURCE Function Syntax
MODULE-SOURCE ~~~~~~~~~~~~~
The filename of the source code of the program (as specified on the cobc
command when the program was compiled) is returned by this function.
The discussion of the MODULE-TIME
(see MODULE-TIME) function includes a sample program that uses this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.58. MODULE-TIME
MODULE-TIME Function Syntax
MODULE-TIME ~~~~~~~~~~~
This function returns the time the GnuCOBOL program was compiled, in the form hhmmss.
Since this function has no arguments, no parenthesis should be specified.
The following sample program uses all the MODULE- Functions:
IDENTIFICATION DIVISION. PROGRAM-ID. DEMOMODULE. ENVIRONMENT DIVISION. CONFIGURATION SECTION. REPOSITORY. FUNCTION ALL INTRINSIC. PROCEDURE DIVISION. 000-Main. DISPLAY "MODULE-CALLER-ID = [" MODULE-CALLER-ID ‘]’ DISPLAY "MODULE-DATE = [" MODULE-DATE ‘]’ DISPLAY "MODULE-FORMATTED-DATE = [" MODULE-FORMATTED-DATE ‘]’ DISPLAY "MODULE-ID = [" MODULE-ID ‘]’ DISPLAY "MODULE-PATH = [" MODULE-PATH ‘]’ DISPLAY "MODULE-SOURCE = [" MODULE-SOURCE ‘]’ DISPLAY "MODULE-TIME = [" MODULE-TIME ‘]’ STOP RUN .
The program produces this output when executed:
MODULE-CALLER-ID = [] MODULE-DATE = [20180522] MODULE-FORMATTED-DATE = [May 22 2018 12:43:14] MODULE-ID = [DEMOMODULE] MODULE-PATH = [/home/vince/cobolsrc/ACAS/demomodule] MODULE-SOURCE = [demomodule.cbl] MODULE-TIME = [124314]
8.1.59. MONETARY-DECIMAL-POINT
MONETARY-DECIMAL-POINT Function Syntax
MONETARY-DECIMAL-POINT ~~~~~~~~~~~~~~~~~~~~~~
MONETARY-DECIMAL-POINT
returns the character used to separate the integer portion from the fractional part of a monetary currency value according to the rules currently in effect for the locale under which your program is running.
On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the LANG
run-time environment variable (see Run Time Environment Variables) environment variable. On Windows, the Control Panel’s Regional and Language Options define the locale.
Using the DECIMAL-POINT IS COMMA
(see SPECIAL-NAMES) clause in your program will not affect the value returned by this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.60. MONETARY-THOUSANDS-SEPARATOR
MONETARY-THOUSANDS-SEPARATOR Function Syntax
MONETARY-THOUSANDS-SEPARATOR ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function returns the character used to separate the thousands digit groupings of monetary currency values according to the rules currently in effect for the locale under which your program is running.
On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the LANG
run-time environment variable (see Run Time Environment Variables) environment variable. On Windows, the Control Panel’s Regional and Language Options define the locale.
Using the DECIMAL-POINT IS COMMA
(see SPECIAL-NAMES) clause in your program will not affect the value returned by this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.61. NUMERIC-DECIMAL-POINT
NUMERIC-DECIMAL-POINT Function Syntax
NUMERIC-DECIMAL-POINT ~~~~~~~~~~~~~~~~~~~~~
This function returns the character used to separate the integer portion of a non-integer numeric item from the fractional part according to the rules currently in effect for the locale under which your program is running.
On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the LANG
run-time environment variable (see Run Time Environment Variables) environment variable. On Windows, the Control Panel’s Regional and Language Options define the locale.
Using the DECIMAL-POINT IS COMMA
(see SPECIAL-NAMES) clause in your program will not affect the value returned by this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.62. NUMERIC-THOUSANDS-SEPARATOR
NUMERIC-THOUSANDS-SEPARATOR Function Syntax
NUMERIC-THOUSANDS-SEPARATOR ~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function returns the character used to separate the thousands digit groupings of numeric values according to the rules currently in effect for the locale under which your program is running.
On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the LANG
run-time environment variable (see Run Time Environment Variables) environment variable. On Windows, the Control Panel’s Regional and Language Options define the locale.
Using the DECIMAL-POINT IS COMMA
(see SPECIAL-NAMES) clause in your program will not affect the value returned by this function.
Since this function has no arguments, no parenthesis should be specified.
8.1.63. NUMVAL
NUMVAL Function Syntax
NUMVAL(string) ~~~~~~
The NUMVAL
function converts a string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal) to its corresponding numeric value.
The string must have any of the following formats, where ’#’ represents a sequence of one or more decimal digits:
There must be at least one digit character in the string.
Leading and/or trailing spaces are allowed, as are spaces before the first digit.
The character period in argument-1 string, represents the decimal separator. The character comma in argument-1 represents the grouping separator. When the DECIMAL-POINT IS COMMA
clause is specified, the character comma shall be used in argument-1 to represent the decimal separator and the character period shall be used to represent the grouping separator.
Note: Locale-based functionality equivalent to NUMVAL
can be obtained by using the NUMVAL-C
function with the LOCALE
keyword. A currency sign is optional in NUMVAL-C
. The locale category LC_MONETARY
will be used because there is no sign convention specified in locale category LC_NUMERIC
.
Returned values:
The returned value is the numeric value represented by string.
If it contains a CR
, DB
, or the minus sign (‘-’), the returned value is negative.
8.1.64. NUMVAL-C
NUMVAL-C Function Syntax
NUMVAL-C (string [, symbol ] ~~~~~~~~ [, LOCALE locale-name-1 ] [, ANYCASE ])
This function converts a string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal) representing a currency value to its corresponding numeric value.
The currency string if any, and any grouping separators preceding the decimal separator are ignored. Optionally, the currency string, sign convention, grouping separator and the decimal separator permitted in the character string may be specified by locale category LC-MONETARY
, or the currency string may be specified by symbol.
The optional symbol character represents the currency symbol (a non-space single-character group item, USAGE DISPLAY
elementary item or alphanumeric literal) that may be used as the currency character in string. Any spaces including leading or trailing are ignored. If no symbol is specified, the value that would be returned by the CURRENCY-SYMBOL
intrinsic function (see CURRENCY-SYMBOL) will be used.
If this references the LOCALE
:
Changing the currency symbol via the SPECIAL-NAMES
paragraph’s CURRENCY SYMBOL
setting will not affect the value returned by this function.
While NUMVAL-C
will always use the currency symbol that is specified via the SPECIAL-NAMES
paragraph’s CURRENCY SYMBOL
(or the system default which is currently always ‘$’).
string may have any of the following formats, where ’#’ represents a sequence of one or more decimal digits and ’$’ represents the symbol character:
There must be at least one digit character in the string.
Leading and/or trailing spaces are allowed, as are spaces before and/or after the currency symbol, sign, CR and DB characters.
If the ANYCASE
keyword is used the matching rules for detecting a currency string in argument-1 are case-insensitive. If the ANYCASE
keyword is not specified, the matching rules are case-sensitive.
If neither symbol nor the LOCALE
keyword is specified, there shall be only one currency string used, either the default currency sign or a currency string specified in the SPECIAL-NAMES
paragraph.
The returned value is the numeric value represented by string.
When the LOCALE
keyword is specified, the returned value is negative if string contains a negative sign.
When the LOCALE
keyword is not specified, the returning value is negative if string contains CR, DB, or a minus sign.
8.1.64B. NUMVAL-C-2
NUMVAL-C Function Syntax
NUMVAL-C (argument-1 [, argument-2 ] ~~~~~~~~ [, LOCALE locale-name-1 ] [, ANYCASE ])
This function returns the numeric value represented by the character string specified by argument-1 and defined as alphanumeric.
argument-2, the currency string if any, and any grouping separators preceding the decimal separator are ignored. Optionally, the currency string, sign convention, grouping separator and the decimal separator permitted in the character string may be specified by locale category LC-MONETARY
, or the currency string may be specified by argument-2.
The optional alphanumeric argument-2 character represents the currency symbol (a non-space and at least one single-character item, that may be used as the currency character in argument-1. Any spaces including leading or trailing are ignored. If no argument-2 is specified, the value that would be returned by the CURRENCY-SYMBOL
intrinsic function (see CURRENCY-SYMBOL) will be used. argument-2 must not contain any of the digits - through 9, characters ‘*’, ‘+’, ‘-’, ‘,’ or ‘.’; or the two consecutive letters CR
or DB
, whether upper or lower case or a combination of both.
argument-2 specifies a currency string that may appear in argument-1.
If the ANYCASE
keyword is specified, the matching rules for detecting a currency string in argument-1 are case-insensitive. If not specified, the matching rules are case-sensitive.
If neither argument-2 nor the LOCALE
keyword is specified, there shall be only one currency string used, either the default currency sign or a currency string specified in the SPECIAL-NAMES
paragraph.
While NUMVAL-C
will always use the currency symbol that is specified via the SPECIAL-NAMES
paragraph’s CURRENCY SYMBOL
(or the system default which is currently always ’$’) argument-1 shall have any of the following formats, where ’#’ represents a sequence of one or more decimal digits and ’$’ represents the symbol character:
There must be at least one digit character in the string.
Leading and/or trailing spaces are allowed, as are spaces before and/or after the currency symbol, sign, CR and DB characters.
The returned value is the numeric value represented by argument-1.
When the LOCALE
keyword is specified, the returned value is negative if string contains a negative sign and when not specified, the returning value is negative if string contains CR, DB, or a minus sign.
8.1.65. NUMVAL-F
NUMVAL-F Function Syntax
NUMVAL-F(char) ~~~~~~~~
This function converts a string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal) representing a floating-point value to its corresponding numeric value.
There must be at least one digit character both before and after the E
in the string.
Leading and/or trailing spaces are allowed, as are spaces before and/or after any sign characters.
8.1.66. ORD
ORD Function Syntax
ORD(char) ~~~
This function returns the ordinal position in the program character set (usually ASCII) corresponding to the 1st character of char argument (a group item, USAGE DISPLAY
elementary item or alphanumeric literal).
For example, assuming the program is using the standard ASCII collating sequence, ORD('!')
returns 34 because ‘!’ is the 34th ASCII character. If you are using this function to convert an ASCII character to its numeric value, you must subtract one from the result.
The following code is an alternative approach when you just wish to convert an ASCII character to its numeric equivalent:
01 Char-Value. 05 Numeric-Value USAGE BINARY-CHAR. … MOVE "character" TO Char-Value
Numeric-Value
now has the numeric value of character
.
8.1.67. ORD-MAX
ORD-MAX Function Syntax
ORD-MAX(char-1 [, char-2 ]...) ~~~~~~~
This function returns the ordinal position in the argument list corresponding to the char-n whose 1st character has the highest position in the program collating sequence (usually ASCII).
For example, assuming the program is using the standard ASCII collating sequence, ORD-MAX('Z', 'z', '!')
returns 2 because the 2nd character in the argument list (the ASCII character ‘z’) occurs after ‘Z’ and ‘!’ in the program collating sequence. Each char-n argument may be a group item, USAGE DISPLAY
elementary item or alphanumeric literal.
8.1.68. ORD-MIN
ORD-MIN Function Syntax
ORD-MIN(char-1 [, char-2 ]...) ~~~~~~~
This function returns the ordinal position in the argument list corresponding to the char-n whose 1st character has the lowest position in the program collating sequence (usually ASCII).
For example, assuming the program is using the standard ASCII collating sequence, ORD-MIN('Z', 'z', '!')
returns 3 because the 3rd character in the argument list (the ASCII character ‘!’) occurs before ‘Z’ and ‘z’ in the program collating sequence. Each char-n argument may be a group item, USAGE DISPLAY
elementary item or alphanumeric literal.
8.1.69. PI
PI Function Syntax
PI ~~
This function returns the mathematical constant PI. The maximum precision with which this value may be returned is 3.1415926535897932384626433832795029.
Since this function has no arguments, no parenthesis should be specified.
8.1.70. PRESENT-VALUE
PRESENT-VALUE Function Syntax
PRESENT-VALUE(rate, value-1 [, value-2 ]) ~~~~~~~~~~~~~
The PRESENT-VALUE
function returns a value that approximates the present value of a series of future period-end amounts specified by the various value-n arguments at a discount rate specified by the rate argument.
All arguments are numeric data items and/or numeric literals.
8.1.71. RANDOM
RANDOM Function Syntax
RANDOM[(seed)] ~~~~~~
This function returns a pseudo-random non-integer value in the range 0 to 1 (for example, 0.123456789).
The purpose of the optional seed argument, is to initialize the chain of pseudo-random numbers that will be returned by the function. Not only will calls to this function using the same seed value return the same pseudo-random number, but so will all subsequent executions of the function without a seed. This is actually a good thing when you are testing your program because you can rely on always receiving the same sequence of “random” numbers if you always start using the same seed.
The seed may be any form of literal or data item. If seed is numeric, its numeric value will serve as the seed value. If seed is alphanumeric, a value for it will be determined as if it were used as an argument to NUMVAL
(see NUMVAL).
Take, for example, the following sample program:
IDENTIFICATION DIVISION. PROGRAM-ID. DEMORANDOM. DATA DIVISION. WORKING-STORAGE SECTION. 01 Pseudo-Random-Number USAGE COMP-1. PROCEDURE DIVISION. 000-Main. MOVE FUNCTION RANDOM(1) TO Pseudo-Random-Number DISPLAY Pseudo-Random-Number PERFORM 4 TIMES MOVE FUNCTION RANDOM TO Pseudo-Random-Number DISPLAY Pseudo-Random-Number END-PERFORM STOP RUN .
Every time this program is executed, it will produce the same output, because the same sequence of pseudo-random numbers will be generated:
0.41 0.18467 0.63340002 0.26499999 0.19169
It is worth mentioning that if the first execution of RANDOM
in your program lacks a seed argument, the result will be exactly as if that execution were coded with a seed argument value of 1.
Once your program has been thoroughly tested, you’ll want different sequences to be generated each time the program runs. One possible way to accomplish this is to use a seed that is likely to be different every time the program is executed, as is likely to be the case if the first MOVE
statement in the previous example were replaced by this:
MOVE RANDOM(FUNCTION CURRENT-DATE(1:16)) TO Pseudo-Random-Number
The first 16 characters returned by the CURRENT-DATE
(see CURRENT-DATE) function will be a number in the format YYYYMMDDhhmmssnn
, where YYYYMMDD
is the current calendar date and hhmmssnn
is the current time of day to the one one-hundredth of a second. Since two different executions of the program will never get identical CURRENT-DATE
values (unless they are executed in extremely close time frames to one another), using those first sixteen characters as the RANDOM
seed will guarantee that receiving a duplicate sequence of pseudo-random numbers in two different executions of the program will be highly unlikely.
8.1.72. RANGE
RANGE Function Syntax
RANGE(number-1 [, number-2 ]...) ~~~~~
The RANGE
function returns a value that is equal to the value of the maximum number-n in the argument list minus the value of the minimum number-n argument.
All number-n arguments are numeric data items and/or numeric literals.
8.1.73. REM
REM Function Syntax
REM(number,divisor) ~~~
This function returns a numeric value that is the remainder of number divided by divisor. Both arguments must be numeric data items or numeric literals.
8.1.74. REVERSE
REVERSE Function Syntax
REVERSE(string) ~~~~~~~
This function returns the byte-by-byte reversed value of string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal).
8.1.75. SECONDS-FROM-FORMATTED-TIME
SECONDS-FROM-FORMATTED-TIME Function Syntax
SECONDS-FROM-FORMATTED-TIME(format,time) ~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function decodes the string time — whose value represents a formatted time — and returns the total number of seconds that string represents.
The time string must contain hours, minutes and seconds. The time argument may be specified as a group item, USAGE DISPLAY
elementary item or an alphanumeric literal.
The format argument is a string (a group item, USAGE DISPLAY
elementary item or an alphanumeric literal) documenting the format of time using hh
, mm
and ss
to denote where the respective time information can be found. Any other characters found in format represent character positions that will be ignored. For example, a format of hhmmss
indicates that time will be treated as a six-digit string value where the first two characters are the number of hours, the next two represent minutes and the last two represent seconds. A format of hh:mm:ss
, however, describes time as an eight-character string where characters 3 and 6 will be ignored.
8.1.76. SECONDS-PAST-MIDNIGHT
SECONDS-PAST-MIDNIGHT Function Syntax
SECONDS-PAST-MIDNIGHT ~~~~~~~~~~~~~~~~~~~~~
This function returns the current time of day expressed as the total number of elapsed seconds since midnight.
Since this function has no arguments, no parenthesis should be specified.
8.1.77. SIGN
SIGN Function Syntax
SIGN(number) ~~~~
The SIGN
function returns a -1 if the value of number (a numeric literal or numeric data item) is negative, a zero if the value of number is exactly zero and a 1 if the value of number if greater than 0.
8.1.78. SIN
SIN Function Syntax
SIN(angle) ~~~
This function determines and returns the trigonometric sine of angle (a numeric literal or numeric data item).
The angle is assumed to be a value expressed in radians. If you need to determine the sine of an angle measured in degrees, you first need to convert that angle to radians as follows:
COMPUTE radians = ( degrees * FUNCTION PI) / 180
8.1.79. SQRT
SQRT Function Syntax
SQRT(number) ~~~~
The SQRT
function returns a numeric value that approximates the square root of number (a numeric data item or numeric literal with a non-negative value).
The following two statements produce identical results:
01 Result PIC 9(4).9(10). … MOVE FUNCTION SQRT(15) TO Result COMPUTE Result = 15 ^ 0.5
8.1.80. STANDARD-DEVIATION
STANDARD-DEVIATION Function Syntax
STANDARD-DEVIATION(number-1 [, number-2 ]...) ~~~~~~~~~~~~~~~~~~
This function returns the statistical standard deviation of the list of number-n arguments (numeric data items or numeric literals).
8.1.81. STORED-CHAR-LENGTH
STORED-CHAR-LENGTH Function Syntax
STORED-CHAR-LENGTH(string) ~~~~~~~~~~~~~~~~~~
Returns the length — in bytes — of the specified string
(a group item, USAGE DISPLAY
elementary item or alphanumeric literal), minus the total number of trailing spaces, if any.
8.1.82. SUBSTITUTE
SUBSTITUTE Function Syntax
SUBSTITUTE(string, from-1, to-1 [, from-n, to-n ]...) ~~~~~~~~~~
This function parses string, replacing all occurrences of from-n strings with the corresponding to-n strings.
The from-n strings must match sequences in string exactly with regard to value and case.
A from-n string does not have to be the same length as its corresponding to-n string.
All arguments are group items, USAGE DISPLAY
elementary items or alphanumeric literals.
A null to-n string will be treated as a single space.
8.1.83. SUBSTITUTE-CASE
SUBSTITUTE-CASE Function Syntax
SUBSTITUTE-CASE(string, from-1, to-1 [, from-n, to-n ]...) ~~~~~~~~~~~~~~~
The SUBSTITUTE-CASE
function operates the same as the SUBSTITUTE
(see SUBSTITUTE) function, except that from-n string matching is performed without regard to case.
All arguments are group items, USAGE DISPLAY
elementary items or alphanumeric literals.
8.1.84. SUM
SUM Function Syntax
SUM(number-1 [, number-2 ]...) ~~~
The SUM
function returns a value that is the sum of number-n arguments (these may be numeric data items or numeric literals).
8.1.85. TAN
TAN Function Syntax
TAN(angle) ~~~
This function determines and returns the trigonometric tangent of angle (a numeric literal or numeric data item).
The angle is assumed to be a value expressed in radians. If you need to determine the tangent of an angle measured in degrees, you first need to convert that angle to radians as follows:
COMPUTE radians = ( degrees * FUNCTION PI) / 180
8.1.86. TEST-DATE-YYYYMMDD
TEST-DATE-YYYYMMDD Function Syntax
TEST-DATE-YYYYMMDD(date) ~~~~~~~~~~~~~~~~~~
This function determines if the supplied date argument (a numeric integer data item or literal) is a valid date.
A valid date is one of the form yyyymmdd in the range 1601/01/01 to 9999/12/31, with no more than the expected maximum number of days in the month, accounting for leap year.
If the date is valid, a 0 value is returned. If it isn’t, a value of 1, 2 or 3 is returned signalling the problem lies with the year, month or day, respectively.
8.1.87. TEST-DAY-YYYYDDD
TEST-DAY-YYYYDDD Function Syntax
TEST-DATE-YYYYDDD(date) ~~~~~~~~~~~~~~~~~
This function determines if the supplied date (a numeric integer data item or literal) is a valid date.
A valid date is one of the form yyyyddd
in the range 1601001 to 9999365. Leap year is accounted for in determining the maximum number of days in a year.
If the date is valid, a 0 value is returned. If it isn’t, a value of 1 or 2 is returned signalling the problem lies with the year or day, respectively.
8.1.88. TEST-FORMATTED-DATETIME
TEST-FORMATTED-DATETIME Function Syntax
TEST-FORMATTED-DATETIME ( argument-1, argument-2 ) ~~~~~~~~~~~~~~~~~~~~~~~
TEST-FORMATTED-DATETIME
tests whether a date literal representing a date, a time or a combined date and time is valid according to the specified format.
argument-1 shall be a national or alphanumeric literal. The content must be either a date format or a combined date and time format.
argument-2 must be a data item of the same type as argument-1.
Returned value:
If no format or range problems occur during evaluation of argument-2 according to the format in argument-1, the returned value is zero. Otherwise the returned value is the ordinal character position at which the first error in argument-2 was detected.
8.1.89. TEST-NUMVAL
TEST-NUMVAL Function Syntax
TEST-NUMVAL(string) ~~~~~~~~~~~
The TEST-NUMVAL
function evaluates string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal) for being appropriate for use as the string argument to a NUMVAL
(see NUMVAL) function, returning to a integer a zero value if it is appropriate otherwise if one or more characters are in error, the position of the first character in error or the length of the field plus one for other cases such as all spaces.
Note that these errors include but are not limited to: argument (string) is zero length, contains only spaces or contains valid characters but is incomplete, such as the string ‘+.’.
8.1.90. TEST-NUMVAL-C
TEST-NUMVAL-C Function Syntax
TEST-NUMVAL-C(string[,symbol]) ~~~~~~~~~~~~~
This function evaluates string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal) for being appropriate for use as the string argument to a NUMVAL-C
(see NUMVAL-C) function, returning to a integer a zero value if it is appropriate otherwise if one or more characters are in error, the position of the first character in error or the length of the field plus one for other cases such as all spaces.
Note that these errors include but are not limited to: argument (string) is zero length, contains only spaces or contains valid characters but is incomplete, such as the string ‘+.’.
The optional symbol argument serves the same function — and has the same default and possible values — as the corresponding argument of the NUMVAL-C
function.
8.1.91. TEST-NUMVAL-F
TEST-NUMVAL-F Function Syntax
TEST-NUMVAL-F(string) ~~~~~~~~~~~~~
This function evaluates string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal) for being appropriate for use as the string argument to a NUMVAL-F
(see NUMVAL-F) function, returning to a integer a zero value if it is appropriate otherwise if one or more characters are in error, the position of the first character in error or the length of the field plus one for other cases such as all spaces.
Note that these errors include but are not limited to: argument (string) is zero length, contains only spaces or contains valid characters but is incomplete, such as the string ‘+.’.
8.1.92. TRIM
TRIM Function Syntax
TRIM(string [, LEADING|TRAILING ]) ~~~~ ~~~~~~~ ~~~~~~~~
This function removes LEADING
or TRAILING
spaces from string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal).
The second argument is specified as a keyword, not a quoted string or identifier. If no second argument is specified, both leading and trailing spaces will be removed. The case (upper, lower or mixed) of this argument is irrelevant.
8.1.93. UPPER-CASE
UPPER-CASE Function Syntax
UPPER-CASE(string) ~~~~~~~~~~
This function returns the value of string (a group item, USAGE DISPLAY
elementary item or alphanumeric literal), converted entirely to upper case.
What constitutes a “letter” (or upper/lower case too, for that manner) may be influenced through the use of a CHARACTER CLASSIFICATION
(see OBJECT-COMPUTER).
8.1.94. VARIANCE
VARIANCE Function Syntax
VARIANCE(number-1 [, number-2 ]...) ~~~~~~~~
This function returns the statistical variance of the specified list of number-n arguments (these may be numeric data items or numeric literals).
8.1.95. WHEN-COMPILED
WHEN-COMPILED Function Syntax
WHEN-COMPILED ~~~~~~~~~~~~~
The WHEN-COMPILED
intrinsic function, not to be confused with the WHEN-COMPILED
(see Special Registers) special register, returns the date and time the program was compiled, in ASCII.
Since this function has no arguments, no parenthesis should be specified.
Unlike the WHEN-COMPILED
special register, which has an ASCII value of the compilation date/time in the format mm/dd/yyhh.mm.ss
, the WHEN-COMPILED
intrinsic function returns the compilation date/time as an ASCII string in the format yyyymmddhhmmssnnooooo
, where yyyymmdd
is the date, hhmmss
is the time, nn
is the hundredths of a second component of the compilation time, if available (or 00
if it isn’t) and ooooo
is the time zone offset from GMT.
If the -fintrinsics=WHEN-COMPILED switch or -fintrinsics=ALL switch is specified to the compiler or the REPOSITORY
(see REPOSITORY) paragraph specifies either FUNCTION WHEN-COMPILED INTRINSIC
or FUNCTION ALL INTRINSIC
, then references to WHEN-COMPILED
(without a leading FUNCTION
keyword will always reference this intrinsic function and there will be no way to access the WHEN-COMPILED
special register.
8.1.96. YEAR-TO-YYYY
YEAR-TO-YYYY Function Syntax
YEAR-TO-YYYY(yy [, yy-cutoff [, yy-execution-time ]]) ~~~~~~~~~~~~
YEAR-TO-YYYY
converts yy — a two-digit year — to a four-digit format (yyyy
).
The optional yy-cutoff argument is the year cutoff used to delineate centuries; if yy meets or exceeds this cutoff value, the result will be 19yy; if yy is less than the cutoff, the result will be 20yy. The default cutoff value if no second argument is given will be 50.
The optional yy-execution-time argument (a numeric integer data item or literal) The default execution time value if no third argument is given will be now equivalent to specifying (FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))).
All arguments must be numeric data items or numeric literals.
8.1.97. BOOLEAN-OF-INTEGER
BOOLEAN-OF-INTEGER Function Syntax
BOOLEAN-OF-INTEGER(argument-1 argument-2) ~~~~~~~~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
BOOLEAN-OF-INTEGER
returns a boolean item of usage bit representing the binary value of argument-1. argument-2 specifies the length of the boolean data item that is returned.
argument-1 must be a positive integer.
argument-2 must be a positive non-zero integer
Returned value is a boolean item of usage bit that has the same bit configuration as the binary representation of the value of argument-1, where the rightmost boolean position is the low-order binary digit. The boolean value is zero-filled or truncated on the left, if necessary, in order to return a boolean item whose length is specified by argument-2 in therms of boolean positions.
8.1.98. CHAR-NATIONAL
CHAR-NATIONAL Function Syntax
CHAR-NATIONAL(argument-1) ~~~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
CHAR-NATIONAL
returns a one character value that is a character in the national program collating sequence having the ordinal position equal to the value of the argument.
argument-1 must be a integer and greater than zero and less than or equal to the number of positions in the national program collating sequence.
8.1.99. DISPLAY-OF
DISPLAY-OF Function Syntax
DISPLAY-OF(argument-1 [ argument-2] ) ~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
DISPLAY-OF
returns a character string containing the alphabetic coded character set representation of the national characters in the argument.
argument-1 must be of class national.
argument-2 must be a of class alphabetic or alphanumeric and is one character position in length. It specifies an alphanumeric substitution character for use in conversion of national characters for which there is no corresponding alphanumeric character.
A character string is returned with each national character of argument-1 converted to its corresponding alphanumeric character representation, if any.
If argument-2 is specified, the alphanumeric substitution character is returned for each national character in argument-1 that has no corresponding alphanumeric character representation.
If argument-2 is un-specified, and argument-1 contains a national character for which there is no corresponding alphanumeric character representation, an substitution character is used as the corresponding alphanumeric character and the EC-DATA-CONVERSION exception condition is set.
The length of the returned value is the number of character positions of usage display required to hold the converted argument and depends on the number of characters contained in argument-1.
8.1.100. EXCEPTION-FILE-N
EXCEPTION-FILE-N Function Syntax
EXCEPTION-FILE-N ~~~~~~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
EXCEPTION-FILE-N
returns a national character string that is the I/O status value and file-name of the file connector, if any, associated with the last exception status.
The value returned has a length that is based on its contents and the concents are as follows:
If the last exception status is not an EC-I-O
exception condition, the returned value is two national zeros.
The returned value is two national spaces when the last exception status indicates an EC-I-O
exception condition that originates from one of the following statements:
- a
RAISE
statement. - an
EXIT
or aGOBACK
statement with aRAISING
phrase that specifies anEC-I-O
exception-name.
Otherwise the returned value is a character string that is as long as is needed to contain the I-O status value and the filename. The first two characters are the I-O status value in national characters. The succeeding characters contain the file-name exactly as specified in the SELECT
clause converted at runtime to the runtime national character set.
The documentation of the CBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine illustrates the use of this function.
8.1.101. EXCEPTION-LOCATION-N
EXCEPTION-LOCATION-N Function Syntax
EXCEPTION-LOCATION-N ~~~~~~~~~~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
EXCEPTION-LOCATION-N
returns an national character string containing exception information from the most-recently failing statement. The information is returned to a 1023 character string in one of the following formats, depending on the nature of the failure:
- primary-entry-point-name; paragraph OF section; statement-number
- primary-entry-point-name; section; statement-number
- primary-entry-point-name; paragraph; statement-number
- primary-entry-point-name; statement-number
Since this function has no arguments, no parenthesis should be specified.
The program must be compiled with the -debug switch, -ftraceall switch or -g switch for this function to return any meaningful information.
The documentation of the CBL_ERROR_PROC
built-in system subroutine (see CBL_ERROR_PROC) built-in subroutine illustrates the use of this function.
8.1.102. INTEGER-OF-BOOLEAN
INTEGER-OF-BOOLEAN Function Syntax
INTEGER-OF-BOOLEAN(argument-1) ~~~~~~~~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
INTEGER-OF-BOOLEAN
returns the numeric value of the boolean string in argument-1 which is class boolean.
Returned value as argument-1 is assigned to a temporary boolean data item of usage bit described with the same number of boolean positions.
The unsigned binary value represented by the same bit configuration as the bit configuration of that temporary boolean data item is determined.
Note: Binary representation is a mathematical concept. It is not required that this representation be the same as a COBOL representation.
8.1.103. NATIONAL-OF
NATIONAL-OF Function Syntax
NATIONAL-OF(argument-1 [argument-2] ) ~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
NATIONAL-OF
returns a character string containing the national character representation of the characters in the argument which must be of class boolean.
A character string is returned with each alphanumeric character in argument-1 converted to its corresponding national coded character set representation.
If argument-2 is specified, each character in argument-1 that has no corresponding national representation is converted to the substitution character specified by argument-2.
If argument-2 is unspecified and argument-1 contains an alphanumeric character for which there is no corresponding national character representation, a substitution character is used as the corresponding national character and the EC-DATA-CONVERSION
exception condition is set to exist.
The length of the returned value is the number of character positions of usage national required to hold the converted argument and depends on the number of characters contained in argument-1.
8.1.104. STANDARD-COMPARE
STANDARD-COMPARE Function Syntax
STANDARD-COMPARE(argument-1 argument-2 [ordering-name-1] [argument-4] ) ~~~~~~~~~~~~~~~~
This option is not yet implemented.
The included file NEWS will indicate when it is.
STANDARD-COMPARE
returns a character indicating the result of comparing argument-1 as a alphanumeric and argument-2 using a cultural ordering table.
- argument-1 shall be of class alphabetic, alphanumeric, or national.
- argument-2 shall be of class alphabetic, alphanumeric, or national.
- argument-1 and argument-2 may be of different classes.
- Neither argument-1 nor argument-2 shall be a zero-length literal.
- ordering-name-1, if specified, shall be associated with a cultural ordering table in the
ORDER TABLE
clause of theSPECIAL-NAMES
paragraph. ordering-name-1 identifies the ordering table to be used for the comparison. If ordering-name-1 is not specified, the default ordering table ‘ISO14651_2010_TABLE1’ described in Appendix A of ISO/IEC 14651:2011 shall be used. - argument-4, if specified, shall be a positive nonzero integer.
Returned values:
- If argument-4 is unspecified, the highest level defined in the ordering table is used for the comparison.
- If the cultural ordering table is not available on the processor, or the specified ordering level is not available, or the level number specified by argument-4 is not defined in the ordering table, the
EC-ORDER-NOT-SUPPORTED
exception condition is set. - If the arguments are of different classes, and one is national, the other argument is converted to class national for purposes of comparison.
- For purposes of comparison, trailing spaces are truncated from the operands except that an operand consisting of all spaces is truncated to a single space.
- argument-1 and argument-2 are compared in accordance with the ordering table and ordering level being used.
Note: This comparison is culturally sensitive and the default ordering table is acceptable for most cultures. It is not necessarily a character-by-character comparison and not necessarily a case-sensitive comparison. In order to use this function, users should understand the types of comparisons specified by ISO/IEC 14651:2D11 and the ordering tables in use for their installation.
- The returned value is:
- ‘=’
-
the arguments compare equal,
- ‘-=.:’
-
argument-1 is less than argument-2,
- ‘:>’
argument-1 is greater than argument-2.
- The length of the returned value is 1.
8.2. Built-In System Subroutines
There are a number of built-in system subroutines included with GnuCOBOL.
Generally, these routines are intended to match those available in Micro Focus COBOL, ACUCOBOL and directly for GnuCOBOL.
It is recommended to change the CBL_OC routines to CBL_GC for forward compatibility as at some point they will be removed as they are a hangover from Open Cobol.
Prefix explanation:
C$
-
–>
ACU
CBL_
-
–>
MF
CBL_GC_
(For backwards compatibility some routines are also available as
CBL_OC_
as well): but these wonderful extensions are only available with GnuCOBOL.
These routines, all executed via their upper-case names via the CALL
statement (see CALL), are capable of performing the following functions:
- Changing the current directory
- Copying files
- Creating a directory
- Creating, Opening, Closing, Reading and Writing byte-stream files
- Deleting directories (folders)
- Deleting files
- Determining how many arguments were passed to a subroutine
- Getting file information (size and last-modification date/time)
- Getting the length (in bytes) of an argument passed to a subroutine
- Justifying a field left-, right- or center-aligned
- Moving files (a destructive “copy”)
- Putting the program “to sleep”, specifying the sleep time in seconds
- Putting the program “to sleep”, specifying the sleep time in nanoseconds; Caveat: although you’ll express the time in nanoseconds, Windows systems will only be able to sleep at a millisecond granularity
- Retrieving information about the currently-executing program
- Submitting a command to the shell environment appropriate for the version of GnuCOBOL you are using for execution
Early versions of Micro Focus COBOL allowed programmers to access various runtime library routines by using a single two-digit hexadecimal number as the entry-point name. These were known as call-by-number routines. Over time, Micro Focus COBOL evolved, replacing most of the call-by-number routines with ones accessible using a more conventional call-by-name technique.
Most of the call-by-number routines have evolved into even more powerful call-by-name routines, many of which are supported by GnuCOBOL.
Some of the original call-by-number routines never evolved call-by-name equivalents; GnuCOBOL supports some of these routines.
The following sections describe the various built-in subroutines. All subroutine arguments are mandatory except where explicitly noted to the contrary. Any subroutine returning a value to the RETURN-CODE
special register (see Special Registers) could utilize the RETURNING
clause on the CALL
statement to return the result back to the full-word binary data item of your choice.
8.2.1. C$CALLEDBY
C$CALLEDBY Built-In Subroutine Syntax
CALL "C$CALLEDBY" USING prog-name-area ~~~~ ~~~~~
This routine returns the name of the program that called the currently-executing program. The program name will be returned, left-justified and space filled, in prog-name-area argument, which should be a PIC X
elementary item or a group item. If prog-name-area is too small to receive the entire program name, the program name value will be truncated (on the right) to fit.
The RETURN-CODE
special register (see Special Registers) will be set to one of the following values:
-1 | An error occurred. The prog-name-area contents will be unchanged. |
0 | The program calling C$CALLEDBY was not called by any other program (in other words, it is a main program). The prog-name-area contents will be set entirely to spaces. |
1 | The program calling C$CALLEDBY was indeed called by another program, and that program’s name has been saved in prog-name-area. |
8.2.2. C$CHDIR
C$CHDIR Built-In Subroutine Syntax
CALL "C$CHDIR" USING directory-path, result ~~~~ ~~~~~
This routine makes directory-path (an alphanumeric literal or identifier) the current directory.
The return code of the operation is returned both in the result argument (any non-edited numeric identifier) as well as in the RETURN-CODE
special register (see Special Registers). The return code of the operation will be either 0=Success or 128=failure.
The directory change remains in effect until the program terminates (in which the original current directory at the time the program was started will be automatically restored) or until another C$CHDIR
or a CBL_CHANGE_DIR
built-in system subroutine (see CBL_CHANGE_DIR) is executed.
8.2.3. C$COPY
C$COPY Built-In Subroutine Syntax
CALL "C$COPY" USING src-file-path, dest-file-path, 0 ~~~~ ~~~~~
Use this subroutine to copy file src-file-path to dest-file-path as if it were done via the cp
(Unix/OSX) or COPY
(Windows) command.
Both file path arguments may be alphanumeric literals or identifiers.
The third argument is required, but is unused.
If the attempt to copy the file fails (for example, it or the destination directory doesn’t exist), the RETURN-CODE
special register (see Special Registers) will be set to 128; on successful completion it will be set to 0.
8.2.4. C$DELETE
C$DELETE Built-In Subroutine Syntax
CALL "C$DELETE" USING file-path, 0 ~~~~ ~~~~~
This routine deletes the file specified by the file-path argument (an alphanumeric literal or identifier) just as if that were done using the rm
(Unix/OSX) or ERASE
(Windows) command.
The second argument is required, but is unused.
If the attempt to delete the file fails (for example, it doesn’t exist), the RETURN-CODE
special register (see Special Registers) will be set to 128; on successful completion it will be set to 0.
8.2.5. C$FILEINFO
C$FILEINFO Built-In Subroutine Syntax
CALL "C$FILEINFO" USING file-path, file-info ~~~~ ~~~~~
With this routine you may retrieve the size of the file specified as the file-path argument (an alphanumeric literal or identifier) and the date/time that file was last modified. File size information may not be available in the particular GnuCOBOL build / Operating System combination you are using and may therefore always be returned as zero. The information is returned to the file-info argument, which is defined as the following 16-byte area:
01 File-Info. 05 File-Size-In-Bytes PIC 9(18) COMP. 05 Mod-YYYYMMDD PIC 9(8) COMP. *> Modification Date 05 Mod-HHMMSS00 PIC 9(8) COMP. *> Modification Time
The last two decimal digits in the modification time will always be 00.
If the subroutine is successful, a value of 0 will be returned in the RETURN-CODE
special register (see Special Registers). Failure to retrieve the needed statistics on the file will cause a RETURN-CODE
special register value of 35 to be passed back. Supplying less than two arguments will generate a 128 RETURN-CODE
special register value.
8.2.6. C$GETPID
C$GETPID Built-In Subroutine Syntax
CALL "C$GETPID" ~~~~
Use this subroutine to return the PID (process ID) of the executing GnuCOBOL program. The PID value is returned into the RETURN-CODE
special register (see Special Registers).
There are no arguments to this routine.
8.2.7. C$JUSTIFY
C$JUSTIFY Built-In Subroutine Syntax
CALL "C$JUSTIFY" USING data-item, "justification-type" ~~~~ ~~~~~
Use C$JUSTIFY
to left, right or center-justify an alphabetic, alphanumeric or numeric edited data-item. The optional justification-type argument indicates the type of the justification to be performed. Its value is interpreted as follows:
- ‘C’
-
the value will be centered
- ‘R’
-
the value will be right-justified, space-filled to the left
- ‘L’
the value will be left-justified, space-filled to the right
If it begins with anything else, or is absent, it will be treated as if it is present and begins with a capital ‘R’
8.2.8. C$MAKEDIR
C$MAKEDIR Built-In Subroutine Syntax
CALL "C$MAKEDIR" USING dir-path ~~~~ ~~~~~
With this routine you may create a new directory — the name of which is supplied as the dir-path argument (an alphanumeric literal or identifier).
Only the lowest-level directory (last) in the specified path can be created — all others must already exist. This subroutine will not behave as a mkdir -p
(Unix) or mkdir /p
(Windows).
The RETURN-CODE
special register (see Special Registers) will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
8.2.9. C$NARG
C$NARG Built-In Subroutine Syntax
CALL "C$NARG" USING arg-count-result ~~~~ ~~~~~
This subroutine returns the number of arguments passed to the program that calls it back to in the numeric field arg-count-result. When called from within a user-defined function, a value of one (1) is returned if any arguments were passed to the function or a zero (0) otherwise.
When called from a main program, the returned value will always be 0.
8.2.10. C$PARAMSIZE
C$PARAMSIZE Built-In Subroutine Syntax
CALL "C$PARAMSIZE" USING argument-number ~~~~ ~~~~~
This subroutine returns the size (in bytes) of the subroutine argument supplied using the argument-number parameter (a numeric literal or data item).
The size is returned in the RETURN-CODE
special register (see Special Registers).
If the specified argument does not exist, or an invalid argument number is specified, a value of 0 is returned.
8.2.11. C$PRINTABLE
C$PRINTABLE Built-In Subroutine Syntax
CALL "C$PRINTABLE" USING data-item [ , char ] ~~~~ ~~~~~
The C$PRINTABLE
subroutine converts the contents of the data-item specified as the first argument to printable characters. Those characters that are deemed printable (as defined by the character set used by data-item) will remain unchanged, while those that are NOT printable will be converted to the character specified as the second argument.
If no char argument is provided, a period (‘.’) will be used.
Note: CBL_GC_PRINTABLE replaces this although it is currently still supported for legacy reasons.
8.2.12. C$SLEEP
C$SLEEP Built-In Subroutine Syntax
CALL "C$SLEEP" USING seconds-to-sleep ~~~~ ~~~~~
C$SLEEP
puts the program to sleep for the specified number of seconds. The seconds-to-sleep argument may be a numeric literal or data item.
Sleep times less than 1 will be interpreted as 0, which immediately returns control to the calling program without any sleep delay.
8.2.13. C$TOLOWER
C$TOLOWER Built-In Subroutine Syntax
CALL "C$TOLOWER" USING data-item, BY VALUE convert-length ~~~~ ~~~~~ ~~~~~
This routine will converts the convert-length (a numeric literal or data item) leading characters of data-item (an alphanumeric identifier) to lower-case.
The convert-length argument must be specified BY VALUE
(see CALL). Any characters in data-item after the convert-length point will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
8.2.14. C$TOUPPER
C$TOUPPER Built-In Subroutine Syntax
CALL "C$TOUPPER" USING data-item, BY VALUE convert-length ~~~~ ~~~~~ ~~~~~
This routine will converts the convert-length (a numeric literal or data item) leading characters of data-item (an alphanumeric identifier) to upper-case.
The convert-length argument must be specified BY VALUE
(see CALL). Any characters in data-item after the convert-length point will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
8.2.15. CBL_AND
CBL_AND Built-In Subroutine Syntax
CALL "CBL_AND" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 0 0 1 0 1 0 0 1 1 1 |
This subroutine performs a bit-by-bit logical AND operation between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the AND process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.16. CBL_CHANGE_DIR
CBL_CHANGE_DIR Built-In Subroutine Syntax
CALL "CBL_CHANGE_DIR" USING directory-path ~~~~ ~~~~~
This routine makes directory-path (an alphanumeric literal or identifier) the current directory.
The return code of the operation, which will be either 0=Success or 128=failure, is returned in the RETURN-CODE
special register (see Special Registers).
The directory change remains in effect until the program terminates (in which the original current directory at the time the program was started will be automatically restored) or until another CBL_CHANGE_DIR
or a C$CHDIR
built-in system subroutine (see C$CHDIR) is executed.
8.2.17. CBL_CHECK_FILE_EXIST
CBL_CHECK_FILE_EXIST Built-In Subroutine Syntax
CALL "CBL_CHECK_FILE_EXIST" USING file-path, file-info ~~~~ ~~~~~
With this routine you may retrieve the size of the file specified as the file-path argument (an alphanumeric literal or identifier) and the date/time that file was last modified. File size information may not be available in the particular GnuCOBOL build / Operating System combination you are using and may therefore always be returned as zero.
The information is returned to the file-info argument, which is defined as the following 16-byte area:
01 file-info. 05 File-Size-In-Bytes PIC 9(18) COMP. 05 Mod-DD PIC 9(2) COMP. *> Modification Date 05 Mod-MO PIC 9(2) COMP. 05 Mod-YYYY PIC 9(4) COMP. 05 Mod-HH PIC 9(2) COMP. *> Modification Time 05 Mod-MM PIC 9(2) COMP. 05 Mod-SS PIC 9(2) COMP. 05 FILLER PIC 9(2) COMP. *> Always 00
If the subroutine is successful, a value of 0 will be returned in the RETURN-CODE
special register (see Special Registers). Failure to retrieve the needed statistics on the file will cause a RETURN-CODE
special register value of 35 to be passed back. Supplying less than two arguments will generate a 128 RETURN-CODE
special register value.
8.2.18. CBL_CLOSE_FILE
CBL_CLOSE_FILE Built-In Subroutine Syntax
CALL "CBL_CLOSE_FILE" USING file-handle ~~~~ ~~~~~
The CBL_CLOSE_FILE
subroutine closes a byte stream file previously opened by either the CBL_OPEN_FILE
built-in system subroutine (see CBL_OPEN_FILE) or CBL_CREATE_FILE
built-in system subroutine (see CBL_CREATE_FILE) subroutines.
If the file defined by the file-handle argument (a PIC X(4) USAGE COMP-X
data item) was opened for output, an implicit CBL_FLUSH_FILE
built-in system subroutine (see CBL_FLUSH_FILE) will be performed before the file is closed.
If the subroutine is successful, a value of 0 will be returned in the RETURN-CODE
special register (see Special Registers). Failure will cause a RETURN-CODE
special register value of -1 to be passed back.
8.2.19. CBL_COPY_FILE
CBL_COPY_FILE Built-In Subroutine Syntax
CALL "CBL_COPY_FILE" USING src-file-path, dest-file-path ~~~~ ~~~~~
Use this subroutine to copy file src-file-path to dest-file-path as if it were done via the cp
(Unix/OSX) or COPY
(Windows) command.
Both arguments may be alphanumeric literals or identifiers.
If the attempt to copy the file fails (for example, it or the destination directory doesn’t exist), the RETURN-CODE
special register (see Special Registers) will be set to 128; on successful completion it will be set to 0.
8.2.20. CBL_CREATE_DIR
CBL_CREATE_DIR Built-In Subroutine Syntax
CALL "CBL_CREATE_DIR" USING dir-path ~~~~ ~~~~~
With this routine you may create a new directory — the name of which is supplied as the dir-path argument (an alphanumeric literal or identifier).
Only the lowest-level directory (last) in the specified path can be created — all others must already exist. This subroutine will not behave as a mkdir -p
(Unix) or mkdir /p
(Windows).
The RETURN-CODE
special register (see Special Registers) will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
8.2.21. CBL_CREATE_FILE
CBL_CREATE_FILE Built-In Subroutine Syntax
CALL "CBL_CREATE_FILE" USING file-path, 2, 0, 0, file-handle ~~~~ ~~~~~
The CBL_CREATE_FILE
subroutine creates the new file specified using the file-path argument and opens it for output as a byte-stream file usable by CBL_WRITE_FILE
built-in system subroutine (see CBL_WRITE_FILE).
Arguments 2, 3 and 4 should be coded as the constant values shown. CBL_CREATE_FILE
is actually a special-case of the CBL_OPEN_FILE
built-in system subroutine (see CBL_OPEN_FILE) routine — see that routine for a description of the meanings of arguments 2, 3 and 4.
A file-handle (PIC X(4) USAGE COMP-X)
will be returned, for use on any subsequent CBL_WRITE_FILE
built-in system subroutine (see CBL_WRITE_FILE) or CBL_CLOSE_FILE
built-in system subroutine (see CBL_CLOSE_FILE) calls.
The success or failure of the subroutine will be reported back in the RETURN-CODE
special register (see Special Registers), with a value of -1 indicating an invalid argument and a value of 0 indicating success.
8.2.22. CBL_DELETE_DIR
CBL_DELETE_DIR Built-In Subroutine Syntax
CALL "CBL_DELETE_DIR" USING dir-path ~~~~ ~~~~~
This subroutine deletes an empty directory.
The only argument — dir-path (an alphanumeric literal or identifier) — is the name of the directory to be deleted.
Only the lowest-level directory (last) in the specified path will be deleted, and that directory must be empty to be deleted.
The RETURN-CODE
special register (see Special Registers) will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
8.2.23. CBL_DELETE_FILE
CBL_DELETE_FILE Built-In Subroutine Syntax
CALL "CBL_DELETE_FILE" USING file-path ~~~~ ~~~~~
This routine deletes the file specified by the file-path argument (an alphanumeric literal or identifier) just as if that were done using the rm
(Unix/OSX) or ERASE
(Windows) command.
If the attempt to delete the file fails (for example, it doesn’t exist), the RETURN-CODE
special register (see Special Registers) will be set to 128; on successful completion it will be set to 0.
8.2.24. CBL_EQ
CBL_EQ Built-In Subroutine Syntax
CALL "CBL_EQ" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 1 0 1 0 1 0 0 1 1 1 |
This subroutine performs a bit-by-bit comparison between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the EQ process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.25. CBL_ERROR_PROC
CBL_ERROR_PROC Built-In Subroutine Syntax
CALL "CBL_ERROR_PROC" USING function, program-pointer ~~~~ ~~~~~
This routine registers a general error-handling routine.
The function argument must be a numeric literal or a 32-bit binary data item (USAGE BINARY-LONG
, for example) with a value of 0 or 1. A value of 0 means that you will be registering (“installing”) an error procedure while a value of 1 indicates you’re de-registering (“uninstalling”) a previously-installed error procedure.
The program-pointer must be a data item with a USAGE
(see USAGE) of PROGRAM-POINTER
containing the address of your error procedure. This item should be given a value using the SET Program-Pointer
statement (see SET Program-Pointer). If the error procedure is written in GnuCOBOL, it must be a subroutine, not a user-defined function.
A success (0) or failure (non-0) result will be passed back in the RETURN-CODE
special register (see Special Registers).
A custom error procedure will trigger when a runtime error condition is encountered. An error procedure may be registered by a main program or a subprogram, but regardless of from where it was registered, it applies to the overall program compilation group and will trigger when a runtime error occurs anywhere in the executable program. If the error procedure was defined by a subprogram, that program must be loaded at the time the error procedure is executed.
An error procedure may be used to take whatever actions might be warranted to display additional information or to gracefully close down work in progress, but it cannot prevent the termination of program execution; should the error procedure not issue its own STOP RUN
, control will return back to the standard error routine when the error procedure exits.
The code within the handler will be executed and — once the handler issues a return
, if it was written in C, or an EXIT PROGRAM
statement (see EXIT) or GOBACK
statement, if it was written in GnuCOBOL, the system-standard error handling routine will be executed.
Only one user-defined error procedure may be in effect at any time.
The following is a sample GnuCOBOL program that registers an error procedure. The output of that program is shown as well. As as you can see, the error handler’s messages appear followed by the standard GnuCOBOL message.
1. IDENTIFICATION DIVISION. 2. PROGRAM-ID. DemoERRPROC. 3. ENVIRONMENT DIVISION. 4. DATA DIVISION. 5. WORKING-STORAGE SECTION. 6. 01 Err-Proc-Address USAGE PROGRAM-POINTER. 7. PROCEDURE DIVISION. 8. S1. 9. DISPLAY 'Program is starting' 10. SET Err-Proc-Address TO ENTRY 'ErrProc' 11. CALL 'CBL_ERROR_PROC' USING 0, Err-Proc-Address 12. CALL 'Tilt' *> THIS DOESN'T EXIST!!!! 13. DISPLAY 'Program is stopping' 14. STOP RUN 15. . 16. END PROGRAM DemoERRPROC. 17. 18. IDENTIFICATION DIVISION. 19. PROGRAM-ID. ErrProc. 20. PROCEDURE DIVISION. 21. 000-Main. 22. DISPLAY 'Error: ' FUNCTION EXCEPTION-LOCATION 23. DISPLAY ' ' FUNCTION EXCEPTION-STATEMENT 24. DISPLAY ' ' FUNCTION EXCEPTION-FILE 25. DISPLAY ' ' FUNCTION EXCEPTION-STATUS 26. DISPLAY '*** Returning to Standard Error Routine ***' 27. EXIT PROGRAM 28. . 29. END PROGRAM ErrProc.
When executed, this sample program generates the following console output.
E:\Programs\Demos>demoerrproc Program is starting Error: DemoERRPROC; S1; 12 CALL 00 EC-PROGRAM-NOT-FOUND *** Returning to Standard Error Routine *** DEMOERRPROC.cbl: 27: libcob: Cannot find module 'Tilt' E:\Programs\Demos>
8.2.26. CBL_EXIT_PROC
CBL_EXIT_PROC Built-In Subroutine Syntax
CALL "CBL_EXIT_PROC" USING function, program-pointer ~~~~ ~~~~~
This routine registers a general exit-handling routine.
The function argument must be a numeric literal or a 32-bit binary data item (USAGE BINARY-LONG
, for example) with a value of 0 or 1. A value of 0 means that you will be registering (“installing”) an exit procedure while a value of 1 indicates you’re deregistering (“uninstalling”) a previously-installed exit procedure.
The program-pointer must be a data item with a USAGE
(see USAGE) of PROGRAM-POINTER
containing the address of your exit procedure.
A success (0) or failure (non-0) result will be passed back in the RETURN-CODE
special register (see Special Registers).
An exit procedure, once registered, will trigger whenever a STOP RUN
statement (see STOP) or a GOBACK
statement (see GOBACK) is executed anywhere in the program. The exit procedure may execute whatever code is desired to undertake an orderly shut down of the program. Once the exit procedure terminates by executing an EXIT PROGRAM
statement (see EXIT) or a GOBACK
statement, the system-standard program termination routine will be executed.
Only one user-defined exit procedure may be in effect at any time.
The following is a sample GnuCOBOL program that registers an exit procedure. The output of that program is shown as well.
IDENTIFICATION DIVISION. PROGRAM-ID. demoexitproc. DATA DIVISION. WORKING-STORAGE SECTION. 01 Exit-Proc-Address USAGE PROGRAM-POINTER. PROCEDURE DIVISION. 000-Register-Exit-Proc. SET Exit-Proc-Address TO ENTRY "ExitProc" CALL "CBL_EXIT_PROC" USING 0, Exit-Proc-Address IF RETURN-CODE NOT = 0 DISPLAY 'Error: Could not register Exit Procedure' END-IF . 099-Now-Test-Exit-Proc. DISPLAY 'Executing a STOP RUN...' END-DISPLAY GOBACK. END PROGRAM demoexitproc. IDENTIFICATION DIVISION. PROGRAM-ID. ExitProc. DATA DIVISION. WORKING-STORAGE SECTION. 01 Display-Date PIC XXXX/XX/XX. 01 Display-Time PIC XX/XX/XX. 01 Now PIC X(8). 01 Today PIC X(8). PROCEDURE DIVISION. 000-Main. DISPLAY '*** STOP RUN has been executed ***' ACCEPT Today FROM DATE YYYYMMDD ACCEPT Now FROM TIME MOVE Today TO Display-Date MOVE Now TO Display-Time INSPECT Display-Time REPLACING ALL '/' BY ':' DISPLAY '*** ' Display-Date ' ' Display-Time ' ***' GOBACK. END PROGRAM ExitProc.
8.2.27. CBL_FLUSH_FILE
CBL_FLUSH_FILE Built-In Subroutine Syntax
CALL "CBL_FLUSH_FILE" USING file-handle ~~~~ ~~~~~
In Micro Focus COBOL, calling this subroutine flushes any as-yet unwritten buffers for the (output) file whose file-handle is specified as the argument to disk.
This routine is non-functional in GnuCOBOL. It exists only to provide compatibility for applications that may have been developed for Micro Focus COBOL.
8.2.28. CBL_GC_FORK
CBL_GC_FORK Built-In Subroute Syntax
CALL "CBL_GC_FORK" USING Child-PID ~~~~ ~~~~~
CBL_GC_FORK allows you to fork the current COBOL process to a new one.
The current content of the process’s storage (including LOCAL-STORAGE) will be identical, any file handles get invalid in the new process, positions and file and record locks are only available to the original process.
This system routine is not available on Windows (exception: GCC on Cygwin).
Parameters: none
Returns: pid
(the child process gets ’0’ returned, the calling process gets the pid
of the created child).
Negative values are returned for system dependant error codes and -1 if the function is not available on the current system.
CBL_GC_FORK
allows you to fork the current COBOL process to a new one. The current content of the process’ storage (including LOCAL-STORAGE
) will be identical, any file handles get invalid in the new process, positions and file / record locks are only available to the original process. This system routine is not available on Windows (exception: gcc
on Cygwin). Parameters: none Returns: pid
(the child process gets 0 returned, the calling process gets the pid
of the created children). Negative values are returned for system dependant error codes and -1 if the function is not available on the current system.
IDENTIFICATION DIVISION. PROGRAM-ID. prog. DATA DIVISION. WORKING-STORAGE SECTION. 01 CHILD-PID PIC S9(9) BINARY. 01 WAIT-STS PIC S9(9) BINARY. PROCEDURE DIVISION. CALL "CBL_GC_FORK" RETURNING CHILD-PID END-CALL EVALUATE TRUE WHEN CHILD-PID = ZERO PERFORM CHILD-CODE WHEN CHILD-PID > ZERO PERFORM PARENT-CODE WHEN CHILD-PID = -1 DISPLAY 'CBL_GC_FORK is not available on the current' ' system!' PERFORM CHILD-CODE MOVE 0 TO CHILD-PID PERFORM PARENT-CODE WHEN OTHER MULTIPLY -1 BY CHILD-PID END-MULTIPLY DISPLAY 'CBL_GC_FORK returned system error: ' CHILD-PID END-EVALUATE STOP RUN. CHILD-CODE. CALL "C$SLEEP" USING 1 END-CALL DISPLAY "Hello, I am the child" MOVE 2 TO RETURN-CODE. PARENT-CODE. DISPLAY "Hello, I am the parent" CALL "CBL_GC_WAITPID" USING CHILD-PID RETURNING WAIT-STS MOVE 0 TO RETURN-CODE EVALUATE TRUE WHEN WAIT-STS >= 0 DISPLAY 'Child ended with status: ' WAIT-STS WHEN WAIT-STS = -1 DISPLAY 'CBL_GC_WAITPID is not available on the ' 'current system!' WHEN WAIT-STS < -1 MULTIPLY -1 BY WAIT-STS END-MULTIPLY DISPLAY 'CBL_GC_WAITPID returned system error: ' WAIT-STS END-EVALUATE.
8.2.29. CBL_GC_GETOPT
CBL_GC_GETOPT Built-In Subroutine Syntax
CALL "CBL_GC_GETOPT" USING BY REFERENCE SHORTOPTIONS LONGOPTIONS LONGIND ~~~~ ~~~~~ BY VALUE LONG-ONLY BY REFERENCE RETURN-CHAR OPT-VAL
CBL_GC_GETOPT
adapts the well-known option parser, getopt
, to GnuCOBOL.
The usage of this system routine is described by the following example.
IDENTIFICATION DIVISION. PROGRAM-ID. PROG. DATA DIVISION. WORKING-STORAGE SECTION. 78 SHORTOPTIONS VALUE "jkl". 01 LONGOPTIONS. 05 OPTIONRECORD OCCURS 2 TIMES. 10 OPTIONNAME PIC X(25). 10 HAS-VALUE PIC 9. 10 VALPOINT POINTER VALUE NULL. 10 RETURN-VALUE PIC X(4). 01 LONGIND PIC 99. 01 LONG-ONLY PIC 9 VALUE 1. 01 RETURN-CHAR PIC X(4). 01 OPT-VAL PIC X(10). 01 COUNTER PIC 9 VALUE 0.
We first need to define the necessary fields for getopt
’s shortoptions
, longoptions
, longoption index (longind
), long-only-option (long-only
) and also the fields for return values return-char
and opt-val
(arbitrary size with trimming, see return codes).
The shortoptions
are written down as an alphanumeric field (i.e., a string with arbitrary size) as follows:
"ab:c::d"
This means we want getopt
to look for short options named ‘a’, ‘b’, ‘c’ or ‘d’, require an option value for ‘b’, and accept an optional one for ‘c’.
The longoptions
are defined as a table of records with oname
, has-value
, valpoint
and val
.5
oname
defines the name of a longoption. has-value
defines if an option value is demanded (has-val = 1
), optional (has-val = 2
) or not required (has-val = 0
).
valpoint
is a pointer used to specify an address to save getopt's
return value to. The pointer is optional. If it is NULL
, getopt
returns a value as usual. If you use the pointer it has to point to a PIC X(4)
field. The field val is a PIC X(4)
character which is returned if the longoption was recognized.
The longoption structure is immutable! You can only vary the number of records.
Now we have the tools to run CBL_GC_GETOPT
within the procedure division.
PROCEDURE DIVISION. MOVE "version" to OPTIONNAME (1). MOVE 0 TO HAS-VALUE (1). MOVE ‘V’ TO RETURN-VALUE (1). MOVE "verbose" TO OPTIONNAME (2). MOVE 0 TO HAS-VALUE (2). MOVE ‘V’ TO RETURN-VALUE (2). PERFORM WITH TEST AFTER UNTIL RETURN-CODE = -1 CALL 'CBL_GC_GETOPT' USING BY REFERENCE SHORTOPTIONS LONGOPTIONS LONGIND BY VALUE LONG-ONLY BY REFERENCE RETURN-CHAR OPT-VAL END-CALL DISPLAY RETURN-CHAR END-DISPLAY DISPLAY OPT-VAL END-DISPLAY END-PERFORM STOP RUN.
The example shows how we initialize all parameters and call the routine until CBL_GC_GETOPT
runs out of options and returns -1.
return-char
might contain the following regular character if an option was recognized:
?
-
undefined or ambiguous option
1
-
non-option (only if first byte of so is ‘-’)
0
-
valpoint != NULL
and we are writing the return value to the specified address -1
no more options (or reach the first non-option if first byte of
shortoptions
is ‘+’)
The return-codes of CBL_GC_GETOPT
are:
1
-
a non-option (only if first byte of so is ‘-’)
0
-
valpoint != NULL
and we are writing the return value to the specified address -1
-
no more options (or reach the first non-option if first byte of
shortoptions
is ‘+’) 2
-
truncated option value in
opt-val
(becauseopt-val
was too small) 3
a regular answer from
getopt
8.2.30. CBL_GC_HOSTED
CBL_GC_HOSTED Built-In Subroutine Syntax
CALL "CBL_GC_HOSTED" USING ARG-1 ARG-2 ~~~~ ~~~~~ Note replaces CBL_OC_HOSTED which is kept as a legacy item.
CBL_GC_HOSTED
provides access to the following C hosted variables:
argc
-
binary-long by value
argv
-
pointer to char **
stdin, stdout, stderr
-
pointer
errno
giving address of
errno
in pointer tobinary-long
, usebased
for more
Direct access and conditional access to the following variables:
tzname
-
pointer to pointer to array of two char pointer
s timezone
-
C
long
, will be seconds west of UTC daylight
C
int
, will be 1 during daylight savings
The system will need HAVE TIMEZONE
defined for these to return anything meaningful. Attempts made when they are not available will return 1 from CBL GC HOSTED
.
It returns 0 when match, 1 on failure, case matters as does length, "arg" won’t match.
The usage of this system routine is described by the following example.
IDENTIFICATION DIVISION. PROGRAM-ID. HOSTED. DATA DIVISION. WORKING-STORAGE SECTION. 01 Argc BINARY-LONG. 01 Argv POINTER. 01 Stdin POINTER. 01 Stdout POINTER. 01 Stderr POINTER. 01 Errno POINTER. 01 Err BINARY-LONG BASED. 01 Domain FLOAT-LONG VALUE 3.0. 01 Tzname POINTER. 01 Tznames POINTER BASED. 05 Tzs POINTER OCCURS 2. 01 Timezone BINARY-LONG. 01 Daylight BINARY-SHORT. *> PROCEDURE DIVISION. call "CBL_GC_HOSTED" using stdin "stdin" display "stdin : " stdin call "feof" using by value stdin display "feof stdin : " return-code call "CBL_GC_HOSTED" using stdout "stdout" display "stdout : " stdout call "fprintf" using by value stdout by content "Hello" & x"0a" call "CBL_GC_HOSTED" using stderr "stderr" display "stderr : " stderr call "fprintf" using by value stderr by content "on err" & x"0a" call "CBL_GC_HOSTED" using argc "argc" display "argc : " argc call "CBL_GC_HOSTED" using argv "argv" display "argv : " argv call "args" using by value argc argv call "CBL_GC_HOSTED" using errno "errno" display "&errno : " errno set address of err to errno display "errno : " err call "acos" using by value domain display "errno after acos(3.0): " err ", EDOM is 33" call "CBL_GC_HOSTED" using argc "arg" display "'arg' lookup : " return-code call "CBL_GC_HOSTED" using null "argc" display "null with argc : " return-code display "argc is still : " argc *> the following only returns zero if the system has HAVE_TIMEZONE set call "CBL_GC_HOSTED" using daylight "daylight " display "'timezone' lookup : " return-code if return-code not = 0 display "system doesn't has timezone" else display "timezone is : " timezone call "CBL_GC_HOSTED" using daylight "daylight " display "'daylight' lookup : " return-code display "daylight is : " daylight set environment "TZ" to "PST8PDT" call static "tzset" returning omitted on exception continue end-call call "CBL_GC_HOSTED" using tzname "tzname" display "'tzname' lookup : " return-code *> tzs(1) will point to z"PST" and tzs(2) to z"PDT" if return-code equal 0 and tzname not equal null then set address of tznames to tzname if tzs(1) not equal null then display "tzs #1 : " tzs(1) end-if if tzs(2) not equal null then display "tzs #2 : " tzs(2) end-if end-if end-if goback. end program hosted.
Note that the legacy name of this routine that starts with CBL_OC
is deprecated, as is NANOSLEEP
but will still work. It is recommended that all library routines names starting with CBL_OC
are replaced with CBL_GC
to minimise issues.
8.2.31. CBL_GC_NANOSLEEP
CBL_GC_NANOSLEEP Built-In Subroutine Syntax
CALL "CBL_GC_NANOSLEEP" USING nanoseconds-to-sleep ~~~~ ~~~~~ Note replaces CBL_OC_NANOSLEEP which is kept as a legacy item.
This subroutine puts the program to sleep for the specified number of nanoseconds.
The effective granularity of nanoseconds-to-sleep values will depend upon the granularity of the system clock your computer is using and the timing granularity of the operating system that computer is running.
For example, you will not expect to see any difference between values of 1, 100, 500 or 1000, but you should see a difference between values such as 250000000 and 500000000.
The nanoseconds-to-sleep argument is a numeric literal or data item.
There are one billion nanoseconds in a second, so if you wanted to put the program to sleep for 1/4 second you’d use a nanoseconds-to-sleep value of 250000000.
Note that the legacy name of this routine starts with “CBL_OC” is deprecated, as is HOSTED
, but will still work. It is recommended that all library routines names starting with “CBL_OC” are replaced with “CBL_GC” to minimise issues.
8.2.32. CBL_GC_PRINTABLE
CBL_GC_PRINTABLE Built-In Subroutine Syntax
CALL "CBL_GC_PRINTABLE" USING data-item [ , char ] ~~~~ ~~~~~ Note replaces C$PRINTABLE which is kept as a legacy item.
The CBL_GC_PRINTABLE
subroutine converts the contents of the data-item specified as the first argument to printable characters.
Those characters that are deemed printable (as defined by the character set used by data-item) will remain unchanged, while those that are not printable will be converted to the character specified as the second argument.
If no char argument is provided, a period (‘.’) will be used.
8.2.33. CBL_GC_WAITPID
CBL_GC_WAITPID Built-In Subroutine Syntax
CALL "CBL_GC_WAITPID" USING ARG-1 ~~~~ ~~~~~ RETURNING RET-STATUS ~~~~~~~~~
CBL_GC_WAITPID
allows you to wait until another system process ended.
Additionally you can check the process’s return code.
Parameters: none
Returns: function-status / child-status
Negative values are returned for system dependant error codes and -1 if the function is not available on the current system.
CALL "CBL_GC_WAITPID" USING CHILD-PID RETURNING WAIT-STS MOVE 0 TO RETURN-CODE DISPLAY 'CBL_GC_WAITPID ended with status: ' WAIT-STS
8.2.34. CBL_GET_CSR_POS
CBL_GET_CSR_POS Built-In Subroutine Syntax
CALL "CBL_GET_CSR_POS" USING cursor-locn-buffer ~~~~ ~~~~~
This subroutine will retrieve the current cursor location on the screen, returning a 2-byte value into the supplied cursor-locn-buffer. The first byte of cursor-locn-buffer will receive the current line (row) location while the second receives the current column location.
The returned location data will be in binary form, and will be based upon starting values of 0, meaning that if the cursor is located at line 15, column 12 at the time this routine is called, a value of (14,11) will be returned.
The following is a typical cursor-locn-buffer definition:
01 CURSOR-LOCN-BUFFER. 05 CURSOR-LINE USAGE BINARY-CHAR. 05 CURSOR-COLUMN USAGE BINARY-CHAR.
Values of 1 (Line) and 1 (column) will be returned if GnuCOBOL was not generated to include screen I/O.
8.2.35. CBL_GET_CURRENT_DIR
CBL_GET_CURRENT_DIR Built-In Subroutine Syntax
CALL "CBL_GET_CURRENT_DIR" USING BY VALUE 0, ~~~~ ~~~~~ ~~~~~ BY VALUE length, ~~~~~ BY REFERENCE buffer ~~~~~~~~~
This retrieves the fully-qualified pathname of the current directory, saving up to length characters of that name into buffer.
The first argument is unused, but must be specified. It must be specified BY VALUE
(see CALL).
The length argument must be specified BY VALUE
. The buffer argument must be specified BY REFERENCE
.
The value specified for the length argument (a numeric literal or data item) should not exceed the actual length of buffer argument.
If the value specified for the length argument is LESS THAN the actual length of buffer argument, the current directory path will be left-justified and space filled within the first length bytes of buffer — any bytes in buffer after that point will be unchanged.
If the routine is successful, a value of 0 will be returned to the RETURN-CODE
special register (see Special Registers). If the routine failed because of a problem with an argument (such as a negative or 0 length), a value of 128 will result. Finally, if the 1st argument value is anything but zero, the routine will fail with a 129 value.
8.2.36. CBL_GET_SCR_SIZE
CBL_GET_SCR_SIZE Built-In Subroutine Syntax
CALL "CBL_GET_SCR_SIZE" USING no-of-lines, no-of-cols ~~~~ ~~~~~
Use this subroutine to retrieve the current console screen size.
When the system is running in a windowed environment, this will be the sizing of the console window in which the program is executing. When the system is not running a windowing environment, the physical console screen attributes will be returned. In environments such as a Windows console window, where the logical size of the window may far exceed that of the physical console window, the size returned will be that of the physical console window. Two one-byte values will be returned — the first will be the current number of lines (rows) while the second will be the number of columns.
The returned size data will be in binary form.
The following are typical no-of-lines and no-of-columns definitions:
01 NO-OF-LINES USAGE BINARY-CHAR. 01 NO-OF-COLUMNS USAGE BINARY-CHAR.
GnuCOBOL run-time screen management must have been initialized prior to CALLing this routine in order to receive meaningful values. This means that a DISPLAY screen-data-item
statement (see DISPLAY screen-data-item) or a ACCEPT screen-data-item
statement (see ACCEPT screen-data-item) must have been executed prior to executing the CALL
statement.
Zero values will be returned if the screen has not been initialized and values of 24 (lines) and 80 (columns) will be returned if GnuCOBOL was not generated to include screen I/O.
8.2.37. CBL_IMP
CBL_IMP Built-In Subroutine Syntax
CALL "CBL_IMP" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 1 0 1 1 1 0 0 1 1 1 |
This subroutine performs a bit-by-bit logical implies process between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the IMP process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.38. CBL_NIMP
CBL_NIMP Built-In Subroutine Syntax
CALL "CBL_NIMP" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 0 0 1 0 1 0 1 1 1 0 |
This subroutine performs the negation of a bit-by-bit logical implies process between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the NIMP process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.39. CBL_NOR
CBL_NOR Built-In Subroutine Syntax
CALL "CBL_NOR" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 1 0 1 0 1 0 0 1 1 0 |
This subroutine performs the negation of a bit-by-bit logical or’ process between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the NOR process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.40. CBL_NOT
CBL_NOT Built-In Subroutine Syntax
CALL "CBL_NOT" USING item-1, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
This subroutine “flips” the left-most 8*byte-length bits of item-1, changing 0 bits to 1, and 1 bits to 0. The changes are made directly im item-1.
The item-1 argument must be a data item. The length of item-1 must be at least 8*byte-length.
The byte-length argument may be a numeric literal or data item, and must be passed using BY VALUE
(see CALL).
Any bits in item-1 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.42. CBL_OPEN_FILE
CBL_OPEN_FILE Built-In Subroutine Syntax
CALL "CBL_OPEN_FILE" USING file-path, access-mode, 0, 0, handle ~~~~ ~~~~~
This routine opens an existing file for use as a byte-stream file usable by CBL_WRITE_FILE or CBL_READ_FILE.
The file-path argument is an alphanumeric literal or data-item.
The access-mode argument is a numeric literal or data item with a PIC X USAGE COMP-X
(or USAGE BINARY-CHAR
) definition; it specifies how you wish to use the file, as follows:
1
-
input (read-only)
2
-
output (write-only)
3
input and/or output
The third and fourth arguments would specify a locking mode and device specification, respectively, but they’re not implemented in GnuCOBOL (currently, at least) — just specify each as 0.
The final argument (handle) is a PIC X(4) USAGE COMP-X
item that will receive the handle to the file. That handle is used on all other byte-stream functions to reference this specific file.
A RETURN-CODE
special register (see Special Registers) value of -1 indicates an invalid argument, while a value of 0 indicates success. A value of 35 means the file does not exist.
8.2.43. CBL_OR
CBL_OR Built-In Subroutine Syntax
CALL "CBL_OR" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 0 0 1 1 1 0 1 1 1 1 |
This subroutine performs a bit-by-bit logical or process between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the OR process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.44. CBL_READ_FILE
CBL_READ_FILE Built-In Subroutine Syntax
CALL "CBL_READ_FILE" USING handle, offset, nbytes, flag, buffer ~~~~ ~~~~~
This routine reads nbytes of data starting at byte number offset from the byte-stream file defined by handle into buffer.
The handle argument (PIC X(4) USAGE COMP-X
) must have been populated by a prior call to CBL_OPEN_FILE
built-in system subroutine (see CBL_OPEN_FILE).
The offset argument (PIC X(8) USAGE COMP-X
) defines the location in the file of the first byte to be read. The first byte of a file is byte offset 0.
The nbytes argument (PIC X(4) USAGE COMP-X
) specifies how many bytes (maximum) will be read. If the flag argument is specified as 128, the size of the file (in bytes) will be returned into the file offset argument (argument 2) upon completion. Not all operating system/GnuCOBOL environments may be able to retrieve file sizes in such cases, a value of zero will be returned. The only other valid value for flags is 0. This argument may be specified either as a numeric literal or as a PIC X USAGE COMP-X
data item.
Upon completion, the RETURN-CODE
special register (see Special Registers) will be set to 0 if the read was successful or to 10 if an "end-of-file" condition occurred. If a value of -1 is returned, a problem was identified with the subroutine arguments.
8.2.45. CBL_READ_KBD_CHAR
CBL_READ_KBD_CHAR Build-In Subroutine Syntax
CALL "CBL_READ_KBD_CHAR" USING char RETURNING status-code. ~~~~ ~~~~~ ~~~~~~~~~
Waits until a character is typed from the terminal and then read it with no echo.
Parameters: char PIC X
. Receives the character that was typed, in ASCII.
status-code PIC XX COMP-5
.
If RETURNING
is not used the RETURN-CODE
special register receives the status-code where zero is success and non-zero it is not.
[Above information taken from MF WB manual].
8.2.46. CBL_RENAME_FILE
CBL_RENAME_FILE Built-In Subroutine Syntax
CALL "CBL_RENAME_FILE" USING old-file-path, new-file-path ~~~~ ~~~~~
You may use this subroutine to rename a file.
The file specified by old-file-path will be “renamed” to the name specified as new-file-path. Each argument may be an alphanumeric literal or data item.
Despite what the name of this routine might make you believe, this routine is more than just a simple “rename” — it will actually move the file supplied as the 1st argument to the file specified as the 2nd argument. Think of it as a two-step sequence, first copying the old-file-path file to the new-file-path file and then a second step where the old-file-path is deleted.
If the attempt to move the file fails (for example, it doesn’t exist), the RETURN-CODE
special register (see Special Registers) will be set to 128; on successful completion it will be set to 0.
8.2.47. CBL_SET_CSR_POS
CBL_SET_CSR_POS Build-In Subroutine Syntax
CALL "CBL_SET_CSR_POS" USING cursor-locn-buffer ? ~~~~ ~~~~~
Set current position on terminal.
8.2.48. CBL_TOLOWER
CBL_TOLOWER Built-In Subroutine Syntax
CALL "CBL_TOLOWER" USING data-item, BY VALUE convert-length ~~~~ ~~~~~ ~~~~~
This routine will convert the first convert-length (a numeric literal or data item) characters of data-item (an alpha-numeric identifier) to lower-case.
The convert-length argument must be specified BY VALUE
(see CALL). It specifies how many (leading) characters in data-item will be converted — any characters after that will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
8.2.49. CBL_TOUPPER
CBL_TOUPPER Built-In Subroutine Syntax
CALL "CBL_TOUPPER" USING data-item, BY VALUE convert-length ~~~~ ~~~~~ ~~~~~
This routine will convert the first convert-length (a numeric literal or data item) characters of data-item (an alpha-numeric identifier) to upper-case.
The convert-length argument must be specified BY VALUE
(see CALL). It specifies how many (leading) characters in data-item will be converted — any characters after that will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
8.2.50. CBL_WRITE_FILE
CBL_WRITE_FILE Built-In Subroutine Syntax
CALL "CBL_WRITE_FILE" USING handle, offset, nbytes, 0, buffer ~~~~ ~~~~~
This routine writes nbytes of data from buffer to the byte-stream file defined by handle starting at byte number offset within the file.
The handle argument (PIC X(4) USAGE COMP-X
) must have been populated by a prior call to CBL_OPEN_FILE. The offset argument (PIC X(4) USAGE COMP-X
) defines the location in the file of the first byte to be written to. The first byte of a file is byte offset 0.
The nbytes argument (PIC X(4) USAGE COMP-X
) specifies how many bytes (maximum) will be written.
Currently, the only allowable value for the flags argument is 0. This argument may be specified either as a numeric literal or as a PIC X(1) USAGE COMP-X
data item.
Upon completion, the RETURN-CODE
special register (see Special Registers) will be set to 0 if the write was successful or to 30 if an I/O error condition occurred. If a value of -1 is returned, a problem was identified with the subroutine arguments.
8.2.51. CBL_XOR
CBL_XOR Built-In Subroutine Syntax
CALL "CBL_XOR" USING item-1, item-2, BY VALUE byte-length ~~~~ ~~~~~ ~~~~~
Old Old New Arg 1 Arg 2 Arg 2 Bit Bit Bit ===== ===== ===== 0 0 0 0 1 1 1 0 1 1 1 0 |
This subroutine performs a bit-by-bit logical exclusive or process between the left-most 8*byte-length corresponding bits of item-1 and item-2, storing the resulting bit string into item-2. The truth table shown to the left documents the XOR process. The item-1 argument may be an alphanumeric literal or a data item and item-2 must be a data item. The length of both item-1 and item-2 must be at least 8*byte-length. |
The byte-length argument may be a numeric literal or data item, and must be specified using BY VALUE
(see CALL).
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE
special register (see Special Registers).
8.2.52. SYSTEM
SYSTEM Built-In Subroutine Syntax
CALL "SYSTEM" USING command ~~~~ ~~~~~
This subroutine submits command (an alphanumeric literal or data item) to a command shell for execution as if it were typed into a console/terminal window.
A shell will be opened subordinate to the GnuCOBOL program issuing the call to SYSTEM
.
Output from the command (if any) will appear in the command window in which the GnuCOBOL program was executed.
On a Unix system, the shell environment will be established using the default shell program. This is also true when using a GnuCOBOL build created with and for OSX or the Cygwin Unix emulator.
With native Windows Windows/MinGW builds, the shell environment will be the Windows console window command processor (usually cmd.exe
) appropriate for the version of Windows you’re using.
To trap output from the executed command and process it within the GnuCOBOL program, use a redirection (‘>’) to send the command output to a temporary file which you read from within the program once control returns.
The exit status of the executed command will be available in the RETURN-CODE
special-register.
8.2.53. X"91"
X"91" Built-In Subroutine Syntax
CALL X"91" USING return-code, function-code, binary-variable-arg ~~~~ ~~~~~
The original Micro Focus version of this routine is capable of providing a wide variety of functions. GnuCOBOL supports just three of them:
- Turning runtime switches (
SWITCH-1
, … ,SWITCH-8
) on. - Turning runtime switches (
SWITCH-1
, … ,SWITCH-8
) off. - Retrieving the number of arguments passed to a subroutine.
The return-code argument must be a one-byte binary numeric data item (USAGE BINARY-CHAR
is recommended). It will receive a value of 0 if the operation was successful, 1 otherwise.
The function-code argument must be either a numeric literal or a one-byte binary numeric data item (USAGE BINARY-CHAR
is recommended).
The third argument — variable-arg — is defined differently depending upon the function-code value, as follows:
- 11
-
Sets and/or clears all eight of the COBOL switches (
SWITCH-1
throughSWITCH-8
). See SPECIAL-NAMES, for an explanation of those switches.The variable-arg argument should be an
OCCURS 8 TIMES
table ofUSAGE BINARY-CHAR
.Each occurrence that is set to a value of zero prior to the
CALL X"91"
will cause the corresponding switch to be cleared. Each occurrence set to 1 prior to theCALL X"91"
will cause the corresponding switch to be set.Values other than 0 or 1 will be ignored.
- 12
-
Reads all eight of the COBOL switches (
SWITCH-1
throughSWITCH-8
)The variable-arg argument should be an
OCCURS 8 TIMES
table ofUSAGE BINARY-CHAR
.Each of the 1st eight occurrences of the array will be set to either 0 or 1 — 1 if the corresponding switch is set, 0 otherwise.
- 16
Retrieves the number of arguments passed to the program executing the
CALL X"91"
, saving that number into the variable-arg argument. That should be a binary numeric data item (USAGE BINARY-CHAR
is recommended).
8.2.54. X"E4"
X"E4" Built-In Subroutine Syntax
CALL X"E4" ~~~~
Use X"E4"
to clear the screen. There are no arguments and no returned value.
8.2.55. X"E5"
X"E5" Built-In Subroutine Syntax
CALL X"E5" ~~~~
The X"E5"
routine will sound the PC “bell”. There are no arguments and no returned value.
8.2.56. X"F4"
X"F4" Built-In Subroutine Syntax
CALL X"F4" USING byte, table ~~~~ ~~~~~
This routine packs the low-order (rightmost) bit from each of the eight 1-byte items in table into the corresponding bit positions of the single-byte data item byte.
The byte data item need be only a single byte in size. If it is longer, the excess will be unaffected by this subroutine.
The table data item must be at least 8 bytes long. If it is longer, the excess will be ignored by this subroutine.
Typically, table is defined similarly to the following:
01 Table-Arg. 05 Each-Byte OCCURS 8 TIMES USAGE BINARY-CHAR.
8.2.57. X"F5"
X"F5" Built-In Subroutine Syntax
CALL X"F5" USING byte, table ~~~~ ~~~~~
This routine unpacks each bit of the single-byte data item byte into the low-order (rightmost) bit of each of the corresponding eight 1-byte items in table. The other seven bit positions of each of the first eight entries in table will be set to zero.
The byte data item need be only a single byte in size. If it is longer, the excess will be unaffected by this subroutine.
The table data item must be at least 8 bytes long. If it is longer, the excess will be ignored by this subroutine.
Typically, table is defined similarly to the following:
01 Table-Arg. 05 Each-Byte OCCURS 8 TIMES USAGE BINARY-CHAR.
9. Report Writer Usage
9.1. RWCS Lexicon
There are a number of terms that describe various aspects of the operation of the Report Writer Control System (RWCS). Understanding the meanings of these terms is vital to developing an understanding of the subject.
- Control Break
-
An event that is triggered when a control field on an RWCS-generated report changes value. It is these events that trigger the generation of control heading and control footing groups.
- Control Field
-
A field of data being presented within a detail group; as the various detail groups that comprise the report are presented, they are presumed to appear in sorted sequence of the control fields contained within them. As an example, a department-by-department sales report for a chain of stores would probably be sorted by store number and – within like store numbers – be further sorted by department number. The store number will undoubtedly serve as a control field for the report, allowing control heading groups to be presented before each sequence of detail groups for the same store and control footing groups to be presented after each such sequence.
- Control Footing
-
A report group that appears immediately after one or more detail groups of an RWCS-generated report. Such are produced automatically as a result of a control break. This type of group typically serves as a summary of the detail group(s) that precede it, as might be the case on a sales report for a chain of stores, where the detail groups documenting sales for each department (one department per detail group) from the same store might be followed by a control footing that provides a summation of the department-by-department sales for that store.
- Control Heading
-
A report group that appears immediately before one or more detail groups of an RWCS-generated report. Such are produced automatically as a result of a control break. This type of group typically serves as an introduction to the detail group(s) that follow, as might be the case on a sales report for a chain of stores, where the detail groups documenting sales for each department (one department per detail group) from the same store might be preceded by a control heading that states the full name and location of the store.
- Detail Group
-
A report group that contains the detailed data being presented for the report.
- Page Footing
-
A report group that appears at the bottom of every page of an RWCS-generated report. Information typically found within such a report group might be:
- The date the report was generated
- The current page number of the report
- Page Heading
-
A report group that appears at the top of every page of an RWCS-generated report. Information typically found within such a report group might be:
- A title for the report
- The date the report was generated
- The current page number of the report
- Column headings describing the fields within the detail group(s)
- Report Footing
-
A report group that occurs only once in an RWCS-generated report — as the very last presented report group of the report. These typically serve as a visual indication that the report is finished.
- Report Group
-
One or more consecutive lines on a report that serve a common informational purpose or function. For example, lines of text that are displayed at the top or bottom of every printed page of a report.
- Report Heading
A report group that occurs only once in an RWCS-generated report — as the very first presented report group of the report. These typically serve as an introduction to the report.
9.2. The Anatomy of a Report
Every report has the same basic structure, as shown here, even though not all reports will have all of the groups shown. In fact, it is a very unusual report indeed that actually has every one of these groups:
- REPORT HEADING
- PAGE HEADING [1]
- CONTROL HEADING(S) [2]
- DETAIL GROUP(S) [2]
- CONTROL FOOTING(S) [2]
- FINAL CONTROL FOOTING
- PAGE FOOTING [1]
- REPORT FOOTING
[1] | Presented throughout the report, as needed |
[2] | Repeated, as needed |
These groups will be presented (printed) across however many formatted pages are necessary to hold them. No single report group will be allowed to cross page boundaries.
The management of paging, enforcement of the groups cannot span pages rule and almost every aspect of report generation are handled entirely by the Report Writer Control System.
9.3. The Anatomy of a Report Page
Each page of a report is divided into as many as five (5) areas, as shown in the following diagram.
_______________________________
| |
| Top-of-page Unusable Area |
—# Lines:LINES AT TOP
(LINAGE)|_______________________________|
| |
—Line #:HEADING
(RD)| Heading Area |
|_______________________________|
—Line #:FIRST DETAIL
(RD) - 1| |
—Line #:FIRST DETAIL
(RD)| |
| Body Area |
—Line #:LAST CONTROL HEADING
(RD)| |
—Line #:LAST DETAIL
(RD)|_______________________________|
—Line #:FOOTING
(RD)| |
—Line #:FOOTING
(RD) + 1| Footing Area |
|_______________________________|
| |
| Bottom-of-page Unusable Area |
—# Lines:LINES AT BOTTOM
(LINAGE)|_______________________________|
When describing a report via the RD
(see REPORT SECTION) clause, the total number of usable lines are specified as the PAGE LIMIT
value; this value is the sum of the number of lines contained in the Heading, Body and Footing Areas.
The unusable areas of a page (if any) will appear above and below that usable area. You don’t specify the unusable area in the RD
, but rather using a LINAGE
(see File/Sort-Description) clause in the FD
of the file the report is “attached” to.
The various report groups will be presentable in the various areas of a page, as follows:
REPORT HEADING
-
Heading Area — An exception to this is the situation where the report heading report group contains the
NEXT GROUP NEXT PAGE
(see NEXT GROUP) option; in those cases, the report heading will be presented on a page by itself (anywhere on that page) at the beginning of the report. PAGE HEADING
-
Heading Area
CONTROL HEADING
-
Body Area, but no line of a control heading is allowed past the line number specified by
LAST CONTROL HEADING
DETAIL
-
Body Area, but no line of a detail report group is allowed past the line number specified by
LAST DETAIL
CONTROL FOOTING
-
Body Area, but no line of a control footing report group is allowed past the line number specified by
FOOTING
PAGE FOOTING
-
Footing Area
REPORT FOOTING
Footing Area — An exception to this is the situation where the report footing report group contains the
NEXT PAGE
option in itsLINE
(see LINE) clause; in those cases, the report footing will be presented on a page by itself at the end of the report.
9.4. How RWCS Builds Report Pages
A report created via a WRITE
statement (see WRITE) will contain carriage-control information. Most notably, ASCII form-feed characters (X’0C’) will be written to the report file to support the statement’s ADVANCING PAGE
option. Whether the data for a report line created via ADVANCING PAGE
occurs before or after the form-feed character depends upon whether the programmer coded WRITE record-name BEFORE ADVANCING PAGE
or WRITE record-name AFTER ADVANCING PAGE
, respectively.
The GnuCOBOL implementation of RWCS does not issue any carriage-control information to the report files it produces — instead, it relies upon the information coded in the RD
for the report (specifically the PAGE LIMITS
and related options) and its internally-generated and managed LINE-COUNTER
special register (see Special Registers) for the report to know when to issue any blank lines to the file to fill-out the end of a printed page.
Because this is the way the GnuCOBOL RWCS works, in order to design an RWCS-generated report you’ll need to know answers to the following questions:
- What printer(s) will the report be printed on?
- What paper orientation will you use, — Landscape (long edge of the paper at the top and bottom of page), or Portrait (long edge of the paper at the left and right of page)?
- What tool will be used to print the report (direct printing to the device, notepad.exe, MS-Word, …)?
- What font and font size will be used for the report when it is printed? RWCS-generated reports will assume that a fixed-width font such as “Courier”, “Lucida Console”, “Consolas” and the like will be used to print, as variable-pitch fonts would make the proper alignment of columns of data on reports virtually impossible.
- When unprintable area exists at all four margins of the paper? These are generally caused by the printer itself or by its software driver.
- What is the maximum number of lines per page that may be printed on a single sheet of paper?
- What is the maximum number of characters that may be printed on one line?
Once you know the answer to questions 1-4, you may easily determine the answers to the remaining questions as follows:
- Prepare a text file containing 100 or so records, each consisting of a numeric scale (
123456789012345678901234
…). - Print the file in a manner consistent with your answers to questions 1-4.
- Add any necessary additional digits to each record in your test file (if lines weren’t full) or remove characters from the end of each record if lines wrapped. If you made changes, reprint the file.
- Now that you know exactly how long each record may be, add additional records and reprint. Continue until printing overflows to a second page.
- The first page you print is now a perfect template to use when designing reports — it shows, given the answers to questions 1-4, every available printable character position on a page! The number of lines printed on that page becomes your
PAGE LIMIT
value for theRD
.
The remaining PAGE LIMIT
values can be established as required by your report(s).
Using identifier rather than integer specifications in the RD
will give your program the ability — at run time — to accommodate multiple printers, fonts, font sizes and paper orientation. Just follow the above steps for each combination you wish your program to support.
9.5. Control Hierarchy
Every report that employs control breaks has a natural hierarchy of those control breaks based upon the manner in which the data the report is being generated from is sorted. This concept is best understood using an example which assumes a COBOL program to process sales data collected from every computerized cash register across a chain of stores having multiple departments is being developed.
The application that collects data from the various cash registers at each store will generate data records that look like this to a COBOL program:
01 Sales-For-Register. 05 Sales-Date PIC 9(8). 05 Time-Collected PIC 9(6). 05 Register-Number PIC 9(7). 05 Store-Number PIC 9(3). 05 Department-Number PIC 9(3). 05 Total-Sales PIC 9(6)V99.
Your task is to develop a report that shows the sales total from each cash register and summarizes those sales by department within each store, by store and also generates a total sales figure for the day across all stores.
To accomplish this, you will use a SORT
statement (see SORT) to sort the file of cash register sales data into:
- Ascending sequence of store number
- Within each store, data will be sorted into ascending sequence of department number
- If there are multiple cash registers in a particular department of a specific store, the data needs to be further sorted so that the cash registers are ordered in sequence of their register number.
So, assuming a sort file has been defined and its record layout (essentially a mirror of the raw data file) is defined as follows:
01 Sorted-Sales-For-Register. 05 Sorted-Sales-Date PIC 9(8). 05 Sorted-Time-Collected PIC 9(6). 05 Sorted-Register-Number PIC 9(7). 05 Sorted-Store-Number PIC 9(3). 05 Sorted-Department-Number PIC 9(3). 05 Sorted-Total-Sales PIC 9(6)V99.
Then the SORT
statement to accomplish the desired sequencing would be:
SORT SORT-FILE ASCENDING KEY Sorted-Store-Number Sorted-Department-Number Sorted-Register-Number USING Input-file OUTPUT PROCEDURE 100-Generate-Report
As a result of the sort, our program might expect to see data somewhat like this (date, time and sales totals are shown as “…”):
+-------------------- Register Number | +------------- Store Number | | +---------- Department Number | | | ...0535240001001... ...0589130001001... ...0625174001001... ...0122234001002... ...0732345001002... ...0003423001003... ...2038774001004... ...0112646002001... ...9963348002002... ...3245677002003... ...4456778002003... ...0002345002004...
Because of the sort, the most-frequently changing value of the three sort keys will be that of Sorted-Register-Number
. This essentially defines the “detail” level of the report.
The next most-frequently changing value is that of Sorted-Department-Number
, and the least-frequently changing value is that of Sorted-Store-Number
. remember that the program should be generating totals each time one of these two values change, plus a grand total of sales at the end of the report. These three points are the Control Break points of the report.
When the report is defined, it’s RD
would contain a CONTROLS ARE
clause that lists the control breaks in least- to most-frequent sequence of changing. This would be coded as:
CONTROLS ARE FINAL, Sorted-Store-Number, Sorted-Department-Number
A FINAL
control break only occurs once, at the very end of the report. The CONTROL FOOTING
for this break will be the one that produces the grand total of sales for all stores.
The next break listed on the CONTROLS
clause will be the one that occurs next most-frequently (Sorted-Store-Number
). This control break will be the one that produces the summation for each entire store, and will have its own CONTROL FOOTING
.
The next (and last, in this case) break listed on the CONTROLS
clause will be the one that occurs even more frequently (Sorted-Department-Number
). The CONTROL FOOTING
for this control field will be the one that summarizes sales for each department within a store.
This sequence of control breaks from least- to most-frequent (in other words, in the order they occur on the CONTROLS ARE
clause) is the ’control hierarchy’ of the report; control breaks that occur more frequently than others are said to be at a lower level in the control hierarchy.
Defining a control hierarchy (via CONTROLS ARE
) that does not match the actual sequence in which data will be processed is a great way to guarantee a “broken” report. I’ll show you an example in a later section.
9.6. An Example
This section contains an example of the RWCS at work. The complete program, presented here, is a stripped-down version of a program I have used to generate a report for a class I teach on PC hardware. This report will provide benchmark statistics on a variety of popular AMD and Intel CPUs. The data for the report was obtained from the website www.cpubenchmark.net in December of 2013. By the time you are reading this, that data will most likely have become rather out of date, but it illustrates RWCS well enough.
9.6.1. Data
Here is the data that the program will be reading. Each record reflects the aggregated benchmark scoring for one particular CPU, as scores for benchmarks against that CPU have been reported to the cpubenchmark.net website by their PassMark benchmark software. The data consists of four fields. Fields are separated from one another by a single comma. The descriptions of the fields are as follows:
- Benchmark Score
-
A five-digit number showing the aggregated benchmark scores for the CPU; the higher this number, the better the CPU performed in benchmark testing.
- Vendor
-
The name of the vendor who makes the CPU. In this data, that will either be “AMD” (American Micro Devices) or “INTEL”.
- Family
-
The 7-character family of CPU products the CPU falls into. This will have values such as “A4”, “A10”, “Core i5”, “Core i7”, etc.
- Model
The specific model of CPU within the family.
The first record of data shown below shows that the aggregated score of all benchmarks reported for the AMD A10-4600M CPU is 3145, as compared to the second record which shows that the aggregated score reported of all benchmarks reported for the Intel Core-i7-4960X CPU is 14291.
The following is the complete set of input data used for this example. This is by no means the complete set of data available at cpubenchmark.net — it is just a representative sample used for this example. For my class, I give my students a report showing the results for almost a thousand CPUs.
For the sake of brevity, this document lists the data in three columns.
03145,AMD,A10,4600M 05421,AMD,FX,6100 03917,Intel,Core i5,4300U 14291,Intel,Core i7,4960X 05813,AMD,FX,6120 01743,Intel,Core i5,4300Y 02505,AMD,A10,4655M 06194,AMD,FX,6200 04804,Intel,Core i5,4330M 03449,AMD,A10,4657M 06388,AMD,FX,6300 03604,Intel,Core i5,4350U 04251,AMD,A10,5700 07017,AMD,FX,6350 06282,Intel,Core i5,4430 02758,AMD,A10,5745M 06163,AMD,FX,8100 05954,Intel,Core i5,4430S 03332,AMD,A10,5750M 06605,AMD,FX,8120 06517,Intel,Core i5,4440 03253,AMD,A10,5757M 06845,AMD,FX,8140 07061,Intel,Core i5,4570 04798,AMD,A10,5800B 07719,AMD,FX,8150 06474,Intel,Core i5,4570R 04677,AMD,A10,5800K 08131,AMD,FX,8320 06803,Intel,Core i5,4570S 04767,AMD,A10,6700 09067,AMD,FX,8350 02503,Intel,Core i5,4570T 05062,AMD,A10,6800K 09807,AMD,FX,9370 07492,Intel,Core i5,4670 00677,AMD,A4,1200 10479,AMD,FX,9590 07565,Intel,Core i5,4670K 00559,AMD,A4,1250 03076,Intel,Core i3,3110M 06351,Intel,Core i5,4670T 01583,AMD,A4,3300 03301,Intel,Core i3,3120M 03701,Intel,Core i7,3517U 01237,AMD,A4,3300M 03655,Intel,Core i3,3130M 03449,Intel,Core i7,3517UE 01227,AMD,A4,3305M 03820,Intel,Core i3,3210 04588,Intel,Core i7,3520M 01263,AMD,A4,3310MX 02266,Intel,Core i3,3217U 03912,Intel,Core i7,3537U 01193,AMD,A4,3320M 04219,Intel,Core i3,3220 04861,Intel,Core i7,3540M 01343,AMD,A4,3330MX 03724,Intel,Core i3,3220T 04009,Intel,Core i7,3555LE 01625,AMD,A4,3400 04407,Intel,Core i3,3225 06144,Intel,Core i7,3610QE 01768,AMD,A4,3420 02575,Intel,Core i3,3227U 07532,Intel,Core i7,3610QM 01685,AMD,A4,4300M 01885,Intel,Core i3,3229Y 06988,Intel,Core i7,3612QE 01169,AMD,A4,4355M 04259,Intel,Core i3,3240 06907,Intel,Core i7,3612QM 01919,AMD,A4,5000 03793,Intel,Core i3,3240T 05495,Intel,Core i7,3615QE 01973,AMD,A4,5150M 04414,Intel,Core i3,3245 07310,Intel,Core i7,3615QM 02078,AMD,A4,5300 04757,Intel,Core i3,3250 07759,Intel,Core i7,3630QM 01632,AMD,A4,5300B 03443,Intel,Core i3,4000M 07055,Intel,Core i7,3632QM 02305,AMD,A4,6300 02459,Intel,Core i3,4010U 06516,Intel,Core i7,3635QM 01634,AMD,A6,1450 02003,Intel,Core i3,4010Y 04032,Intel,Core i7,3667U 01964,AMD,A6,3400M 04904,Intel,Core i3,4130 04271,Intel,Core i7,3687U 02101,AMD,A6,3410MX 04041,Intel,Core i3,4130T 03479,Intel,Core i7,3689Y 02078,AMD,A6,3420M 05115,Intel,Core i3,4330 08347,Intel,Core i7,3720QM 02277,AMD,A6,3430MX 05117,Intel,Core i3,4340 08512,Intel,Core i7,3740QM 01995,AMD,A6,3500 03807,Intel,Core i5,3210M 09420,Intel,Core i7,3770 02798,AMD,A6,3600 03995,Intel,Core i5,3230M 09578,Intel,Core i7,3770K 02892,AMD,A6,3620 03126,Intel,Core i5,3317U 09074,Intel,Core i7,3770S 03232,AMD,A6,3650 04101,Intel,Core i5,3320M 08280,Intel,Core i7,3770T 03327,AMD,A6,3670 05902,Intel,Core i5,3330 08995,Intel,Core i7,3820 01630,AMD,A6,4400M 05690,Intel,Core i5,3330S 08548,Intel,Core i7,3820QM 01296,AMD,A6,4455M 05781,Intel,Core i5,3335S 09025,Intel,Core i7,3840QM 02440,AMD,A6,5200 03280,Intel,Core i5,3337U 09196,Intel,Core i7,3920XM 01958,AMD,A6,5350M 02252,Intel,Core i5,3339Y 12107,Intel,Core i7,3930K 01878,AMD,A6,5357M 06282,Intel,Core i5,3340 09052,Intel,Core i7,3940XM 01906,AMD,A6,5400B 04327,Intel,Core i5,3340M 12718,Intel,Core i7,3960X 02174,AMD,A6,5400K 05372,Intel,Core i5,3340S 12823,Intel,Core i7,3970X 02384,AMD,A6,6400K 06199,Intel,Core i5,3350P 03992,Intel,Core i7,4500U 02050,AMD,A8,3500M 04314,Intel,Core i5,3360M 04507,Intel,Core i7,4558U 02426,AMD,A8,3510MX 04555,Intel,Core i5,3380M 04892,Intel,Core i7,4600M 02245,AMD,A8,3520M 03589,Intel,Core i5,3427U 04484,Intel,Core i7,4600U 02276,AMD,A8,3530MX 03479,Intel,Core i5,3437U 03680,Intel,Core i7,4610Y 02866,AMD,A8,3550MX 03057,Intel,Core i5,3439Y 04345,Intel,Core i7,4650U 03215,AMD,A8,3800 06442,Intel,Core i5,3450 07352,Intel,Core i7,4700EQ 03217,AMD,A8,3820 06071,Intel,Core i5,3450S 08161,Intel,Core i7,4700HQ 03552,AMD,A8,3850 06576,Intel,Core i5,3470 07946,Intel,Core i7,4700MQ 03682,AMD,A8,3870K 06077,Intel,Core i5,3470S 08002,Intel,Core i7,4702HQ 02709,AMD,A8,4500M 04591,Intel,Core i5,3470T 07647,Intel,Core i7,4702MQ 02193,AMD,A8,4555M 05991,Intel,Core i5,3475S 08066,Intel,Core i7,4750HQ 04052,AMD,A8,5500 06828,Intel,Core i5,3550 07367,Intel,Core i7,4765T 03464,AMD,A8,5500B 06631,Intel,Core i5,3550S 09969,Intel,Core i7,4770 02434,AMD,A8,5545M 06993,Intel,Core i5,3570 10190,Intel,Core i7,4770K 03052,AMD,A8,5550M 07118,Intel,Core i5,3570K 09803,Intel,Core i7,4770S 02935,AMD,A8,5557M 06709,Intel,Core i5,3570S 08803,Intel,Core i7,4770T 04348,AMD,A8,5600K 05414,Intel,Core i5,3570T 10078,Intel,Core i7,4771 04390,AMD,A8,6500 04333,Intel,Core i5,4200M 08567,Intel,Core i7,4800MQ 04719,AMD,A8,6600K 03355,Intel,Core i5,4200U 09969,Intel,Core i7,4820K 04055,AMD,FX,4100 02358,Intel,Core i5,4200Y 09331,Intel,Core i7,4850HQ 04153,AMD,FX,4130 02382,Intel,Core i5,4210Y 09323,Intel,Core i7,4900MQ 04094,AMD,FX,4150 03482,Intel,Core i5,4250U 13620,Intel,Core i7,4930K 04774,AMD,FX,4170 04381,Intel,Core i5,4258U 09754,Intel,Core i7,4930MX 04711,AMD,FX,4300 04663,Intel,Core i5,4288U 10262,Intel,Core i7,4960HQ 05247,AMD,FX,4350 04786,Intel,Core i5,4300M
9.6.2. Program
Here is the program that will be producing the report. Pay attention to how the data is sorted and how the control hierarchy (CONTROLS ARE
) relates to the SORT
.
IDENTIFICATION DIVISION. PROGRAM-ID. DEMORWCS. ENVIRONMENT DIVISION. CONFIGURATION SECTION. REPOSITORY. FUNCTION ALL INTRINSIC. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT CPU-FILE ASSIGN TO "CPUDATA.txt" LINE SEQUENTIAL. SELECT REPORT-FILE ASSIGN TO "CPUREPORT.txt" LINE SEQUENTIAL. SELECT SORT-FILE ASSIGN TO DISK. DATA DIVISION. FILE SECTION. FD CPU-FILE. 01 CPU-REC PIC X(26). FD REPORT-FILE REPORT IS CPU-Report. SD SORT-FILE. 01 SORT-REC. 05 F-SR-Score-NUM PIC 9(5). 05 F-SR-Vendor-TXT PIC X(5). 05 F-SR-Family-TXT PIC X(7). 05 F-SR-Model-TXT PIC X(6). WORKING-STORAGE SECTION. 01 WS-Date PIC 9(8). 01 WS-Family-Counters. 05 WS-FC-AVE PIC 9(5)V99. 05 WS-FC-Qty BINARY-LONG. 05 WS-FC-Total-NUM BINARY-LONG. 01 WS-Flags. 05 WS-F-EOF PIC X(1). 01 WS-One-Const PIC 9 VALUE 1. 01 WS-Overall-Counters. 05 WS-OC-AVE PIC 9(5)V99. 05 WS-OC-Qty BINARY-LONG. 05 WS-OC-Total-NUM BINARY-LONG. 01 WS-Starz PIC X(44) VALUE ALL '*'. 01 WS-Vendor-Counters. 05 WS-VC-AVE PIC 9(5)V99. 05 WS-VC-Qty BINARY-LONG. 05 WS-VC-Total-NUM BINARY-LONG. REPORT SECTION. RD CPU-Report CONTROLS ARE FINAL F-SR-Vendor-TXT F-SR-Family-TXT PAGE LIMIT IS 36 LINES HEADING 1 FIRST DETAIL 5 LAST DETAIL 36. 01 TYPE IS PAGE HEADING. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Date PIC 9999/99/99. 10 COL 14 VALUE 'CPU Benchmark Scores'. 10 COL 37 VALUE 'Page:'. 10 COL 43 SOURCE PAGE-COUNTER PIC Z9. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Starz PIC X(44). 05 LINE NUMBER PLUS 1. 10 COL 1 VALUE '**'. 10 COL 6 VALUE 'All CPU Data From cpubenchmark.net'. 10 COL 43 VALUE '**'. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Starz PIC X(44). 01 TYPE CONTROL HEADING F-SR-Family-TXT. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE F-SR-Vendor-TXT PIC X(6). 10 COL 8 SOURCE F-SR-Family-TXT PIC X(7). 05 LINE NUMBER PLUS 1. 10 COL 1 VALUE 'Family'. 10 COL 9 VALUE 'Model'. 10 COL 16 VALUE 'Benchmark Score (High to Low)'. 05 LINE NUMBER PLUS 1. 10 COL 1 VALUE '======'. 10 COL 9 VALUE '======'. 10 COL 16 VALUE '============================='. 01 Detail-Line TYPE IS DETAIL. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE F-SR-Family-TXT PIC X(7) GROUP INDICATE. 10 COL 9 PIC X(6) SOURCE F-SR-Model-TXT. 10 COL 16 PIC ZZZZ9 SOURCE F-SR-Score-NUM. 01 End-Family TYPE IS CONTROL FOOTING F-SR-Family-TXT. 05 LINE NUMBER PLUS 1. 10 COL 9 VALUE 'Ave...'. 10 COL 16 PIC ZZZZ9.99 SOURCE WS-FC-AVE. 10 COL 25 VALUE '('. 10 COL 26 PIC ZZ9 SUM WS-One-Const. 10 COL 30 VALUE 'Family CPUs)'. 01 End-Vendor TYPE IS CONTROL FOOTING F-SR-Vendor-TXT. 05 LINE NUMBER PLUS 1. 10 COL 9 VALUE 'Ave...'. 10 COL 16 PIC ZZZZ9.99 SOURCE WS-VC-AVE. 10 COL 25 VALUE '('. 10 COL 26 PIC ZZ9 SUM WS-One-Const. 10 COL 30 VALUE 'Vendor CPUs)'. 01 End-Overall TYPE IS CONTROL FOOTING FINAL. 05 LINE NUMBER PLUS 1. 10 COL 9 VALUE 'Ave...'. 10 COL 16 PIC ZZZZ9.99 SOURCE WS-OC-AVE. 10 COL 25 VALUE '('. 10 COL 26 PIC ZZ9 SUM WS-One-Const. 10 COL 30 VALUE 'CPUs)'. PROCEDURE DIVISION. DECLARATIVES. 000-End-Family SECTION. USE BEFORE REPORTING End-Family. 1. IF WS-FC-Qty > 0 COMPUTE WS-FC-AVE = WS-FC-Total-NUM / WS-FC-Qty ELSE MOVE 0 TO WS-FC-AVE END-IF MOVE 0 TO WS-FC-Qty WS-FC-Total-NUM . 000-End-Vendor SECTION. USE BEFORE REPORTING End-Vendor. 1. IF WS-VC-Qty > 0 COMPUTE WS-VC-AVE = WS-VC-Total-NUM / WS-VC-Qty ELSE MOVE 0 TO WS-VC-AVE END-IF MOVE 0 TO WS-VC-Qty WS-VC-Total-NUM . 000-End-Overall SECTION. USE BEFORE REPORTING End-Overall. 1. IF WS-OC-Qty > 0 COMPUTE WS-OC-AVE = WS-OC-Total-NUM / WS-OC-Qty ELSE MOVE 0 TO WS-OC-AVE END-IF MOVE 0 TO WS-OC-Qty WS-OC-Total-NUM . END DECLARATIVES. 010-Main SECTION. 1. ACCEPT WS-Date FROM DATE YYYYMMDD SORT SORT-FILE ASCENDING KEY F-SR-Vendor-TXT F-SR-Family-TXT DESCENDING KEY F-SR-Score-NUM ASCENDING KEY F-SR-Model-TXT INPUT PROCEDURE 100-Pre-Process-Data OUTPUT PROCEDURE 200-Generate-Report STOP RUN . 100-Pre-Process-Data SECTION. 1. OPEN INPUT CPU-FILE PERFORM FOREVER READ CPU-FILE AT END EXIT PERFORM END-READ MOVE SPACES TO SORT-REC UNSTRING CPU-REC DELIMITED BY ',' INTO F-SR-Score-NUM, F-SR-Vendor-TXT, F-SR-Family-TXT, F-SR-Model-TXT RELEASE SORT-REC END-PERFORM CLOSE CPU-FILE . 200-Generate-Report SECTION. 1. INITIALIZE WS-Family-Counters WS-Flags OPEN OUTPUT REPORT-FILE INITIATE CPU-Report RETURN SORT-FILE AT END MOVE 'Y' TO WS-F-EOF END-RETURN PERFORM UNTIL WS-F-EOF = 'Y' GENERATE Detail-Line ADD 1 TO WS-FC-Qty WS-OC-Qty WS-VC-Qty ADD F-SR-Score-NUM TO WS-FC-Total-NUM WS-OC-Total-NUM WS-VC-Total-NUM RETURN SORT-FILE AT END MOVE 'Y' TO WS-F-EOF END-RETURN END-PERFORM TERMINATE CPU-Report CLOSE REPORT-FILE .
9.6.3. Generated Report Pages
Finally, here’s the report the program generates!
2013/12/24 CPU Benchmark Scores Page: 1 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** AMD A10 Family Model Benchmark Score (High to Low) ====== ====== ============================= A10 6800K 5062 5800B 4798 6700 4767 5800K 4677 5700 4251 4657M 3449 5750M 3332 5757M 3253 4600M 3145 5745M 2758 4655M 2505 Ave... 3817.90 ( 11 Family CPUs) AMD A4 Family Model Benchmark Score (High to Low) ====== ====== ============================= A4 6300 2305 5300 2078 5150M 1973 5000 1919 3420 1768 4300M 1685 5300B 1632 3400 1625 3300 1583 3330MX 1343 3310MX 1263 3300M 1237 3305M 1227 3320M 1193 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 2 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** A4 4355M 1169 1200 677 1250 559 Ave... 1484.47 ( 17 Family CPUs) AMD A6 Family Model Benchmark Score (High to Low) ====== ====== ============================= A6 3670 3327 3650 3232 3620 2892 3600 2798 5200 2440 6400K 2384 3430MX 2277 5400K 2174 3410MX 2101 3420M 2078 3500 1995 3400M 1964 5350M 1958 5400B 1906 5357M 1878 1450 1634 4400M 1630 4455M 1296 Ave... 2220.22 ( 18 Family CPUs) AMD A8 Family Model Benchmark Score (High to Low) ====== ====== ============================= A8 6600K 4719 6500 4390 5600K 4348 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 3 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** A8 5500 4052 3870K 3682 3850 3552 5500B 3464 3820 3217 3800 3215 5550M 3052 5557M 2935 3550MX 2866 4500M 2709 5545M 2434 3510MX 2426 3530MX 2276 3520M 2245 4555M 2193 3500M 2050 Ave... 3148.68 ( 19 Family CPUs) AMD FX Family Model Benchmark Score (High to Low) ====== ====== ============================= FX 9590 10479 9370 9807 8350 9067 8320 8131 8150 7719 6350 7017 8140 6845 8120 6605 6300 6388 6200 6194 8100 6163 6120 5813 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 4 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** FX 6100 5421 4350 5247 4170 4774 4300 4711 4130 4153 4150 4094 4100 4055 Ave... 6457.00 ( 19 Family CPUs) Ave... 3448.86 ( 84 Vendor CPUs) Intel Core i3 Family Model Benchmark Score (High to Low) ====== ====== ============================= Core i3 4340 5117 4330 5115 4130 4904 3250 4757 3245 4414 3225 4407 3240 4259 3220 4219 4130T 4041 3210 3820 3240T 3793 3220T 3724 3130M 3655 4000M 3443 3120M 3301 3110M 3076 3227U 2575 4010U 2459 3217U 2266 4010Y 2003 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 5 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** Core i3 3229Y 1885 Ave... 3677.76 ( 21 Family CPUs) Intel Core i5 Family Model Benchmark Score (High to Low) ====== ====== ============================= Core i5 4670K 7565 4670 7492 3570K 7118 4570 7061 3570 6993 3550 6828 4570S 6803 3570S 6709 3550S 6631 3470 6576 4440 6517 4570R 6474 3450 6442 4670T 6351 3340 6282 4430 6282 3350P 6199 3470S 6077 3450S 6071 3475S 5991 4430S 5954 3330 5902 3335S 5781 3330S 5690 3570T 5414 3340S 5372 4330M 4804 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 6 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** Core i5 4300M 4786 4288U 4663 3470T 4591 3380M 4555 4258U 4381 4200M 4333 3340M 4327 3360M 4314 3320M 4101 3230M 3995 4300U 3917 3210M 3807 4350U 3604 3427U 3589 4250U 3482 3437U 3479 4200U 3355 3337U 3280 3317U 3126 3439Y 3057 4570T 2503 4210Y 2382 4200Y 2358 3339Y 2252 4300Y 1743 Ave... 5026.13 ( 52 Family CPUs) Intel Core i7 Family Model Benchmark Score (High to Low) ====== ====== ============================= Core i7 4960X 14291 4930K 13620 3970X 12823 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 7 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** Core i7 3960X 12718 3930K 12107 4960HQ 10262 4770K 10190 4771 10078 4770 9969 4820K 9969 4770S 9803 4930MX 9754 3770K 9578 3770 9420 4850HQ 9331 4900MQ 9323 3920XM 9196 3770S 9074 3940XM 9052 3840QM 9025 3820 8995 4770T 8803 4800MQ 8567 3820QM 8548 3740QM 8512 3720QM 8347 3770T 8280 4700HQ 8161 4750HQ 8066 4702HQ 8002 4700MQ 7946 3630QM 7759 4702MQ 7647 3610QM 7532 4765T 7367 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 8 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** Core i7 4700EQ 7352 3615QM 7310 3632QM 7055 3612QE 6988 3612QM 6907 3635QM 6516 3610QE 6144 3615QE 5495 4600M 4892 3540M 4861 3520M 4588 4558U 4507 4600U 4484 4650U 4345 3687U 4271 3667U 4032 3555LE 4009 4500U 3992 3537U 3912 3517U 3701 4610Y 3680 3689Y 3479 3517UE 3449 Ave... 7725.58 ( 58 Family CPUs) Ave... 6005.16 (131 Vendor CPUs) Ave... 5006.42 (215 CPUs) ____________________________________________
9.7. Control Hierarchy (Revisited)
The sample program just discussed presents a great opportunity to show what can happen if you don’t define the control hierarchy of a report properly.
I changed the CONTROLS ARE
clause on the sample program from this:
CONTROLS ARE FINAL F-SR-Vendor-TXT F-SR-Family-TXT
To this:
CONTROLS ARE FINAL F-SR-Family-TXT F-SR-Vendor-TXT
And then ran the report again. Here are the first two pages of that new report. See what happened to the control breaks?
2013/12/24 CPU Benchmark Scores Page: 1 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** AMD A10 Family Model Benchmark Score (High to Low) ====== ====== ============================= A10 6800K 5062 5800B 4798 6700 4767 5800K 4677 5700 4251 4657M 3449 5750M 3332 5757M 3253 4600M 3145 5745M 2758 4655M 2505 Ave... 3817.90 ( 11 Vendor CPUs) Ave... 3817.90 ( 11 Family CPUs) AMD A4 Family Model Benchmark Score (High to Low) ====== ====== ============================= A4 6300 2305 5300 2078 5150M 1973 5000 1919 3420 1768 4300M 1685 5300B 1632 3400 1625 3300 1583 3330MX 1343 3310MX 1263 3300M 1237 3305M 1227 ____________________________________________ 2013/12/24 CPU Benchmark Scores Page: 2 ******************************************** ** All CPU Data From cpubenchmark.net ** ******************************************** A4 3320M 1193 4355M 1169 1200 677 1250 559 Ave... 1484.47 ( 17 Vendor CPUs) Ave... 1484.47 ( 17 Family CPUs) AMD A6 Family Model Benchmark Score (High to Low) ====== ====== ============================= A6 3670 3327 3650 3232 3620 2892 3600 2798 5200 2440 6400K 2384 3430MX 2277 5400K 2174 3410MX 2101 3420M 2078 3500 1995 3400M 1964 5350M 1958 5400B 1906 5357M 1878 1450 1634 4400M 1630 4455M 1296 Ave... 2220.22 ( 18 Vendor CPUs) Ave... 2220.22 ( 18 Family CPUs) AMD A8 Family Model Benchmark Score (High to Low) ====== ====== ============================= A8 6600K 4719 ____________________________________________
9.8. Turning PHYSICAL Page Formatting Into LOGICAL Formatting
You can trick RWCS into using the PAGE LIMIT
values as logical specifications rather than physical ones quite easily — simply include an ASCII form-feed (X'0C'
) character into your page heading design! Here’s how the sample program shown earlier could be easily modified:
Simply Change This…
01 TYPE IS PAGE HEADING. 05 LINE NUMBER 1. 10 COL 1 SOURCE WS-Date PIC 9999/99/99. 10 COL 14 VALUE 'CPU Benchmark Scores'. 10 COL 37 VALUE 'Page:'. 10 COL 43 SOURCE PAGE-COUNTER PIC Z9. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Starz PIC X(44). 05 LINE NUMBER PLUS 1. 10 COL 1 VALUE '**'. 10 COL 6 VALUE 'All CPU Data From ' & 'cpubenchmark.net'. 10 COL 43 VALUE '**'. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Starz PIC X(44).
To This…
01 TYPE IS PAGE HEADING. 05 LINE NUMBER 1. *> NEW 10 COL 1 VALUE X’0C’. *> NEW 05 LINE NUMBER PLUS 1. *> CHANGED 10 COL 1 SOURCE WS-Date PIC 9999/99/99. 10 COL 14 VALUE 'CPU Benchmark Scores'. 10 COL 37 VALUE 'Page:'. 10 COL 43 SOURCE PAGE-COUNTER PIC Z9. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Starz PIC X(44). 05 LINE NUMBER PLUS 1. 10 COL 1 VALUE '**'. 10 COL 6 VALUE 'All CPU Data From ' & 'cpubenchmark.net'. 10 COL 43 VALUE '**'. 05 LINE NUMBER PLUS 1. 10 COL 1 SOURCE WS-Starz PIC X(44).
RWCS will still be counting lines to decide when to close off one page and start a new one, but when a new page is started its page heading will physically form-feed the printer when the report is printed. As long as any printer you plan on using supports at least as many physical print lines as what is defined as the PAGE LIMIT
value in whatever paper orientation and font you plan on (or are limited to) printing in, you have now divorced your program from the physical realities of the printer!
Of course, whatever software you are using to deliver the printed document to the printer with, must allow the ASCII form-feed character to pass through to the printer.
10. Interfacing With The OS
10.1. Compiling Programs
Program source files should have extensions of .cob or .cbl.
Program file names should match exactly the specification of PROGRAM-ID
(including case).
Spaces cannot be included in primary entry-point names and therefore should not be included in program file names.
The GnuCOBOL compiler will translate your COBOL program into C source code, compile that C source code into executable binary form using the C compiler specified when GnuCOBOL was built and link that executable binary into:
- Directly executable form
-
This is an executable file directly-executable from the command-line. On Windows computers, this would be an .exe file. On Unix systems, this will be a file with no specific extension, but with execute permissions. This file will include the main program as well as any static-linked subprograms.
- Static-linkable form
-
This is a single subprogram compiled into object-code form, ready to be linked in with a main program to form a directly-executable program. On windows computers, these generally are .o (object-code) files.
- Dynamically-loadable executable form
These are dynamically-loadable object code files ready to be invoked from other programs at execution time. On Windows systems, these would be .dll files, while on Unix systems they are typically .so files (OSX uses .dylib).
10.1.1. cobc - The GnuCOBOL Compiler
The GnuCOBOL compiler is named cobc
(cobc.exe
on a Windows system).
The following describes the syntax and option switches of the cobc command. This information may be displayed by entering the command cobc --help
or cobc -h
.
GnuCOBOL compiler for most COBOL dialects with lots of extensions as of v3.1. Usage: cobc [options]... file... Options: -h, -help display this help and exit -V, -version display compiler version and exit -i, -info display compiler information (build/environment) and exit -v, -verbose display compiler version and the commands invoked by the compiler -vv, -verbose=2 like -v but additional pass verbose option to assembler/compiler -vvv, -verbose=3 like -vv but additional pass verbose option to linker -q, -brief reduced displays, commands invoked not shown -### like -v but commands not executed -x build an executable program -m build a dynamically loadable module (default) -j [<args>], -job[=<args>] run program after build, passing <args> -std=<dialect> warnings/features for a specific dialect <dialect> can be one of: default, cobol2014, cobol2002, cobol85, xopen, ibm-strict, ibm, mvs-strict, mvs, mf-strict, mf, bs2000-strict, bs2000, acu-strict, acu, rm-strict, rm; see configuration files in directory config -F, -free use free source format -fixed use fixed source format (default) -O, -O2, -O3, -Os enable optimization -O0 disable optimization -g enable C compiler debug / stack check / trace -d, -debug enable all run-time error checking -o <file> place the output into <file> -b combine all input files into a single dynamically loadable module -E preprocess only; do not compile or link -C translation only; convert COBOL to C -S compile only; output assembly file -c compile and assemble, but do not link -T <file> generate and place a wide program listing into <file> -t <file> generate and place a program listing into <file> --tlines=<lines> specify lines per page in listing, default = 55 -P[=<dir or file>] generate preprocessed program listing (.lst) -Xref generate cross reference through 'cobxref' (V. Coen's 'cobxref' must be in path) {This uses the internal tool only. See 10.1.1.1 for example output. To use Cobxref you must run this separately. See second example as 10.1.1.2} -I <directory> add <directory> to copy/include search path -L <directory> add <directory> to library search path -l <lib> link the library <lib> -A <options> add <options> to the C compile phase -Q <options> add <options> to the C link phase -D <define> define <define> for COBOL compilation -K <entry> generate CALL to <entry> as static -conf=<file> user-defined dialect configuration; see -std -list-reserved display reserved words -list-intrinsics display intrinsic functions -list-mnemonics display mnemonic names -list-system display system routines -save-temps[=<dir>] save intermediate files * default: current directory -ext <extension> add file extension for resolving COPY Warning options: -W enable all warnings -Wall enable most warnings (all except as noted below) -Warchaic warn if archaic features are used -Warithmetic-osvs warn if arithmetic expression precision has changed -Wcall-params warn about non 01/77 items for CALL parameters * NOT set with -Wall -Wcolumn-overflow warn about text after program-text area, FIXED format * NOT set with -Wall -Wconstant-expression warn about expressions that always resolve to true/false -Wcorresponding warn about CORRESPONDING with no matching items -Werror treat all warnings as errors -Werror=<warning> treat specified <warning> as error -Wimplicit-define warn about implicitly defined data items -Winitial-value warn if initial VALUE clause is ignored -Wlinkage warn about dangling LINKAGE items * NOT set with -Wall -Wno-<warning> disable warning enabled by -W or -Wall -Wno-dialect do not warn about dialect specific issues * ALWAYS active -Wno-pending do not warn if pending features are mentioned * ALWAYS active -Wno-unfinished do not warn if unfinished features are used * ALWAYS active -Wobsolete warn if obsolete features are used -Wothers do not warn about different issues * ALWAYS active -Woverlap warn about overlapping MOVE of items -Wparentheses warn about lack of parentheses around AND within OR -Wpossible-overlap warn about MOVE of items that may overlap depending on variables * NOT set with -Wall -Wpossible-truncate warn about possible field truncation * NOT set with -Wall -Wprototypes warn about missing FUNCTION prototypes/definitions -Wredefinition warn about incompatible redefinition of data items -Wstrict-typing warn strictly about type mismatch -Wterminator warn about lack of scope terminator END-XXX * NOT set with -Wall -Wtruncate warn about field truncation from constant assignments -Wunreachable warn about likely unreachable statements * NOT set with -Wall Compiler options: -facucomment '$' in indicator area treated as '*', '|' treated as floating comment -fcallfh=<function> use external provided EXTFH interface module <function> for I/O -fdebugging-line enable debugging lines * 'D' in indicator column or floating >>D -fdefaultbyte=<value> initialize fields without VALUE to value * decimal 0..255 or any quoted character * default: initialize to picture -fdump=<scope> dump data fields on abort, <scope> may be a combination of: ALL, WS, LS, RD, FD, SC -ffold-call=[UPPER|LOW ER] fold PROGRAM-ID, CALL, CANCEL subject to value * default: no transformation -ffold-copy=[UPPER|LOW ER] fold COPY subject to value * default: no transformation -fibmcomp sets -fbinary-size=2-4-8 -fsynchronized-clause=ok -fimplicit-init automatic initialization of the COBOL runtime system -finline-intrinsic whe n possible resolve intrinsic FUNCTIONs at compile time -fintrinsics=[ALL|intr insic function name(,name,...)] intrinsics to be used without FUNCTION keyword -fmax-errors=<number> maximum number of errors to report before compilation is aborted * default: 100 -fmf-files Sequential & Relative files will match Micro Focus format -fmfcomment '*' or '/' in column 1 treated as comment * FIXED format only -fno-gen-c-decl-static -call disable generation of C function declarations for subroutines with static CALL -fno-ibmcomp sets -fbinary-size=1--8 -fsynchronized-clause=ignore -fno-recursive-check disable check of recursive program call; effectively compiling as RECURSIVE program -fno-remove-unreachabl e disable remove of unreachable code * turned off by -g -fno-theaders suppress all headers and output of compilation options from listing while keeping page breaks -fno-tmessages suppress warning and error summary from listing -fno-tsource suppress source from listing -fnotrunc allow numeric field overflow * non-ANSI behaviour -fodoslide adjust items following OCCURS DEPENDING * implies -fcomplex-odo -foptional-file treat all files as OPTIONAL * unless NOT OPTIONAL specified -fsign=[ASCII|EBCDIC] define display sign representation * default: machine native -fsingle-quote use a single quote (apostrophe) for QUOTE * default: double quote -fsource-location generate source location code * turned on by -debug/-g/-ftraceall -fstack-check PERFORM stack checking * turned on by -debug or -g -fstatic-call output static function calls for the CALL statement -fsyntax-only syntax error checking only; don't emit any output -ftrace generate trace code * scope: executed SECTION/PARAGRAPH -ftraceall generate trace code * scope: executed SECTION/PARAGRAPH/STATEMENTS * turned on by -debug -ftsymbols specify symbols in listing -fwrite-after use AFTER 1 for WRITE of LINE SEQUENTIAL * default: BEFORE 1 Compiler dialect configuration options: -faccept-auto Set WITH AUTO clause as default for ACCEPT dest-item, instead of WITH TAB -faccept-display-extensions=<support> Extensions to ACCEPT and DISPLAY -faccept-update Set WITH UPDATE clause as default for ACCEPT dest-item, instead of WITH NO UPDATE -facu-literals=<support> ACUCOBOL-GT literals (#B #O #H #X) -falter-statement=<support> ALTER statement -farithmetic-osvs Limit precision in intermediate results to precision of final result (less accurate) -fassign-clause=<value> Set way of interpreting ASSIGN -fbinary-byteorder=<value> Binary byte order, may be one of: native, big-endian -fbinary-comp-1 COMP-1 is a 16-bit signed integer -fbinary-size=<value> Binary byte size - defines the allocated bytes according to PIC, may be one of: 2-4-8, 1-2-4-8, 1--8 -fbinary-sync-clause=<support> BINARY-SHORT/LONG/DOUBLE SYNCHRONIZED clause -fbinary-truncate Numeric truncation according to ANSI -fcall-convention-linkage=<support> Specifying call-convention by WITH ... LINKAGE -fcall-convention-mnemonic=<support> Specifying call-convention by mnemonic -fcall-overflow=<support> OVERFLOW clause for CALL -fcomment-paragraphs=<support> Comment paragraphs in IDENTIFICATION DIVISION (AUTHOR, DATE-WRITTEN, ...) -fcomplex-odo Allow complex OCCURS DEPENDING ON -fconsole-is-crt Assume CONSOLE IS CRT if not set otherwise -fconstant-01=<support> Constant with level 01 CONSTANT AS/FROM item -fconstant-78=<support> Constant with level 78 item (note: has left to right precedence in expressions) -fconstant-folding Evaluate constant expressions at compile time -fcontinue-after=<support> AFTER phrase in CONTINUE statement -fdata-records-clause=<support> DATA-RECORDS clause -fdebugging-mode=<support> DEBUGGING MODE and debugging indicator -fdefine-constant-directive=<support> Allow >> DEFINE CONSTANT var AS literal -fdepending-on-not-fixed=<support> Depending-on-not-fixed -fdisplay-special-fig-consts Special behaviour of DISPLAY SPACE/ALL X'01'/ALL X'02'/ALL X'07' -fentry-statement=<support> ENTRY statement -ffilename-mapping Resolve file names at run time using environment variables. -ffree-redefines-position=<support> REDEFINES clause not following entry-name in definition -fgoto-entry=<support> ENTRY FOR GOTO and GOTO ENTRY statements -fgoto-statement-without-name=<support> GOTO statement without name -fhexadecimal-boolean=<support> Hexadecimal-boolean literals (BX'A') -fhexadecimal-national-literals=<support> Hexadecimal-national literals (NX'265E') -fhostsign Allow hexadecimal value 'F' for NUMERIC test of signed PACKED DECIMAL field -fhp-octal-literals=<support> HP COBOL octal literals (%377) -fincorrect-conf-sec-order=<support> Incorrect order of CONFIGURATION SECTION paragraphs -findirect-redefines Allow REDEFINES to other than last equal level number -flabel-records-clause=<support> LABEL-RECORDS clause -flarger-redefines-ok Allow larger REDEFINES items -flength-in-data-division Length in data division -fline-col-zero-default Assume the first item in a field DISPLAY goes at LINE 0 COL 0, not LINE 1 COL 1 -flisting-statements=<support> Listing-directive statements EJECT, SKIP1, SKIP2, SKIP3 -fliteral-length=<number> Maximum literal size in general -fmemory-size-clause=<support> MEMORY-SIZE clause -fmissing-statement=<support> Missing statement (e.g. empty IF / PERFORM) -fmove-figurative-constant-to-numeric=<support> Move figurative constants to numeric -fmove-figurative-quote-to-numeric=<support> Move figurative constant QUOTE to numeric -fmove-figurative-space-to-numeric=<support> Move figurative constant SPACE to numeric -fmove-ibm MOVE operates as on IBM (left to right, byte by byte), otherwise no propagating move -fmove-non-numeric-lit-to-numeric-is-zero Imply zero in move of non-numeric literal to numeric items -fmove-noninteger-to-alphanumeric=<support> Move noninteger to alphanumeric -fmultiple-file-tape-clause=<support> MULTIPLE-FILE-TAPE clause -fnational-character-literals=<support> Non-standard national literals (NC'UTF-16 string') -fnational-literals=<support> National literals (N'UTF-16 string') -fnext-sentence-phrase=<support> NEXT SENTENCE phrase -fno-echo-means-secure NO-ECHO Hides input with asterisks like SECURE -fnonnumeric-with-numeric-group-usage=<support> Non-Numeric item with Numeric Group USAGE clause -fnot-exception-before-exception=<support> NOT ON EXCEPTION before ON EXCEPTION -fnumeric-boolean=<support> Boolean literals (B'1010') -fnumeric-literal-length=1..38 Maximum numeric literal size -fnumeric-value-for-edited-item=<support> Numeric literals in VALUE clause of numeric-edited items -foccurs-max-length-without-subscript Occurs max length without subscript -fodo-without-to=<support> OCCURS DEPENDING ON without to -fpadding-character-clause=<support> PADDING CHARACTER clause -fperform-osvs exit point of any currently executing perform is recognized if reached -fperform-varying-without-by=<support> PERFORM VARYING without BY phrase (implies BY 1) -fpic-length=<number> Maximum number of characters allowed in the PICTURE character-string -fpretty-display Alternate formatting of numeric fields -fprogram-name-redefinition Program names don't lead to a reserved identifier -fprogram-prototypes=<support> CALL/CANCEL with program-prototype-name -frecord-delim-with-fixed-recs=<support> RECORD DELIMITER clause on file with fixed-length records -frecord-delimiter=<support> RECORD DELIMITER clause -frecords-mismatch-record-clause=<support> Record sizes does not match RECORD clause -freference-out-of-declaratives=<support> References to sections not in DECLARATIVES from within DECLARATIVES -frelax-level-hierarchy Allow non-matching level numbers -frelax-syntax-checks Allow certain syntax variations (e.g. REDEFINES position) -frenames-uncommon-levels=<support> RENAMES of 01-, 66- and 77-level items -freserved-words=<value> Use of complete/fixed reserved words -fscreen-section-rules=<value> Which compiler's rules to apply to SCREEN SECTION item clauses -fsection-segments=<support> Section segments -fselect-working Require ASSIGN USING items to be in WORKING-STORAGE -fsequential-delimiters=<support> BINARY-SEQUENTIAL and LINE-SEQUENTIAL phrases in RECORD DELIMITER -fsticky-linkage LINKAGE-SECTION items remain allocated between invocations -fstop-identifier-statement=<support> STOP-identifier statement -fstop-literal-statement=<support> STOP-literal statement -fsymbolic-constant=<support> Constants defined in SPECIAL-NAMES -fsynchronized-clause=<support> SYNCHRONIZED clause -ftab-width=1..12 Set number of spaces that are assumed for tabs -ftext-column=72..255 Set right margin for source (fixed format only) -ftitle-statement=<support> Listing-directive statement TITLE -ftop-level-occurs-clause=<support> OCCURS clause on top-level -fuse-for-debugging=<support> USE FOR DEBUGGING -fvalue-of-clause=<support> VALUE-OF clause -fword-continuation=<support> Continuation of COBOL words -fword-length=1..63 Maximum word-length for COBOL (= programmer defined) words -fxml-generate-extra-phrases=<support> XML GENERATE's phrases other than COUNT IN -fzero-length-literals=<support> Zero-length literals, e.g. '@w{}' and "" where <support> is one of the following: 'ok', 'warning', 'archaic', 'obsolete', 'skip', 'ignore', 'error', 'unconformable' -fnot-reserved=<word> Word to be taken out of the reserved words list -freserved=<word> Word to be added to reserved words list -freserved=<word>:<alias> Word to be added to reserved words list as alias -fnot-register=<word> Special register to disable -fregister=<word> Special register to enable
Each file specified on the cobc
command constitutes a Compilation Unit. A compilation unit may be a single GnuCOBOL program — with or without nested subprograms(see Independent vs Contained vs Nested Subprograms) — or multiple GnuCOBOL programs, separated by END PROGRAM
or END FUNCTION
marker lines, as appropriate. See Independent vs Contained vs Nested Subprograms, for some examples of these marker lines.
A compilation unit may also be a C-language source program, recognized as such by having a file extension of .c
or an assembly-language program, recognized by its file extension of .s. In such a case, COBOL compilation of that file will be bypassed by the cobc
command; instead, the file will be passed directly to the C compiler or assembler (executed automatically by cobc
).
A compilation unit may also be an object-code module (output from the C compiler), recognized as such by having a file extension of .o
. In these situations, all compilation will be bypassed, and the object code will be “bound” into the generated executable by the linker (an ld
command executed internally by the cobc
command).
Pre-compiled object-code subprograms may be automatically located by the GnuCOBOL compiler and the loader by using the LD_LIBRARY_PATH
compilation-time environment variable (see Compilation Time Environment Variables). If they are locatable through that environment variable, they need not be named on the cobc
command.
The collection of compilation units supplied on a single cobc
execution constitute a Compilation Group. All executable code produced from a single compilation group will be collected together into a single executable file, whose filename will be the same as that of the first compilation unit specified on the cobc
command.
The simplest mode of compilation is to generate a single executable file from one or more GnuCOBOL source files:
cobc -x mainprog.cbl sub1.cbl sub2.cbl
The main program must be the first program found in the first compilation unit (mainprog.cbl). The remainder of that compilation unit as well as the rest of the files in the compilation group (sub1.cbl and sub2.cbl) must be independent and/or contained subprograms (see Independent vs Contained vs Nested Subprograms).
This command assumes that all source files are in the directory from which the cobc
command was executed. You are, of course, free to include full pathnames with any filename, if necessary.
With the -x switch on the compiler command, a single directly-executable executable file (UNIX, Windows/Cygwin, OSX) or “exe” file (Windows, Windows/MinGW) will be generated. This executable file has the compiled code for all COBOL programs contained within the compilation group specified on the cobc
command included in the file.
Any subroutines or user-defined functions that weren’t included in any of the source files comprising the compilation group will be treated as dynamically loadable subprograms (see Dynamic vs Static Subprograms).
Optionally, the -o switch may be used in addition to -x
to specify the name of the generated executable file. If -o switch is not specified, the filename of the 1st compilation unit will be used as the name of the executable file. The appropriate extension for the generated file (.exe, on a Windows computer, for example) will be added to the filename that is explicitly specified or implicitly assumed for the output file.
Compilations may be performed to generate dynamically-loadable modules (or dynamically-loadable libraries, as they are frequently called). These compilations are performed by using the -m switch instead of -x switch:
cobc -m mainprog.cbl sub1.cbl sub2.cbl
When the -m switch is used, an operating-system-specific dynamically-loadable module is generated for each individual compilation unit, using the filename of each compilation unit as its module filename and either an extension of .so (UNIX, Windows/Cygwin), .dylib (OSX) or .dll (Windows, Windows/MinGW).
You may compile GnuCOBOL subprograms into assembler source code which can then be assembled and linked with a main program when that main program is compiled. To create such an assembler source file, compile the subprogram(s) as follows:
cobc -S sprog1.cbl
The above generates an assembler source file named sprog1.s. If you have multiple subprograms to compile this way, just string their file names out on the command. Each will be translated to its own assembler source file.
Later, when you wish to compile a calling program and combine any needed assembly language subroutines in (as static subroutines — see Dynamic vs Static Subprograms), use a command such as this:
cobc -x mainprog.cbl sprog1.s
10.1.1.1. cobc option -Xref an example
The following shows the output from using -Xref.
Using the internal -Xref as extra options -X -t prog.list: GnuCOBOL 3.1-dev.0 prog.cbl Fri Dec 6 14:17:52 2019 Page 0001 LINE PG/LN A...B............................................................ 000001 000001 IDENTIFICATION DIVISION. 000002 000002 PROGRAM-ID. prog. 000003 000003 ENVIRONMENT DIVISION. 000004 000004 CONFIGURATION SECTION. 000005 000005 DATA DIVISION. 000006 000006 WORKING-STORAGE SECTION. 000007 000007 COPY 'values.cpy'. 000001C 000001 78 I VALUE 20. 000002C 000002 78 J VALUE 5000. 000003C 000003 78 M VALUE 5. 000008 000008 01 SETUP-REC. 000009 000009 05 FL1 PIC X(04). 000010 000010 05 FL2 PIC ZZZZZ. 000011 000011 05 FL3 PIC 9(04). 000012 000012 05 FL4 PIC 9(08) COMP. 000013 000013 05 FL5 PIC 9(04) COMP-4. 000014 000014 05 FL6 PIC Z,ZZZ.99. 000015 000015 05 FL7 PIC S9(05) SIGN LEADING SEPARATE. 000016 000016 05 FL8 PIC X(04). 000017 000017 05 FL9 REDEFINES FL8 PIC 9(04). 000018 000018 05 FLA. 000019 000019 10 FLB OCCURS I TIMES. 000020 000020 15 FLC PIC X(02). 000021 000021 10 FLD PIC X(20). 000022 000022 05 FLD1 PIC X(100). 000023 000025 05 FLD3 PIC X(3). 000024 000026 05 FLD4 PIC X(4). 000025 000023 05 FLD2 OCCURS M TO J TIMES DEPENDING ON FL5. 000026 000024 10 FILLER PIC X(01). 000027 000027 PROCEDURE DIVISION. 000028 000028 STOP RUN. GnuCOBOL 3.1-dev.0 prog.cbl Fri Dec 6 14:17:52 2019 Page 0002 NAME DEFINED REFERENCES SETUP-REC 8 referenced by child FL1 9 not referenced FL2 10 not referenced FL3 11 not referenced FL4 12 not referenced FL5 13 25 FL6 14 not referenced FL7 15 not referenced FL8 16 not referenced FL9 17 not referenced FLA 18 not referenced FLB 19 not referenced FLC 20 not referenced FLD 21 not referenced FLD1 22 not referenced FLD3 23 not referenced FLD4 24 not referenced FLD2 25 not referenced GnuCOBOL 3.1-dev.0 prog.cbl Fri Dec 6 14:17:52 2019 Page 0003 LABEL DEFINED REFERENCES E prog 27 0 warnings in compilation group 0 errors in compilation group
10.1.1.2. Cross Reference listing using cobxref
This program is found in the contrib area or by itself in Sourceforge under its own name (cobxref
).
The following shows the output from using cobxref
with the same program example.
Using cobxref with command cobxref prog.cbl : ACS Cobol Xref v2.02.02 Dictionary File for PROG 06/12/2019 14:19:09:39 Page 1 1 000001 IDENTIFICATION DIVISION. 2 000002 PROGRAM-ID. prog. 3 000003 ENVIRONMENT DIVISION. 4 000004 CONFIGURATION SECTION. 5 000005 DATA DIVISION. 6 000006 WORKING-STORAGE SECTION. 7 000007*COPY 'values.cpy'. 8 000001 78 I VALUE 20. 9 000002 78 J VALUE 5000. 10 000003 78 M VALUE 5. 11 000008 01 SETUP-REC. 12 000009 05 FL1 PIC X(04). 13 000010 05 FL2 PIC ZZZZZ. 14 000011 05 FL3 PIC 9(04). 15 000012 05 FL4 PIC 9(08) COMP. 16 000013 05 FL5 PIC 9(04) COMP-4. 17 000014 05 FL6 PIC Z,ZZZ.99. 18 000015 05 FL7 PIC S9(05) SIGN LEADING SEPARATE. 19 000016 05 FL8 PIC X(04). 20 000017 05 FL9 REDEFINES FL8 PIC 9(04). 21 000018 05 FLA. 22 000019 10 FLB OCCURS I TIMES. 23 000020 15 FLC PIC X(02). 24 000021 10 FLD PIC X(20). 25 000022 05 FLD1 PIC X(100). 26 000025 05 FLD3 PIC X(3). 27 000026 05 FLD4 PIC X(4). 28 000023 05 FLD2 OCCURS M TO J TIMES DEPENDING ON FL5. 29 000024 10 FILLER PIC X(01). 30 000027 PROCEDURE DIVISION. 31 000028 STOP RUN. 32 *>>>Info: Total Copy Depth Used = 02 ACS Cobol Xref v2.02.02 Dictionary File for PROG 06/12/2019 14:19:09:39 Page 2 Symbols of Module: PROG (PROG) ------------------------------ Data Section (WORKING-STORAGE) Defn Locations -------------------------------+--------------------------------------------------------------- FL1 000012W FL2 000013W FL3 000014W FL4 000015W FL5 000016W 000028 FL6 000017W FL7 000018W FL8 000019W 000020 FL9 000020W FLA 000021W FLB 000022W FLC 000023W FLD 000024W FLD1 000025W FLD2 000028W FLD3 000026W FLD4 000027W I 000008W 000022 J 000009W 000028 M 000010W 000028 SETUP-REC 000011W ACS Cobol Xref v2.02.02 Dictionary File for PROG 06/12/2019 14:19:09:39 Page 3 Symbols of Module: PROG (PROG) ------------------------------ Procedure Defn Locations -------------------------------+--------------------------------------------------------------- None ACS Cobol Xref v2.02.02 Dictionary File for PROG 06/12/2019 14:19:09:39 Page 4 Symbols of Module: PROG (PROG) ------------------------------ Unreferenced Working Storage Symbols FL1 000012W FL2 000013W FL3 000014W FL4 000015W FL6 000017W FL7 000018W FL9 000020W FLA 000021W FLB 000022W FLC 000023W FLD 000024W FLD1 000025W FLD2 000028W FLD3 000026W FLD4 000027W SETUP-REC 000011W ACS Cobol Xref v2.02.02 Dictionary File for PROG 06/12/2019 14:19:09:39 Page 5 Symbols of Module: PROG (PROG) ------------------------------ Unreferenced Procedures None
10.1.2. Compilation Time Environment Variables
The following are the various environment variables that can play a role in the compilation of GnuCOBOL programs.
COB_CC
-
Set to the name