>From 64bcb34e12371f61a8958645e1668e0ac2704391doc.patch 4 Oct 2024 12:01:22
>-0400
From: "James K. Lowden" <jklow...@symas.com>
Date: Thu 12 Dec 2024 06:28:05 PM EST
Subject: [PATCH] Add 'cobol' to 4 files
gcc/cobol/ChangeLog
* gcobc: New file.
* gcobol.1: New file.
* gcobol.3: New file.
* help.gen: New file.
---
gcc/cobol/gcobc |
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
gcc/cobol/gcobol.1 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
gcc/cobol/gcobol.3 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
gcc/cobol/help.gen | +++++++++++++++
4 files changed, 2356 insertions(+), 4 deletions(-)
diff --git a/gcc/cobol/gcobc b/gcc/cobol/gcobc
new file mode 100755
index 00000000000..9afd8fd93fe
--- /dev/null
+++ b/gcc/cobol/gcobc
@@ -0,0 +1,443 @@
+#! /bin/sh -e
+
+#
+# COPYRIGHT
+# The gcobc program is in public domain.
+# If it breaks then you get to keep both pieces.
+#
+# This file emulates the GnuCOBOL cobc compiler to a limited degree.
+# For options that can be "mapped" (see migration-guide.1), it accepts
+# cobc options, changing them to the gcobol equivalents. Options not
+# recognized by the script are passed verbatim to gcobol, which will
+# reject them unless of course they are gcobol options.
+#
+# User-defined variables, and their defaults:
+#
+# Variable Default Effect
+# echo none If defined, echo the gcobol command
+# gcobcx none Produce verbose messages
+# gcobol ./gcobol Name of the gcobol binary
+# GCOBCUDF PREFIX/share/cobol/udf/ Location of UDFs to be prepended to
input
+#
+# By default, this script includes all files in $GCOBCUDF. To defeat
+# that behavior, use GCOBCUDF=none.
+#
+# A list of supported options is produced with "gcobc -HELP".
+#
+## Maintainer note. In modifying this file, the following may make
+## your life easier:
+##
+## - To force the script to exit, either set exit_status to 1, or call
+## the error function.
+## - As handled options are added, add them to the HELP here-doc.
+## - The compiler can produce only one kind of output. In this
+## script, that's known by $mode. Options that affect the type of
+## output set the mode variable. Everything else is appended to the
+## opts variable.
+##
+
+if [ "$COBCPY" ]
+then
+ copydir="-I$COBCPY"
+fi
+
+if [ "$COB_COPY_DIR" ]
+then
+ copydir="-I$COB_COPY_DIR"
+fi
+
+udf_default="${0%/*}/../share/cobol/udf"
+udfdir="${GCOBCUDF:-$udf_default}"
+
+if [ -d "$udfdir" ]
+then
+ for F in "$udfdir"/*
+ do
+ if [ -f $F ]
+ then
+ includes="$includes -include $F "
+ fi
+ done
+else
+ if [ "$GCOBCUDF" -a "$GCOBCUDF" != "none" ]
+ then
+ echo warning: no such directory: "'$GCOBCUDF'"
+ fi
+fi
+
+exit_status=0
+skip_arg=
+opts="$copydir ${dialect:--dialect mf} $includes"
+mode=-shared
+
+incomparable="has no comparable gcobol option"
+
+if [ "${gcobcx:-0}" -gt 1 ]
+then
+ set -x
+fi
+
+error() {
+ echo "error: $1" >&2
+ exit_status=1
+}
+warn() {
+ echo "warning: $1 ignored" >&2
+}
+ignore_arg() {
+ warn "$1"
+ skip_arg="$1"
+}
+no_warn() { :; } # silence is golden
+
+help() {
+ cat<<EOF
+$0 recognizes the following GnuCOBOL cobc output mode options:
+ -b, -c, -m, -S, -x
+$0 recognizes the following GnuCOBOL cobc compilation options:
+ -C
+ -d, --debug
+ -E
+ -ext
+ -fec=exception-name, -fno-ec=exception-name
+ -fixed
+ -F, -free
+ -fimplicit-init
+ -h, --help
+ -save-temps=
+ -save-temps
+ -std=mvs
+ -std=mf
+Options that are the same in gcobol and cobc are passed through verbatim.
+Options that have no analog in gcobol produce a warning message.
+To produce this message, use -HELP.
+To see the constructed cobc command-line, use -echo.
+To override the default cobc, set the "cobc" environment variable.
+By default, gcobc invokes the gcobol the same directory the gcobc resides.
+To override, set the gcobol environment variable.
+EOF
+}
+
+#
+# Simply iterate over the command-line tokens. We can't use getopts
+# here because it's not designed for single-dash words (e.g. -shared).
+#
+
+for opt in "$@"
+do
+ if [ "$skip_arg" ]
+ then
+ skip_arg=
+ continue
+ fi
+
+ if [ "$pending_arg" ]
+ then
+ opts="$opts $pending_arg $opt"
+ pending_arg=
+ continue
+ fi
+
+ case $opt in
+ -A | -Q) warn "$opt"
+ ;;
+ -b) mode="-shared"
+ ;;
+ -c) mode="-c"
+ ;;
+ --conf=*) warn "$opt"
+ ;;
+ -C) error "$opt $incomparable"
+ ;;
+ -d | --debug) opts="$opts -fcobol-exceptions=EC-ALL"
+ warn "$opt implies -fstack-check:"
+ ;;
+ # -D
+ -E) opts="$opts $opt -fsyntax-only"
+ ;;
+ -echo) echo="echo"
+ ;;
+
+ -fec=* | -fno-ec=*)
+ opt="$(echo "$opt" | sed -E
's/-f(no-)?ec=/-f\1cobol-exceptions=EC-/g')"
+ opts="$opts $opt"
+ ;;
+ -ext)
+ pending_arg=$opt
+ ;;
+ -ext=*) opts="$opts $(echo $opt | sed 's/-ext=/-copyext ./')"
+ ;;
+
+ # A.3 Compiler options
+ -fsign=*) warn "$opt" ;;
+ -ffold-copy=*) warn "$opt" ;;
+ -ffold-call=*) warn "$opt" ;;
+ -fmax-errors=*) warn "$opt" ;;
+ -fintrinsics=*) warn "$opt" ;;
+ -fdump=*) warn "$opt" ;;
+ -fcallfh=*) warn "$opt" ;;
+ -fsqlschema=*) warn "$opt" ;;
+ -fsql) warn "$opt" ;;
+ -fno-recursive-check) no_warn "$opt" ;;
+ -fstack-extended) warn "$opt" ;;
+ -fno-remove-unreachable) no_warn "$opt" ;;
+ -finline-intrinsic) warn "$opt" ;;
+ -ftrace) warn "$opt" ;;
+ -ftraceall) warn "$opt" ;;
+ -fsymtab) warn "$opt" ;;
+ # -fsyntax-only is identical
+ -fdebugging-line) warn "$opt" ;;
+ -fsource-location) warn "$opt" ;;
+ -fstack-check) warn "$opt" ;;
+ -fsection-exit-check) warn "$opt" ;;
+ -fimplicit-goback-check) warn "$opt" ;;
+ -fwrite-after) warn "$opt" ;;
+ -fmfcomment) warn "$opt" ;;
+ -facucomment) warn "$opt" ;;
+ -fno-trunc) no_warn "$opt" ;;
+ -fsingle-quote) warn "$opt" ;;
+ -foptional-file) warn "$opt" ;;
+ -fstatic-call | -fno-static-call)
+ opts="$opts $opt"
+ static_used="x"
+ ;;
+ -fno-gen-c-decl-static-call) no_warn "$opt" ;;
+ -fmf-files) warn "$opt" ;;
+ -ffile-format=*) warn "$opt" ;;
+ -fno-theaders) no_warn "$opt" ;;
+ -fno-tsource) no_warn "$opt" ;;
+ -fno-tmessages) no_warn "$opt" ;;
+ -ftsymbols) warn "$opt" ;;
+ -fdatamap) warn "$opt" ;;
+ -fno-diagnostics-show-option) no_warn "$opt" ;;
+ -fibmcomp) warn "$opt" ;;
+ -fno-ibmcomp) no_warn "$opt" ;;
+
+ # A.4 Compiler dialect configuration options
+ -fname=*) warn "$opt" ;;
+ -freserved-words=*) warn "$opt" ;;
+ -ftab-width=*) warn "$opt" ;;
+ -ftext-column=*) warn "$opt" ;;
+ -fpic-length=*) warn "$opt" ;;
+ -fword-length=*) warn "$opt" ;;
+ -fliteral-length=*) warn "$opt" ;;
+ -fnumeric-literal-length=*) warn "$opt" ;;
+ -fdefaultbyte=*) warn "$opt" ;;
+ -falign-record=*) warn "$opt" ;;
+ -fkeycompress=*) warn "$opt" ;;
+ -falign-opt) warn "$opt" ;;
+ -fbinary-size=*) warn "$opt" ;;
+ -fbinary-byteorder=*) warn "$opt" ;;
+ -fassign-clause=*) warn "$opt" ;;
+ -fscreen-section-rules=*) warn "$opt" ;;
+ -fdpc-in-data=*) warn "$opt" ;;
+ -ffilename-mapping) warn "$opt" ;;
+ -fpretty-display) warn "$opt" ;;
+ -fbinary-truncate | -fno-binary-truncate) warn "$opt" ;;
+ -fcomplex-odo) warn "$opt" ;;
+ -fodoslide) warn "$opt" ;;
+ -findirect-redefines) warn "$opt" ;;
+ -flarger-redefines-ok) warn "$opt" ;;
+ -frelax-syntax-checks) warn "$opt" ;;
+ -fref-mod-zero-length) warn "$opt" ;;
+ -frelax-level-hierarchy) warn "$opt" ;;
+ -flocal-implies-recursive) warn "$opt" ;;
+ -fsticky-linkage) warn "$opt" ;;
+ -fmove-ibm) warn "$opt" ;;
+ -fperform-osvs) warn "$opt" ;;
+ -farithmetic-osvs) warn "$opt" ;;
+ -fconstant-folding) warn "$opt" ;;
+ -fhostsign) warn "$opt" ;;
+ -fprogram-name-redefinition) warn "$opt" ;;
+ -faccept-update) warn "$opt" ;;
+ -faccept-auto) warn "$opt" ;;
+ -fconsole-is-crt) warn "$opt" ;;
+ -fno-echo-means-secure) no_warn "$opt" ;;
+ -fline-col-zero-default) warn "$opt" ;;
+ -freport-column-plus) warn "$opt" ;;
+ -fdisplay-special-fig-consts) warn "$opt" ;;
+ -fbinary-comp-1) warn "$opt" ;;
+ -fnumeric-pointer) warn "$opt" ;;
+ -fmove-non-numeric-lit-to-numeric-is-zero) warn "$opt" ;;
+ -fimplicit-assign-dynamic-var) warn "$opt" ;;
+ -fcomment-paragraphs=*) warn "$opt" ;;
+ -fmemory-size-clause=*) warn "$opt" ;;
+ -fmultiple-file-tape-clause=*) warn "$opt" ;;
+ -flabel-records-clause=*) warn "$opt" ;;
+ -fvalue-of-clause=*) warn "$opt" ;;
+ -fdata-records-clause=*) warn "$opt" ;;
+ -ftop-level-occurs-clause=*) warn "$opt" ;;
+ -fsame-as-clause=*) warn "$opt" ;;
+ -ftype-to-clause=*) warn "$opt" ;;
+ -fusage-type=*) warn "$opt" ;;
+ -fsynchronized-clause=*) warn "$opt" ;;
+ -fsync-left-right=*) warn "$opt" ;;
+ -fspecial-names-clause=*) warn "$opt" ;;
+ -fgoto-statement-without-name=*) warn "$opt" ;;
+ -fstop-literal-statement=*) warn "$opt" ;;
+ -fstop-identifier-statement=*) warn "$opt" ;;
+ -fdebugging-mode=*) warn "$opt" ;;
+ -fuse-for-debugging=*) warn "$opt" ;;
+ -fpadding-character-clause=*) warn "$opt" ;;
+ -fnext-sentence-phrase=*) warn "$opt" ;;
+ -flisting-statements=*) warn "$opt" ;;
+ -ftitle-statement=*) warn "$opt" ;;
+ -fentry-statement=*) warn "$opt" ;;
+ -fmove-noninteger-to-alphanumeric=*) warn "$opt" ;;
+ -foccurs-max-length-without-subscript) warn "$opt" ;;
+ -flength-in-data-division) warn "$opt" ;;
+ -fmove-figurative-constant-to-numeric=*) warn "$opt" ;;
+ -fmove-figurative-space-to-numeric=*) warn "$opt" ;;
+ -fmove-figurative-quote-to-numeric=*) warn "$opt" ;;
+ -fodo-without-to=*) warn "$opt" ;;
+ -fodo-last-varlen=*) warn "$opt" ;;
+ -fsection-segments=*) warn "$opt" ;;
+ -falter-statement=*) warn "$opt" ;;
+ -fcall-overflow=*) warn "$opt" ;;
+ -fnumeric-boolean=*) warn "$opt" ;;
+ -fhexadecimal-boolean=*) warn "$opt" ;;
+ -fnational-literals=*) warn "$opt" ;;
+ -fhexadecimal-national-literals=*) warn "$opt" ;;
+ -fnational-character-literals=*) warn "$opt" ;;
+ -fhp-octal-literals=*) warn "$opt" ;;
+ -facu-literals=*) warn "$opt" ;;
+ -fword-continuation=*) warn "$opt" ;;
+ -fnot-exception-before-exception=*) warn "$opt" ;;
+ -faccept-display-extensions=*) warn "$opt" ;;
+ -frenames-uncommon-levels=*) warn "$opt" ;;
+ -fsymbolic-constant=*) warn "$opt" ;;
+ -fconstant-78=*) warn "$opt" ;;
+ -fconstant-01=*) warn "$opt" ;;
+ -fperform-varying-without-by=*) warn "$opt" ;;
+ -freference-out-of-declaratives=*) warn "$opt" ;;
+ -freference-bounds-check=*) warn "$opt" ;;
+ -fprogram-prototypes=*) warn "$opt" ;;
+ -fcall-convention-mnemonic=*) warn "$opt" ;;
+ -fcall-convention-linkage=*) warn "$opt" ;;
+ -fnumeric-value-for-edited-item=*) warn "$opt" ;;
+ -fincorrect-conf-sec-order=*) warn "$opt" ;;
+ -fdefine-constant-directive=*) warn "$opt" ;;
+ -ffree-redefines-position=*) warn "$opt" ;;
+ -frecords-mismatch-record-clause=*) warn "$opt" ;;
+ -frecord-delimiter=*) warn "$opt" ;;
+ -fsequential-delimiters=*) warn "$opt" ;;
+ -frecord-delim-with-fixed-recs=*) warn "$opt" ;;
+ -frecord-sequential-advancing=*) warn "$opt" ;;
+ -fmissing-statement=*) warn "$opt" ;;
+ -fzero-length-literals=*) warn "$opt" ;;
+ -fxml-generate-extra-phrases=*) warn "$opt" ;;
+ -fcontinue-after=*) warn "$opt" ;;
+ -fgoto-entry=*) warn "$opt" ;;
+ -fdepending-on-not-fixed=*) warn "$opt" ;;
+ -fbinary-sync-clause=*) warn "$opt" ;;
+ -fnonnumeric-with-numeric-group-usage=*) warn "$opt" ;;
+ -fassign-variable=*) warn "$opt" ;;
+ -fassign-using-variable=*) warn "$opt" ;;
+ -fassign-ext-dyn=*) warn "$opt" ;;
+ -fassign-disk-from=*) warn "$opt" ;;
+ -fvsam-status=*) warn "$opt" ;;
+ -fself-call-recursive=*) warn "$opt" ;;
+ -fnot-reserved=*) warn "$opt" ;;
+ -freserved=*) warn "$opt" ;;
+ -fnot-register=*) warn "$opt" ;;
+ -fregister=*) warn "$opt" ;;
+
+ -fixed) opts="$opts -ffixed-form"
+ ;;
+ -F | -free) opts="$opts -ffree-form"
+ ;;
+ # -g
+ -h | --help) opts="$opts --help"
+ ;;
+
+ -HELP) help && exit
+ ;;
+ -i | --info) warn "$opt"
+ ;;
+
+ # -I
+ -fimplicit-init) warn "$opt"
+ ;;
+ -j | -job) warn "$opt"
+ ;;
+ -K) ignore_arg "$opt"
+ ;;
+ -K*) warn "$opt"
+ ;;
+ # -l
+ # -L
+ --list*) warn "$opt"
+ ;;
+ -m) mode="-shared"
+ ;;
+ # -main
+ # -nomain
+ # -o
+ # -O0, -Ox
+ -O | -O2 | -Os) warn "$opt"
+ ;;
+ -S) mode="$opt"
+ ;;
+ -save-temps=*) opt="$(echo $opt | sed -E 's/^.+=//')"
+ export GCOBOL_TEMPDIR="$opt"
+ ;;
+ -save-temps) export GCOBOL_TEMPDIR="${PWD:-$(pwd)}"
+ ;;
+ # -shared is identical
+
+ -std=mvs) opts="$opts -dialect ibm"
+ ;;
+ -std=mf) opts="$opts -dialect mf"
+ ;;
+ -t | -T | -tlines=* | -P | -P=* | -X | --Xref)
+ warn "$opt (no listing)"
+ ;;
+ -q | --brief) warn "$opt"
+ ;;
+ -v | --verbose) opts="$opts -V"
+ ;;
+ -V | --version | --dumpversion) opts="$opts --version"
+ ;;
+
+ -w) opts="$opts $opt"
+ ;;
+ -Wno-*) no_warn "$opt"
+ ;;
+ -W*) ignore_arg "$opt"
+ ;;
+
+ -x) mode=
+ ;;
+
+ *) opts="$opts $opt" # pass through
+ ;;
+ esac
+done
+
+# cobc default:
+if [ "$static_used" = "" ]
+then
+ opts="$opts -fno-static-call";
+fi
+
+if [ "$exit_status" -gt 0 ]
+then
+ exit $exit_status
+fi
+
+# To override the default gcobol, set the "gcobol" environment variable.
+gcobol="${gcobol:-${0%/*}/gcobol}"
+
+if [ "$echo" ]
+then
+ echo $gcobol $mode $opts
+ exit
+fi
+
+if [ "$gcobcx" ]
+then
+ set -x
+fi
+
+exec $gcobol $mode $opts
+
diff --git a/gcc/cobol/gcobol.1 b/gcc/cobol/gcobol.1
new file mode 100644
index 00000000000..71f334ece6f
--- /dev/null
+++ b/gcc/cobol/gcobol.1
@@ -0,0 +1,1566 @@
+.ds lang COBOL
+.ds gcobol GCC\ \*[lang]\ Front-end
+.ds isostd ISO/IEC 1989:2023
+.Dd \& December 2022
+.Dt GCOBOL 1\& "GCC \*[lang] Compiler"
+.Os Linux
+.Sh NAME
+.Nm gcobol
+.Nd \*[gcobol]
+.Sh SYNOPSIS
+.Nm
+.Op Fl D Ns Ar name Ns Oo Li = Ns Ar value Oc
+.Op Fl E
+.Op Fl fdefaultbyte Ns Li = Ns Ar value
+.Op Fl fsyntax-only
+.Op Fl I Ns Ar copybook-path
+.Op Fl fmax-errors Ns Li = Ns Ar nerror
+.Oo
+.Fl nomain |
+.Fl main Ar filename |
+.Fl main Ns Li = Ns Ar filename
+.Fl main Ns Li = Ns Ar filename:program-id
+.Oc
+.Op Fl fcobol-exceptions Ar exception Ns Op Ns , Ns Ar exception Ns ...
+.Op Fl copyext Ar ext
+.Op Fl ffixed-form | Fl ffree-form
+.Op Fl findicator-column
+.Op Fl finternal-ebcdic
+.Op Fl dialect Ar dialect-name
+.Op Fl include Ar filename
+.Op Fl preprocess Ar preprocess-filter
+.Op Fl fflex-debug
+.Op Fl fyacc-debug
+.Ar filename Op ...
+.
+.Sh DESCRIPTION
+.Nm
+compiles \*[lang] source code to object code, and optionally produces an
+executable binary or shared object. As a GCC component, it accepts
+all options that affect code-generation and linking. Options specific
+to \*[lang] are listed below.
+.Bl -tag -width \0\0debug
+.It Fl main Ar filename
+.Nm
+will generate a
+.Fn main
+function as an entry point calling the first PROGRAM-ID in
+.Ar filename .
+.Pp
+.Fl main
+is the default. When none of
+.Fl nomain ,
+.Fl c ,
+or
+.Fl shared ,
+is present, an implicit
+.Fl main
+is inserted into the command line ahead of the first source file name.
+.It Fl main Ns Li = Ns Ar filename
+The .o object module for
+.Ar filename
+will include a
+.Fn main
+entry point calling the first PROGRAM-ID in
+.Ar filename
+.It Fl main Ns Li = Ns Ar filename:program-id
+The .o object module for
+.Ar filename
+will include a
+.Fn main
+entry point that calls the
+.Ar program-id
+entry point
+.It Fl nomain
+No
+.Fn main
+entry point will be generated by this
+compilation. The
+.Fl nomain
+option is incompatible with
+.Fl main ,
+and is implied by
+.Fl shared .
+It is also implied by
+.Fl c
+when there is no
+.Fl main
+present.
+.Pp
+See below for examples showing the use of
+.Fl main
+and
+.Fl nomain.
+.It Fl D Ar name Ns Op Li = Ns Ar expr
+Define a CDF name (for use with
+.Sy >>IF )
+to have the value of
+.Ar expr .
+.It Fl E
+Write the CDF-processed \*[lang] input to standard output in free-form
+reference format. Certain non-Cobol markers are included in the
+output to indicate where copybook files were included. For
+line-number consistency with the input, blank lines are retained.
+.Pp
+Unlike the C compiler, This option does not prevent compilation.
+To prevent compilation, use the option
+.D1 Fl Sy fsyntax-only
+also.
+.It Fl fdefaultbyte Ns Li = Ns Ar value
+Use
+.Ar value ,
+a number between 0 and 255, as the default value for all
+WORKING-STORAGE data items that have no VALUE clause. By default,
+alphanumeric data items are initialized with blanks, and numeric data
+items are initialized to zero. This option overrides the default with
+.Ar value .
+.It Fl fsyntax-only
+Invoke only the parser. Check the code for syntax errors, but don't do
+anything beyond that.
+.It Fl copyext Ar ext
+For the CDF directive
+.D1 COPY Ar name
+if
+.Ar name
+is unquoted, several varieties of
+.Ar name
+are tried, as described below under
+.Xr Copybooks Ns .
+The
+.Fl copyext
+option extends the names searched to include
+.Ar ext .
+If
+.Ar ext
+is all uppercase or all lowercase, both forms are tried, with preference given
to the one supplied. If
+.Ar ext
+is mixed-case, only that version is tried.
+For example, with
+.D1 Fl copyext Ar .abc
+given the CDF directive
+.D1 COPY name
+.Nm
+will add to possible names searched
+.Ql name.abc
+and
+.Ql name.ABC
+in that order.
+.It Fl ffixed-form
+Use strict
+.Em "Reference Format"
+in reading the \*[lang] input:
+72-character lines, with a 6-character sequence area, and an indicator
+column. Data past column 72 are ignored.
+.It Fl ffree-form
+Force the \*[lang] input to be interpreted as
+.Em "free format" .
+Line breaks are insignificant, except that
+.Ql *
+at the start of a line acts as a comment marker.
+Equivalent to
+.Fl indicator-column Ar 0 Ns Li .
+.
+.It Fl findicator-column
+describes the location of the Indicator Area in a \*[lang] file
+in
+.Em "Reference Format" ,
+where the first 6 columns \(em known as the
+.Dq "Sequence Number Area"
+\(em are ignored, and the 7th column \(em the Indicator
+Area \(em may hold a character of significance to the compiler.
+.Pp
+Although
+.Em "reference format" ,
+strictly speaking, ignores data after column 72,
+with this option
+.Nm
+accepts long \*[lang] lines, sometimes known as
+.Em "extended source format" .
+Text past column 72 is treated as ordinary \*[lang] text. (Line
+continuation remains in effect, however,
+provided no text appears
+.Em past
+column 72.)
+.Pp
+There is no maximum line length. Regardless of source code format,
+the entire program could appear on one line.
+.Pp
+By default,
+.Nm
+auto-detects the source code format by examining the
+.Em "sequence number area"
+of the first line of the first file: if those characters are all
+digits or blanks, the file is assumed to be in
+.Em "reference format" ,
+with the indicator area in column 7.
+.Pp
+.
+.It Fl fcobol-exceptions Ar exception Op Ns , Ns Ar exception Ns ...
+By default, no exception condition is enabled (including fatal ones),
+and by the ISO standard exception conditions are enabled only via the
+CDF
+.Sy "TURN"
+directive. This option enables one or more exception conditions by
+default, as though
+.Sy TURN
+had appeared at the top of the first source code file.
+This option may also appear more than once on the command line.
+.Pp
+The value of
+.Ar exception
+is a Level 1, 2, or 3 exception condition name, as described by
+\*[isostd].
+.Ql EC-ALL
+means enable all exceptions.
+.Pp
+The
+.Fl fno-cobol-exceptions
+form turns off
+.Ar exception ,
+just as though
+.D1 >>TURN Ar exception CHECKING OFF
+had appeared.
+.Pp
+Not all exception conditions are implemented. Any that are not
+produce a warning message.
+.
+.It Fl fmax-errors Ar nerror
+.Ar nerror
+represents the number of error messages produced. Without this option,
+.Nm
+attempts to recover from a syntax error by resuming compilation at the
+next statement, continuing until end-of-file. With it,
+.Nm
+counts the messages as they're produced, and stops when
+.Ar nerror
+is reached.
+.It Fl fstatic-call Ns , Fl fno-static-call
+With
+.Fl fno-static-call ,
+.Nm
+never uses static linking for
+.D1 Sy CALL Ar program
+By default, or with
+.Fl fstatic-call ,
+if
+.Ar program
+is an alphanumeric literal,
+.Nm
+uses static linkage, meaning the compiler produces an external symbol
+.Ar program
+for the linker to resolve.
+(In the future, that will work with
+.Sy CONSTANT
+data items, too.) With static linkage, if
+.Ar program
+is not supplied by the source code module or another object file or library
+at build time, the linker will produce an
+.Dq "unresolved symbol"
+error. With
+.Fl fno-static-call ,
+.Nm
+always uses dynamic linking.
+.Pp
+This option affects the
+.Sy CALL
+statement for literals only. If
+.Ar program
+is a non-constant data item, it is always resolved using dynamic
+linking, with
+.Xr dlsym 3 Ns Li ,
+because its value is determined at run time.
+.It Fl dialect Ar dialect-name
+By default,
+.Nm
+accepts \*[lang] syntax as defined by \*[isostd], with some
+extensions for backward compatibility with COBOL-85. To make the
+compiler more generally useful, some additional syntax is supported by
+this option.
+.Pp
+The value of
+.Ar dialect-name
+may be
+.Bl -tag -compact
+.It ibm
+to indicate IBM COBOL 6.3 syntax, specifically
+.D1 STOP <number> .
+.It gnu
+to indicate GnuCOBOL syntax
+.It mf
+to indicate MicroFocus syntax, specifically
+.Sy LEVEL 78
+constants.
+.El
+.Pp
+Only a few such non-standard constructs are accepted, and
+.Nm
+makes no claim to emulate other compilers. But to the extent that a
+feature is popular but nonstandard, this option provides a way to
+support it, or add it.
+.
+.It Fl include Ar filename
+Process
+.Ar filename
+as if
+.D1 COPY Dq Ar filename
+appeared as the first line of
+the primary source file. If
+.Ar filename
+is not an absolute path, the directory searched is the current working
+directory, not the directory containing the main source file. The
+name is used verbatim. No permutations are applied, and no
+directories searched.
+.Pp
+If multiple
+.Fl include
+options are given, the files are included in
+the order they appear on the command line.
+.
+.It Fl preprocess Ar preprocess-filter
+After all CDF text-manipulation has been applied, and before the
+prepared \*[lang] is sent to the
+.Sy cobol1
+compiler, the input may be
+further altered by one or more filters. In the tradition of
+.Xr sed 1 ,
+each
+.Ar preprocess-filter
+reads from standard input and writes to standard output.
+.Pp
+To supply options to
+.Ar preprocess-filter ,
+use a comma-separated string, similar to how linker options are supplied to
+.Fl Sy Wl .
+(Do not put any spaces after the commas, because the shell will treat it as an
option separator.)
+.Nm
+replaces each comma with a space when
+.Ar preprocess-filter
+is invoked. For example,
+.D1 Fl preprocess Li tee,output.cbl
+invokes
+.Xr tee 1
+with the output filename argument
+.Pa output.cbl ,
+causing a copy of the input to be written to the file.
+.Pp
+.Nm
+searches the current working directory and the PATH environment
+variable directories for an executable file whose name matches
+.Ar preprocess-filter .
+The first one found is used. If none is found, an error is reported
+and the compiler is not invoked.
+.Pp
+The
+.Fl preprocess
+option may appear more than once on the command line. Each
+.Ar preprocess-filter
+is applied in turn, in order of appearance.
+.Pp
+The
+.Ar preprocess-filter
+should return a zero exit status, indicating success. If it returns a
+nonzero exit status, an error is reported and the compiler is not
+invoked.
+.
+.It Fl fflex-debug Ns Li , Fl fyacc-debug
+produce messages useful for compiler development. The
+.Fl fflex-debug
+option prints the tokenized input stream. The
+.Fl fyacc-debug
+option shows the shift and reduce actions taken by the parser.
+.El
+.
+.Sh COMPILATION SCENARIOS
+.Ss gcobol Pa xyz.cob
+.Ss gcobol -main Pa xyz.cob
+.Ss gcobol -main= Ns Pa xyz.cob Pa xyz.cob
+These are equivalent. The
+.Pa xyz.cob
+code is compiled and a
+.Fn main
+function is
+inserted that calls the first PROGRAM-ID in the
+.Pa xyz.cob
+source file.
+
+.Ss gcobol -nomain Pa xyz.cob Pa elsewhere.o
+The
+.Fl nomain
+option prevents a
+.Fn main
+function from being generated by the gcobol compiler.
+A
+.Fn main
+entry point must be present in the
+.Pa elsewhere.o
+module; without it the
+linker will report a
+.Dq "missing main"
+error.
+
+.Ss gcobol Pa aaa.cob Pa bbb.cob Pa ccc.cob
+.Ss gcobol -main Pa aaa.cob Pa bbb.cob Pa ccc.cob
+The two commands are equivalent. The three source code modules are compiled and
+linked together along with a generated
+.Fn main
+function that calls the first
+PROGRAM-ID in the
+.Pa aaa.cob
+module.
+
+.Ss gcobol Pa aaa.cob Pa bbb.cob Fl main Pa ccc.cob
+.Ss gcobol -main Ns = Ns Pa ccc.cob Pa aaa.cob Pa bbb.cob Pa ccc.cob
+These two commands have the same result: An
+.Pa a.out
+executable is created that
+starts executing at the first PROGRAM-ID in
+.Pa ccc.cob .
+
+.Ss gcobol -main Ns = Ns Pa bbb.cob:b-entry Pa aaa.cob Pa bbb.cob Pa ccc.cob
+An
+.Pa a.out
+executable is created that starts executing at the PROGRAM-ID
+.Ar "b-entry" .
+
+.Ss gcobol -c Pa aaa.cob
+.Ss gcobol -c -main Pa bbb.cob
+.Ss gcobol -c Pa ccc.cob
+.Ss gcobol Pa aaa.o Pa bbb.o Pa ccc.o
+The first three commands each create a .o file. The
+.Pa bbb.o
+file will contain a
+.Fn main
+entry point that calls the first PROGRAM-ID in
+.Pa bbb .
+The fourth links the
+three .o files into an
+.Pa a.out.
+
+.Sh EBCDIC
+The
+.Fl finternal-ebcdic
+option is useful when working with mainframe \*[lang] programs intended
+for EBCDIC-encoded files. With this option, while the \*[lang] text
+remains in ASCII, the character literals and field initial values
+produce EBCDIC strings in the compiled binary, and any character data
+read from a file are interpreted as EBCDIC data. The file data are
+not
+.Em converted ;
+rather, the file is assumed to use EBCDIC representation. String
+literals in the \*[lang] text
+.Em are
+converted, so that they can be compared meaningfully with data in the file.
+.Pp
+Only file data and character literals are affected. Data read from
+and written to the environment, or taken from the command line, are
+interpreted according the
+.Xr locale 7
+in force during execution. The same is true of
+.Sy ACCEPT
+and
+.Sy DISPLAY .
+Names known to the operating system, such as file names and the names
+of environment variables, are processed verbatim.
+.Pp
+At the present time, this is an all-or-nothing setting. Support for
+.Sy USAGE
+and
+.Sy CODESET ,
+which would allow conversion between encodings, remains a future goal.
+.Pp
+See also
+.Sx "Feature-set Variables" ,
+below.
+.
+.Sh REDEFINES ... USAGE POINTER
+Per ISO, an item that
+.Sy REDEFINES
+another may not be larger than the item it redefines, unless that item
+has LEVEL 01 and is not EXTERNAL. In
+.Nm ,
+using
+.Fl dialect Ar ibm ,
+this rule is relaxed for
+.Sy REDEFINES
+with
+.Sy USAGE POINTER
+whose redefined member is a 4-byte
+.Sy USAGE COMP-5
+(usually
+.Sy PIC S9(8) Ns ),
+or vice-versa.
+In that case, the redefined member is re-sized to be 8 bytes, to
+accommodate the pointer. This feature allows pointer arithmetic on a
+64-bit system with source code targeted at a 32-bit system.
+.Pp
+See also
+.Sx "Feature-set Variables" ,
+below.
+.
+.Sh IMPLEMENTATION NOTES
+.Nm
+is a gcc compiler, and follows gcc conventions where applicable.
+Sometimes those conventions (and user expectations) conflict with
+common Mainframe practice. Unless required of the compiler by the ISO
+specification, any such conflicts are resolved in favor of gcc.
+.Ss Linking
+Unlike, C, the \*[lang]
+.Sy CALL
+statement implies dynamic linking, because for
+.D1 Sy CALL Ar program
+.Ar program
+can be a variable whose value is determined at runtime.
+However, the parameter may also be compile-time constant, either an
+alphanumeric literal, or a
+.Sy CONSTANT
+data item.
+.Pp
+.Nm
+supports static linking where possible, unless defeated by
+.Fl fno-static-call .
+If the parameter value is known at compile time, the compiler produces
+an external reference to be resolved by the linker. The referenced
+program is normally supplied via an object module, a static library,
+or a shared object. If it is not supplied, the linker will report an
+.Dq "unresolved symbol"
+error, either at build time or, if using a shared object, when the
+program is executed. This feature informs the programmer of the error
+at the earliest opportunity.
+.Pp
+Programs that are expected to execute
+correctly in the presence of an unresolved symbol (perhaps because the
+program logic won't require that particular
+.Sy CALL )
+can use the
+.Fl no-static-call
+option. That forces all
+.Sy CALL
+statements to be resolved dynamically, at runtime.
+.ig
+Programs that are expected to execute
+correctly in the presence of an unresolved symbol (perhaps because the
+program logic won't require that particular
+.Sy CALL )
+can use linker options to produce an executable anyway.
+.Pp
+One corner case yet remains. The
+.Sy CALL
+statement includes an
+.Sy "ON ERROR"
+clause whose purpose is to handle errors arising when the called program is
not found.
+Control is transferred to the
+.Sy "ON ERROR"
+clause when the
+.Sy EC-PROGRAM-NOT-FOUND
+exception condition is raised. That exception condition is not raised in
+.Nm
+when:
+.Bl -bullet -compact
+.It
+the
+.Sy CALL
+parameter
+is known at compile time, i.e., is an alphanumeric literal or
+.Sy CONSTANT
+data item, and
+.It
+the executable was generated with the linker option to ignore unresolved
symbols.
+.El
+In that case, the program is terminated with a signal. No recovery with
+.Sy "ON ERROR"
+is possible.
+.Pp
+Should your program meet those particular conditions, all is not lost.
+There are workarounds, and an option could be added to use dynamic
+linking for all
+.Sy CALL
+statement, regardless of compile-time constants.
+..
+.
+.Ss Implemented Exception Conditions
+Not all Exception Conditions are implemented. Any attempt to enable
+an EC that that is not implemented produces a warning message.
+The following are implemented:
+.Pp
+.Bl -tag -offset 5n -compact
+.It EC-FUNCTION-ARGUMENT
+.Bl -item -compact
+.It ACOS.It ANNUITY
+.It ASIN
+.It LOG
+.It LOG10
+.It PRESENT-VALUE
+.It SQRT
+.El
+.It EC-SORT-MERGE-FILE-OPEN
+.It EC-BOUND-SUBSCRIPT
+subscript not an integer, less than 1, or greater than occurs
+.It EC-BOUND-REF-MOD
+refmod start not an integer, start less than 1, start greater than
+variable size, length not an integer, length less than 1, and
+start+length exceeds variable size
+.It EC-BOUND-ODO
+DEPENDING not an integer, greater than occurs upper limit,
+less than occurs lower limit, and subscript greater than DEPENDING for sending
item
+.It EC-SIZE-ZERO-DIVIDE
+for both fixed-point and floating-point division
+.It EC-SIZE-TRUNCATION
+.It EC-SIZE-EXPONENTIATION
+.El
+.Pp
+As of this writing, no \*[lang] compiler documents a complete
+implementation of \*[isostd] Exception Conditions.
+.Nm
+will give priority to those ECs that the user community deems most
+valuable.
+.
+.Sh EXTENSIONS TO ISO \*[lang]
+Standard \*[lang] has no provision for environment variables as defined
+by Unix and Windows, or command-line arguments.
+.Nm
+supports them using syntax similar to that of GnuCOBOL. ISO and IBM
+also define incompatible ways to return the program's exit status to
+the operating system.
+.Nm
+supports IBM syntax.
+.
+.Ss Environment Variables
+To read an environment variable:
+.Pp
+.D1 ACCEPT Ar target Li FROM ENVIRONMENT Ar envar
+.Pp
+where
+.Ar target
+is a data item defined in
+.Sy "DATA DIVISION" ,
+and
+.Ar envar
+names an environment variable.
+.Ar envar
+may be a string literal or alphanumeric data item whose value is the
+name of an environment variable. The value of the named environment
+variable is moved to
+.Ar target .
+The rules are the same as for
+.Sy MOVE .
+.Pp
+To write an environment variable:
+.Pp
+.D1 SET ENVIRONMENT Ar envar Li TO Ar source
+.Pp
+where
+.Ar source
+is a data item defined in
+.Sy DATA DIVISION ,
+and
+.Ar envar
+names an environment variable.
+.Ar envar
+again may be a string literal or alphanumeric data item whose value is the
+name of an environment variable. The value of the named environment
+variable is set to the value of
+.Ar source .
+.
+.Ss Command-line Arguments
+To read command-line arguments, use the registers
+.Sy COMMAND-LINE
+and
+.Sy COMMAND-LINE-COUNT
+in an
+.Sy ACCEPT
+statement (only).
+Used without a subscript,
+.Sy COMMAND-LINE
+returns the whole command line as a single string. With a subscript,
+.Sy COMMAND-LINE
+is a table of command-line arguments. For example, if the
+program is invoked as
+.sp
+.D1 Sy ./program Fl i Ar input Ar output
+.sp
+then
+.sp
+.D1 ACCEPT target FROM COMMAND-LINE(3)
+.sp
+moves
+.Ar input
+into
+.Ar target .
+The program name is the first thing in the whole command line and is
+found in COMMAND-LINE(1)
+.Sy COMMAND-LINE
+table.
+.Pp
+To discover how many arguments were provided on the command line, use
+.sp
+.D1 ACCEPT Ar target Li FROM COMMAND-LINE-COUNT
+.sp
+If
+.Sy ACCEPT
+refers to a nonexistent environment variable or command-line
+argument, the target is set to
+.Sy LOW-VALUES .
+.Pp
+The system command line parameters can also be accessed through the LINKAGE
+SECTION in the program where execution starts. The data structure looks like
+this:
+
+ linkage section.
+ 01 argc pic 999.
+ 01 argv.
+ 02 argv-table occurs 1 to 100 times depending on argc.
+ 03 argv-element pointer.
+ 01 argv-string pic x(100) .
+
+and the code to access the third parameter looks like this
+
+ procedure division using by value argc by reference argv.
+ set address of argv-string to argv-element(3)
+ display argv-string
+.
+.Ss #line directive
+The parser accepts lines in the form
+.D1 #line Ar lineno Dq Ar filename Ns .
+The effect is to set the current line number to
+.Ar lineno
+and the current input filename to
+.Ar filename .
+Preprocessors may use this directive to control the filename and line
+numbers reported in error messages and in the debugger.
+.
+.Ss SELECT ... ASSIGN TO
+In the phrase
+.sp
+.D1 ASSIGN TO Ar filename
+.sp
+.Ar filename
+may appear in quotes or not. If quoted, it represents a filename as
+known to the operating system. If unquoted, it names either a data
+element or an environment variable containing the name of a file.
+If
+.Ar filename
+matches the name of a data element, that element is used. If not,
+resolution of
+.Ar filename
+is deferred until runtime, when the name must appear in the program's
+environment.
+.
+.Sh ISO \*[lang] Implementation Status
+.Ss USAGE Data Types
+.Nm
+supports the following
+.Sy USAGE IS
+clauses:
+.Bl -tag -compact -width POINTER\0
+.It Sy INDEX
+for use as an index in a table.
+.It Sy POINTER
+for variables whose value is the address of an external function,
+.Sy PROGRAM-ID ,
+or data item. Assignment is via the
+.Sy SET
+statement.
+.It Sy BINARY, Sy COMP , Sy COMPUTATIONAL, Sy COMP-4, Sy COMPUTATIONAL-4
+big-endian integer, 1 to 16 bytes, per PICTURE.
+.It Sy COMP-1 , Sy COMPUTATIONAL-1 , Sy FLOAT-BINARY-32
+IEEE 754 single-precision (4-byte) floating point, as provided by the
+hardware.
+.It Sy COMP-2 , Sy COMPUTATIONAL-2 , Sy FLOAT-BINARY-64
+IEEE 754 double-precision (8-byte) floating point, as provided by the
+hardware.
+.It Sy COMP-3 , Sy COMPUTATIONAL-3, Sy PACKED-DECIMAL
+currently unimplemented.
+.It Sy COMP-5 , Sy COMPUTATIONAL-5
+little-endian integer, 1 to 16 bytes, per
+.Sy PICTURE.
+.It Sy FLOAT-BINARY-128 , FLOAT-EXTENDED
+implements 128-bit floating point, per IEEE 754.
+.El
+.Pp
+.Nm
+supports ISO integer
+.Sy BINARY-<type>
+types, most of which alias
+.Sy COMP-5.
+.
+.hw unsigned
+.sp
+.TS
+LB LB LB LB
+LB LB LB LB
+L L L L .
+COMP-5 Compatible
+Picture BINARY Type Bytes Value
+ T{
+BINARY-CHAR [UNSIGNED]
+T} 1 0 \(em 256
+S9(1...4) T{
+BINARY-CHAR SIGNED
+T} 1 -128 \(em +127
+\09(1...4) T{
+BINARY-SHORT [UNSIGNED]
+T} 2 0 \(em 65535
+S9(1...4) T{
+BINARY-SHORT SIGNED
+T} 2 -32768 \(em +32767
+\09(5...9) T{
+BINARY-LONG [UNSIGNED]
+T} 4 0 \(em 4,294,967,295
+S9(5...9) T{
+BINARY-LONG SIGNED
+T} 4 T{
+-2,147,483,648 \(em +2,147,483,647
+T}
+\09(10...18) T{
+BINARY-LONG-LONG [UNSIGNED]
+T} 8 T{
+0 \(em 18,446,744,073,709,551,615
+T}
+S9(10...18) T{
+BINARY-LONG-LONG SIGNED
+T} 8 T{
+-9,223,372,036,854,775,808 \(em +9,223,372,036,854,775,807
+T}
+.TE
+.Pp
+These define a size (in bytes) and cannot be
+used with a
+.Sy PICTURE
+clause.
+Per the ISO standard,
+.Sy SIGNED
+is the default for the
+.Sy "BINARY-" Ns Ar type
+aliases.
+.Pp
+All computation \(em both integer and floating point \(em is done
+using 128-bit intermediate forms.
+.
+.Ss Environment Names
+In
+.Nm
+.sp
+.Dl DISPLAY UPON
+.sp
+maps
+.Sy SYSOUT
+and
+.Sy STDOUT
+to standard output, and
+.Sy SYSPUNCH ,
+.Sy SYSPCH
+and
+.Sy STDERR
+to standard error.
+.
+.Ss Exit Status
+.Nm
+supports the ISO syntax for returning an exit status to the operating system,
+.Pp
+.D1 STOP RUN Oo WITH Oc Bro NORMAL | ERROR Brc Oo STATUS Oc Ar status
+.Pp
+In addition,
+.Nm
+also supports the IBM syntax for returning an exit status to
+the operating system. Use the
+.Sy RETURN-CODE
+register:
+.Bd -literal -offset indent
+MOVE ZERO TO RETURN-CODE.
+GOBACK.
+.Ed
+.Pp
+The
+.Sy RETURN-CODE
+register is defined as a 4-byte binary integer.
+.ig
+.Pp
+The ISO standard supports an extended form of
+.Sy GOBACK :
+.Pp
+.D1 GOBACK {ERROR | NORMAL} WITH Ar status
+.Pp
+where
+.Ar status
+is a numeric data item or literal. This syntax has the same effect as:
+.Bd -literal -offset indent
+MOVE status TO RETURN-CODE.
+GOBACK.
+.Ed
+The use of
+.Sy ERROR
+or
+.Sy NORMAL
+has no effect; the two are interchangeable.
+..
+.
+.Ss Compiler-Directing Facility (CDF)
+The CDF is partially implemented, and should be used with caution
+because no comprehensive test suite has been identified. The status
+of CDF directives and statements is shown below.
+.
+.Ss Conditional Compilation
+.Bl -tag -width >>DEFINE
+.It >> Ns Sy DEFINE Ar name Li = Ar expression
+Define
+.Ar name
+to have the value
+.Ar expression
+for the purposes of conditional compilation.
+.Sy AS PARAMETER
+is unimplemented.
+.It >> Ns Sy IF Ar expression Li ... >> Ns Sy END-IF
+evaluates
+.Ar expression
+for conditional compilation.
+If a name,
+.Ar expression
+may be defined with the
+.Fl D
+command-line parameter.
+.Bo Sy IS Bo Sy NOT Bc Bc Sy DEFINED
+is supported. Boolean literals are not supported.
+.It >> Ns Sy EVALUATE
+Not implemented.
+.El
+.
+.Ss Other CDF Directives
+.Bl -tag -width >>PROPAGATE
+.It >> Ns Sy CALL-CONVENTION Ar convention
+.Ar convention
+may be one of:
+.Bl -tag -compact
+.It Sy \*[lang]
+Use standard \*[lang] case-insensitive symbol-name matching. For
+.Sy CALL Dq Ar name ,
+.Ar name
+is rendered by the compiler in lowercase.
+.It Sy C
+Use case-sensitive symbol-name matching. The
+.Sy CALL
+target is not changed in any way; it is used verbatim.
+.It Sy VERBATIM
+An alias for >>\c
+.Sy "CALL-CONVENTION C" .
+.El
+.It >> Ns Sy COBOL-WORDS EQUATE Ar keyword Sy WITH Ar alias
+makes
+.Ar alias
+a synonym for
+.Ar keyword .
+.It >> Ns Sy COBOL-WORDS UNDEFINE Ar keyword
+.Ar keyword
+is removed from the \*[lang] grammar. Use of it in a program will provoke
+a syntax error from the compiler.
+.It >> Ns Sy COBOL-WORDS SUBSTITUTE Ar keyword Sy BY Ar new-word
+.Ar keyword
+is deleted as a keyword from the grammar, replaced by
+.Ar new-word .
+.Ar keyword
+may thereafter be used as a user-defined word.
+.It >> Ns Sy COBOL-WORDS RESERVE Ar new-word
+Treat
+.Ar new-word
+as a \*[lang] keyword. It cannot be used by the program, either as a
+keyword or as a user-defined word.
+.
+.It >> Ns Sy DISPLAY Ar string ...
+Write
+.Ar string
+to standard error as a warning message.
+.It >> Ns Sy SOURCE Ar format
+.Ar format
+may be one of:
+.Bl -tag -compact
+.It Sy FIXED
+Source conforms to \*[lang] Reference Format with unlimited line length.
+.It Sy FREE
+Line endings and indentation are ignored by the compiler, except that a
+.Ql "*"
+at the beginning of a line is recognized as a comment.
+.El
+.El
+.Pp
+.Bl -tag -width >>PROPAGATE -compact
+.It >> Ns Sy FLAG-02
+Not implemented.
+.It >> Ns Sy FLAG-85
+Not implemented.
+.It >> Ns Sy FLAG-NATIVE-ARITHMETIC
+Not implemented.
+.It >> Ns Sy LEAP-SECOND
+Not implemented.
+.It >> Ns Sy LISTING
+Not implemented.
+.It >> Ns Sy PAGE
+Not implemented.
+.It >> Ns Sy PROPAGATE
+Not implemented.
+.It >> Ns Sy TURN Oo
+.Ar ec Oo Ar file Li ... Oc ...
+.Oc Sy CHECKING Bro Oo Sy ON Oc Oo Oo Sy WITH Oc Sy LOCATION Oc | Sy OFF Brc
+Enable (or, with
+.Sy OFF ,
+disable) exception condition
+.Ar ec
+optionally associated with the file connectors
+.Ar file .
+If
+.Sy LOCATION
+is specified,
+.Nm
+reports at runtime the source filename and line number of the
+statement that triggered the exception condition.
+.El
+.
+.Ss Feature-set Variables
+Some command-line options affect CDF
+.Em "feature-set"
+variables that are special to
+.Nm .
+They can be set and tested using
+.Sy >>DEFINE
+and
+.Sy >>IF ,
+and are distinguished by a leading
+.Ql \&%
+in the name, which is otherwise invalid in a \*[lang] identifier:
+.Pp
+.Bl -tag -compact
+.It Sy %EBCDIC-MODE
+is set by
+.Fl finternal-ebcdic .
+.It Sy %64-BIT-POINTER
+is implied by
+.Fl "dialect ibm" .
+.El
+.Pp
+To set a feature-set variable, use
+.Dl >>SET Ar feature Li [AS] {ON | OFF}
+If
+.Ar feature
+is
+.Sy %EBCDIC-MODE ,
+the directive must appear before
+.Sy PROGRAM-ID .
+.Pp
+To test a feature-set variable, use
+.Dl >>IF Ar feature Li DEFINED
+..
+.Ss Copybooks
+.Nm
+supports the CDF
+.Sy COPY
+statement, with or without its
+.Sy REPLACING
+component. For any statement
+.sp
+.D1 COPY Ar copybook
+.sp
+.Nm
+looks first for an environment variable named
+.Va copybook
+and, if found, uses the contents of that variable as the name of the
+copybook file. If that file does not exist, it continues looking for
+a file named one of:
+.sp
+.Bl -bullet -compact -offset 5n
+.It
+.Pa copybook
+(literally)
+.It
+.Pa copybook.cpy
+.It
+.Pa copybook.CPY
+.It
+.Pa copybook.cbl
+.It
+.Pa copybook.CBL
+.It
+.Pa copybook.cob
+.It
+.Pa copybook.COB
+.El
+.sp
+in that order. It looks first in the same directory as the source
+code file, and then in any
+.Ar copybook-path
+named with the
+.Fl I
+option.
+.
+.\" FIXME: need escape mechanism for directories with ':' in the name.
+.Ar copybook-path
+may (like the shell's
+.Ev PATH
+variable) be a colon-separated list.
+.
+The
+.Fl I
+option may occur multiple times on the command line. Each successive
+.Ar copybook-path
+is concatenated to previous ones.
+Relative paths (having no leading
+.Ql / Ns
+\&)
+are searched relative to the compiler's current working directory.
+.Pp
+For example,
+.D1 \&
+.D1 Fl I Li /usr/local/include:include
+.D1 \&
+searches first the directory where the \*[lang] program is found, next in
+.Pa /usr/local/include ,
+and finally in an
+.Pa include
+subdirectory of the directory from which
+.Nm
+was invoked.
+.
+.Ss Intrinsic functions
+.Nm
+implements all intrinsic functions defined by \*[isostd], plus a few
+others. They are listed alphabetically below.
+.Pp
+ABS ACOS ANNUITY ASIN ATAN BASECONVERT BIT_OF BIT_TO_CHAR
+BOOLEAN_OF_INTEGER BYTE_LENGTH CHAR CHAR_NATIONAL COMBINED_DATETIME
+CONCAT CONVERT COS CURRENT_DATE DATE_OF_INTEGER DATE_TO_YYYYMMDD
+DAY_OF_INTEGER DAY_TO_YYYYDDD DISPLAY_OF E EXCEPTION_FILE
+EXCEPTION_FILE_N EXCEPTION_LOCATION EXCEPTION_LOCATION_N
+EXCEPTION_STATEMENT EXCEPTION_STATUS EXP EXP10 FACTORIAL FIND_STRING
+FORMATTED_CURRENT_DATE FORMATTED_DATE FORMATTED_DATETIME
+FORMATTED_TIME FRACTION_PART HEX_OF HEX_TO_CHAR HIGHEST_ALGEBRAIC
+INTEGER INTEGER_OF_BOOLEAN INTEGER_OF_DATE INTEGER_OF_DAY
+INTEGER_OF_FORMATTED_DATE INTEGER_PART LENGTH LOCALE_COMPARE
+LOCALE_DATE LOCALE_TIME LOCALE_TIME_FROM_SECONDS LOG LOG10 LOWER_CASE
+LOWEST_ALGEBRAIC MAX MEAN MEDIAN MIDRANGE MIN MOD MODULE_NAME
+NATIONAL_OF NUMVAL NUMVAL_C NUMVAL_F ORD ORD_MAX ORD_MIN PI
+PRESENT_VALUE RANDOM RANGE REM REVERSE SECONDS_FROM_FORMATTED_TIME
+SECONDS_PAST_MIDNIGHT SIGN SIN SMALLEST_ALGEBRAIC SQRT
+STANDARD_COMPARE STANDARD_DEVIATION SUBSTITUTE SUM TAN
+TEST_DATE_YYYYMMDD TEST_DAY_YYYYDDD TEST_FORMATTED_DATETIME
+TEST_NUMVAL TEST_NUMVAL_C TEST_NUMVAL_F TRIM ULENGTH UPOS UPPER_CASE
+USUBSTR USUPPLEMENTARY UUID4 UVALID UWIDTH VARIANCE WHEN_COMPILED
+YEAR_TO_YYYY
+.
+.Ss Binary floating point DISPLAY
+How the DISPLAY presents binary floating point numbers depends on the value.
+.Pp
+When a value has six or fewer decimal digits to the left of the
+decimal point, it is expressed as
+.Em 123456.789... .
+.Pp
+When a value is less than 1 and has no more than three zeroes to the
+right of the decimal point, it is expressed as
+.Em 0.0001234... .
+.Pp
+Otherwise, exponential notation is used:
+.Em 1.23456E+7 .
+.Pp
+In all cases, trailing zeroes on the right of the number are removed
+from the displayed value.
+.Pp
+.Bl -tag -compact -width FLOAT-EXTENDED
+.It COMP-1
+displayed with 9 decimal digits.
+.It COMP-2
+displayed with 17 decimal digits.
+.It FLOAT-EXTENDED
+displayed with 36 decimal digits.
+.El
+.Pp
+Those digit counts are consistent with the IEEE 754 requirements for
+information interchange. As one example, the description for COMP-2
+binary64 values (per Wikipedia).
+.Pp
+If an IEEE 754 double-precision number is converted to a decimal
+string with at least 17 significant digits, and then converted back to
+double-precision representation, the final result must match the
+original number.
+.Pp
+17 digits was chosen so that the
+.Sy DISPLAY
+statement shows the contents
+of a COMP-2 variable without hiding any information.
+.
+.Ss Binary floating point MOVE
+During a
+.Sy MOVE
+statement, a floating-point value may be truncated. It will not be
+unusual for Numeric Display values to be altered when moved through a
+floating-point value.
+.Pp
+This program:
+.Bd -literal
+ 01 PICV999 PIC 9999V999.
+ 01 COMP2 COMP-2.
+ PROCEDURE DIVISION.
+ MOVE 1.001 to PICV999
+ MOVE PICV999 TO COMP2
+ DISPLAY "The result of MOVE " PICV999 " TO COMP2 is " COMP2
+ MOVE COMP2 to PICV999
+ DISPLAY "The result of MOVE COMP2 TO PICV999 is " PICV999
+.Ed
+.Pp
+generates this result:
+.Bd -literal
+ The result of MOVE 0001.001 TO COMP2 is 1.00099999999999989
+ The result of MOVE COMP2 TO PICV999 is 0001.000
+.Ed
+.Pp
+However, the internal implementation can produce results that might be seem
surprising:
+.Bd -literal
+ The result of MOVE 0055.110 TO COMP2 is 55.1099999999999994
+ The result of MOVE COMP2 TO PICV999 is 0055.110
+.Ed
+.Pp
+The source of this inconsistency is the way
+.Nm
+stores and converts
+numbers. Converting the floating-point value to the numeric display
+value 0055110 is done by multiplying 55.109999...\& by 1,000 and then
+truncating the result to an integer. And it turns out that even
+though 55.11 can?t be represented in floating-point as an exact value,
+the product of the multiplication, 55110, is an exact value.
+.Pp
+In cases where it is important for conversions to have predictable
+results, we need to be able to apply rounding, which can be done with
+an arithmetic statement:
+.Bd -literal
+ MOVE 1.001 to PICV999
+ MOVE PICV999 TO COMP2
+ DISPLAY "The result of MOVE " PICV999 " TO COMP2 is " COMP2
+ MOVE COMP2 to PICV999
+ DISPLAY "The result of MOVE COMP2 TO PICV999 is " PICV999
+ ADD COMP2 to ZERO GIVING PICV999 ROUNDED
+ DISPLAY "The result of ADD COMP2 to ZERO GIVING PICV999 ROUNDED is "
PICV999
+
+ The result of MOVE 0001.001 TO COMP2 is 1.00099999999999989
+ The result of MOVE COMP2 TO PICV999 is 0001.000
+ The result of ADD COMP2 to ZERO GIVING PICV999 ROUNDED is 0001.001
+.Ed
+.Ss Binary floating point computation
+.Nm
+attempts to do internal computations using binary integers when
+possible. Thus, simple arithmetic between binary values and numeric
+display values conclude with binary intermediate results.
+.Pp
+If a floating-point value gets included in the mix of variables
+specified for a calculation, then the intermediate result becomes a
+128-bit floating-point value.
+.
+.Ss A warning about binary floating point comparison
+The cardinal rule when doing comparisons involving floating-point
+values: Never, ever, test for equality. It?s just not worth the hassle.
+.Pp
+For example:
+.Bd -literal
+ WORKING-STORAGE SECTION.
+ 01 COMP1 COMP-1 VALUE 555.11.
+ 01 COMP2 COMP-2 VALUE 555.11.
+ PROCEDURE DIVISION.
+ DISPLAY "COMPARE " COMP1 " with " COMP2
+ IF COMP1 EQUAL COMP2 DISPLAY "Equal" ELSE DISPLAY "Not equal" END-IF
+
+ MOVE COMP1 to COMP2
+ DISPLAY "COMPARE " COMP1 " with " COMP2
+ IF COMP1 EQUAL COMP2 DISPLAY "Equal" ELSE DISPLAY "Not equal" END-IF
+.Ed
+.Pp
+the results:
+.Bd -literal
+ COMPARE 555.1099854 with 555.110000000000014
+ Not equal
+ COMPARE 555.1099854 with 555.1099853515625
+ Equal
+.Ed
+.Pp
+Why? Again, it has to do with the internals of
+.Nm .
+When differently sized floating-point values need to be compared, they
+are first converted to 128-bit floats. And it turns out that when a
+COMP1 is moved to a COMP2, and they are both converted to
+FLOAT-EXTENDED, the two resulting values are (probably) equal.
+.Pp
+Avoid testing for equality unless you really know what you are doing
+and you really test the code. And then avoid it anyway.
+.Pp
+Finally, it is observably the case that the
+.Nm
+implementations of floating-point conversions and comparisons don?t
+precisely match the behavior of other \*[lang] compilers.
+.Pp
+You have been warned.
+.
+.Sh ENVIRONMENT
+.Bl -tag -width COBPATH
+.It Ev COBPATH
+If defined, specifies the directory paths to be used by the
+.Nm
+runtime library,
+.Pa libgcobol.so ,
+to locate shared objects.
+Like
+.Ev LD_LIBRARY_PATH ,
+it may contain several directory names separated by a colon
+.Pq Ql \&: .
+.Ev COBPATH
+is searched first, followed by
+.Ev LD_LIBRARY_PATH .
+.Pp
+Each directory is searched for files whose name ends in
+.Ql ".so" .
+For each such file,
+.Xr dlopen 3
+is attempted, and, if successful
+.Xr dlsym 3 .
+No relationship is defined between the symbol's name and the filename.
+.Pp
+Without
+.Ev COBPATH ,
+binaries produced by
+.Nm
+behave as one might expect of any program compiled with gcc. Any
+shared objects needed by the program are mentioned on the command line
+with a
+.Fl l Ns Ar library
+option, and are found by following the executable's
+.Pa RPATH
+or otherwise per the configuration of the runtime linker,
+.Xr ld.so 8 .
+.
+.It Ev UPSI
+\*[lang] defines a User Programmable Status Indicator (UPSI) switch. In
+.Nm ,
+the settings are denoted
+.Sy UPSI-0
+through
+.Sy UPSI-7 ,
+where 0-7 indicates a bit position. The value of the UPSI switches is
+taken from the
+.Ev UPSI
+environment variable, whose value is a string of up to eight 1's and
+0's. The first character represents the value of
+.Sy UPSI-0 ,
+and missing values are assigned 0. For example,
+.Sy UPSI=1000011
+in the environment sets bits 0, 5, and 6 on, which means that
+.Sy UPSI-0 ,
+.Sy UPSI-5 ,
+and
+.Sy UPSI-6
+are on.
+.It Ev GCOBOL_TEMPDIR
+causes any temporary files created during CDF processing to be written
+to a file whose name is specified in the value of
+.Ev GCOBOL_TEMPDIR .
+If the value is just
+.Dq / ,
+the effect is different: each copybook read is reported on standard
+error. This feature is meant to help diagnose mysterious copybook
+errors.
+.El
+.
+.Sh FILES
+Executables produced by
+.Nm
+require the runtime support library
+.Pa libgcobol ,
+which is provided both as a static library and as a shared object.
+.
+.\" .Sh DIAGNOSTICS
+.
+.Sh COMPATIBILITY
+The ISO standard leaves the default file organization up to the
implementation; in
+.Nm ,
+the default is
+.Sy "SEQUENTIAL" .
+.
+.Ss On-Disk Format
+Any ability to use files produced by other \*[lang] compilers, or for
+those compilers to use files produced by
+.Nm ,
+is the product of luck and intuition. Various compilers interpret the
+ISO standard differently, and the standard's text is
+not always definitive.
+.Pp
+For
+.Sy "ORGANIZATION IS LINE SEQUENTIAL"
+files (explicitly or by default),
+.Nm ,
+absent specific direction, produces an ordinary Linux text file: for
+each WRITE, the data are written, followed by an ASCII NL (hex 0A)
+character. On READ, the record is read up to the size of the
+specified record or NL, whichever comes first. The NL is not included
+in the data brought into the record buffer; it serves only as an
+on-disk record-termination marker. Consequently,
+.Sy SEQUENTIAL
+and
+.Sy "LINE SEQUENTIAL"
+files work the same way: the \*[lang] program never sees the record
+terminator.
+.Pp
+When
+.Sy READ
+and
+.Sy WRITE
+are used with
+.Sy ADVANCING ,
+however, the game changes. If
+.Sy ADVANCING
+is used with
+.Sy "LINE SEQUENTIAL"
+files,
+it is honored by
+.Nm .
+.Pp
+Other compilers may not do likewise.
+According to ISO, in
+.Sy WRITE
+(14.9.47.3 General rules)
+.Sy ADVANCING
+is
+.Em ignored
+for files for which
+.Dq "the physical file does not support vertical positioning" .
+It further states that, in the absence of
+.Sy ADVANCING ,
+.Sy WRITE
+proceeds as if
+.Dq "as if the user has specified AFTER ADVANCING 1 LINE" .
+Some other implementations interpret that to mean that the first
+.Sy WRITE
+to a
+.Sy "LINE SEQUENTIAL"
+file results in a leading NL on the first line, and no trailing NL on
+the last line. Some furthermore
+.Em prohibit
+the use of
+.Sy ADVANCING
+with
+.Sy "LINE SEQUENTIAL"
+files.
+.
+.\" .Sh SEE ALSO
+.
+.Sh STANDARDS
+The reference standard for
+.Nm
+is \*[isostd].
+.Bl -bullet -compact
+.It
+If
+.Nm
+compiles code consistent with that standard, the resulting program
+should execute correctly; any other result is a bug.
+.It
+If
+.Nm
+compiles code that does not comply with that standard, but runs correctly
according to some other specification, that represents a non-standard
extension. One day, the
+.Fl pedantic
+option will produce diagnostic messages for such code.
+.It
+If
+.Nm
+rejects code consistent with that standard, that represents an aspect
+of \*[lang] that is (or is not) on the To Do list. If you would like
+to see it compile, please get in touch with the developers.
+.El
+.
+.Ss Status of NIST \*[lang] Compiler Verification Suite
+.Bl -tag -compact -width "\0\0100% NC"
+.It NC 100%
+Nucleus
+.It SQ 100%
+Sequential I/O
+.It RL 100%
+Relative I/O
+.It IX 100%
+Indexed I/O
+.It IC 100%
+Inter-Program Communication
+.It ST 100%
+Sort-Merge
+.It SM 100%
+Source Text Manipulation RW \en Report Writer
+.It CM
+Communication
+.It DB to do?
+Debug
+.It SG
+Segmentation
+.It IF 100%
+Intrinsic Function
+.El
+.Pp
+Where
+.Nm
+passes 100% of the tests in a module, we exclude the (few) tests for
+obsolete features. The authors regard features that were obsolete in
+1985 to be well and truly obsolete today, and did not implement them.
+.
+.Ss Notable deferred features
+CCVS-85 modules not marked with above with any status (CM, and SG) are on the
+.Dq "hard maybe"
+list, meaning they await an interested party with real code using the feature.
+.Pp
+.Nm
+does not implement Report Writer or Screen Section.
+.
+.Ss Beyond COBOL/85
+.Nm
+increasingly implements \*[isostd]. For example,
+.Sy DECLARATIVES
+is not tested by CCVS-85, but are implemented by
+.Nm Ns .
+Similarly, Exception Conditions were not defined in 1985, and
+.Nm
+contains a growing number of them.
+.Pp
+The authors are well aware that a complete, pure \*[lang]-85 compiler
+won't compile most existing \*[lang] code. Every vendor offered (and
+offers) extensions, and most environments rely on a variety of
+preprocessors and ancillary systems defined outside the standard. The
+express goal of adding an ISO \*[lang] front-end to GCC is to establish a
+foundation on which any needed extensions can be built.
+.
+.Sh HISTORY
+\*[lang], the language, may well be older than the reader. To the
+author's knowledge, free \*[lang] compilers first began to appear in 2000.
+Around that time an earlier \*[lang] for GCC project
+.br
+(https://cobolforgcc.sourceforge.net/)
+met with some success, but was never officially merged into GCC.
+.Pp
+This compiler,
+.Nm ,
+was begun by COBOLworx (www.cobolworx.com) in the fall of 2021. The
+project announced a complete implementation of the core language
+features in December 2022.
+.
+.Sh AUTHORS
+.Bl -tag -compact
+.It "James K. Lowden"
+(jklow...@cobolworx.com) is responsible for the parser.
+.It "Robert Dubner"
+(rdub...@cobolworx.com) is responsible for producing the GIMPLE tree,
+which is input to the GCC back-end.
+.
+.Sh CAVEATS
+.Bl -bullet -compact
+.It
+.Nm
+has been tested only on x64 and Apple M1 processors running Linux in
+64-bit mode.
+.It
+The I/O support has not been extensively tested, and does not
+implement or emulate many features related to VSAM and other mainframe
+subsystems. While LINE-SEQUENTIAL files are ordinary text files that
+can be manipulated with standard utilities, INDEXED and RELATIVE files
+produced by
+.Nm
+are not compatible with that of any other \*[lang] compiler. Enhancements
+to the I/O support will be readily available to the paying customer.
+.El
+.
+.\" .Sh BUGS
diff --git a/gcc/cobol/gcobol.3 b/gcc/cobol/gcobol.3
new file mode 100644
index 00000000000..6d3e20c50e5
--- /dev/null
+++ b/gcc/cobol/gcobol.3
@@ -0,0 +1,332 @@
+.ds lang COBOL
+.ds gcobol GCC\ \*[lang]\ Front-end
+.Dd \& March 2024
+.Dt GCOBOL 3\& "GCC \*[lang] Compiler"
+.Os Linux
+.Sh NAME
+.Nm gcobol
+.Nd \*[gcobol] I/O function API
+.Sh LIBRARY
+.Pa libgcobol
+.
+.Sh SYNOPSIS
+.In symbols.h
+.In io.h
+.In gcobolio.h
+.
+.Ft gcobol_io_t Fn gcobol_fileops
+.sp
+class gcobol_io_t {
+.br
+public:
+ static const char constexpr marquee[64];
+.
+ typedef void (open_t)( cblc_file_t *file,
+ char *filename,
+ int mode_char,
+ int is_quoted );
+ typedef void (close_t)( cblc_file_t *file,
+ int how );
+ typedef void (start_t)( cblc_file_t *file,
+ int relop, // needs enum
+ int first_last_key,
+ size_t length );
+ typedef void (read_t)( cblc_file_t *file,
+ int where );
+ typedef void (write_t)( cblc_file_t *file,
+ unsigned char *data,
+ size_t length,
+ int after,
+ int lines,
+ int is_random );
+ typedef void (rewrite_t)( cblc_file_t *file,
+ size_t length, bool is_random );
+ typedef void (delete_t)( cblc_file_t *file,
+ bool is_random );
+.
+ open_t *Open;
+ close_t *Close;
+ start_t *Start;
+ read_t *Read;
+ write_t *Write;
+ rewrite_t *Rewrite;
+ delete_t *Delete;
+.
+\&...
+.br
+};
+.
+.Sh DESCRIPTION
+.Nm
+supplies replaceable I/O functionality via
+.Fn gcobol_fileops .
+It returns a pointer to a structure of C function pointers that
+implement sequential, relative, and indexed file operations over files
+whose On Disk Format (ODF) is defined by
+.Nm .
+A user wishing to use another library that implements the same
+functionality over a different ODF must supply a different implementation of
+.Fn gcobol_fileops ,
+plus 7 functions, as described in this document. The pointers to
+those user-implemented functions are placed in a C++ object of type
+.Vt gcobol_io_t
+and an instantiation of that type is returned by
+.Fn gcobol_fileops .
+The compiled program initializes I/O operations by calling that
+function the first time any file is opened.
+.Pp
+Each function takes as its first argument a pointer to a
+.Vt cblc_file_t
+object, which is analogous to a
+.Vt FILE
+object used in the C
+.Sy stdio
+functions. The
+.Vt cblc_file_t
+structure acts as a communication area between the compiled program
+and the I/O library. Any information needed about the file is kept
+there. Notably, the outcome of any operation is stored in that
+structure in the
+.Va file_status
+member, not as a return code. Information about the
+.Em operation
+(as opposed to the
+.Em file )
+appear as parameters to the function.
+.Pp
+.Vt cblc_file_t
+has one member, not used by
+.Nm ,
+that is reserved for the user:
+.Dl Vt "void *" Pa implementation .
+.Pp
+User-supplied I/O functions may assign and dereference
+.Pa implementation .
+.Nm
+will preserve the value, but never references it.
+.Pp
+The 7 function pointers in
+.Vt gcobol_io_t
+are
+.Bl -hang -width Rewrite
+.It Open
+.Ft void
+.Fn open_t "cblc_file_t *file" "char *filename" "int mode_char" "int is_quoted"
+.br
+parameters:
+.Bl -tag -width mode_char -compact
+.It Ar filename
+is the filename, as known to the OS
+.It Ar mode_char
+is one of
+.Bl -hang -width MM -compact
+.It Sq r
+OPEN INPUT: read-only mode
+.It Sq w
+OPEN OUTPUT: create a new file or overwrite an existing one
+.It Sq a
+EXTEND: append to sequential file
+.It Sq +
+modify existing file
+.El
+.It Ar is_quoted
+If
+.Sy true ,
+.Ar filename
+is taken literally. If
+.Sy false ,
+.Ar filename
+is interpreted as the name of an environment variable, the contents of
+which, if extant, are taken as the name of the file to be opened. If
+no such variable exists, then
+.Ar filename
+is used verbatim.
+.El
+.It Close
+.Ft void
+.Fn close_t "cblc_file_t *file" "int how"
+.br
+parameters:
+.Bl -hang -width how -compact
+.It Ar how
+A value of 0x08 closes a
+.Dq REEL\ unit .
+Because no such thing is supported, the function sets the file status to
+.Dq 07 ,
+meaning
+.Em "not a tape" .
+.El
+.It Start
+.Ft void
+.Fn start_t "cblc_file_t *file" "int relop" "int first_last_key" "size_t
length"
+.br
+parameters:
+.Bl -tag -width length -compact
+.It Ar relop
+is one of
+.Bl -hang -width LT -compact
+.It Li 0
+means
+.Sq <
+.It Li 1
+means
+.Sq <=
+.It Li 2
+means
+.Sq =
+.It Li 3
+means
+.Sq !=
+.It Li 4
+means
+.Sq >=
+.It Li 5
+means
+.Sq >
+.El
+.It Ar first_last_key
+is the key number (starting at 1) of the key within the
+.Vt cblc_file_t
+structure.
+.It Ar length
+is the size of the key (TODO: per the START statement?)
+.El
+.It Read
+.Ft void
+.Fn read_t "cblc_file_t *file" "int where"
+parameters:
+.Bl -tag -width where -compact
+.It Ar where
+.Bl -hang -width 000 -compact
+.It Li -2
+PREVIOUS
+.It Li -1
+NEXT
+.It Ar \0N
+represents a key number, starting with 1, in the
+.Vt cblc_file_t
+structure. The value of that key is used to find the record, and read it.
+.El
+.El
+.It Write
+.Ft void
+.Fn write_t "cblc_file_t *file" "unsigned char *data" \
+"size_t length" "int after" "int lines" "int is_random"
+.br
+parameters:
+.Bl -hang -width is_random -compact
+.It Ar data
+address of in-memory buffer to write
+.It Ar length
+length of in-memory buffer to write
+.It Ar after
+has the value 1 if the
+.D1 "AFTER ADVANCING n LINES"
+phrase was present in the
+.Sy WRITE
+statement, else 0
+.It Ar lines
+may be one of
+.Bl -hang -width 00000 -compact
+.It Li -666
+ADVANCING PAGE
+.It Li \0\0-1
+no
+.Sy ADVANCING
+phrase appeared
+.It \0\0\00
+ADVANCING 0 LINES
+is valid
+.It \0\0>0
+the value of
+.Ar n
+in
+ADVANCING
+.Ar n
+LINES
+.El
+.It Ar is_random
+is
+.Sy true
+if the
+.Em "access mode"
+is RANDOM
+.El
+.It Rewrite
+.Ft void
+.Fn rewrite_t "cblc_file_t *file" "size_t length" "bool is_random"
+parameters:
+.Bl -hang -width is_random -compact
+.It Ar length
+number of bytes to write
+.It Ar is_random
+.Sy true
+if
+.Em "access mode"
+is RANDOM
+.El
+.It Delete
+.Ft void
+.Fn delete_t "cblc_file_t *file" "bool is_random"
+parameters:
+.Bl -hang -width is_random -compact
+.It Ar is_random
+.Sy true
+if
+.Em "access mode"
+is RANDOM
+.El
+.El
+.
+.Pp
+The library implements one function that the
+.Nm Ns
+-produced binary calls directly:
+.Bl -item
+.It
+.Ft gcobol_io_t *
+.Fn gcobol_fileops
+.br
+This function populates a
+.Vt gcobol_io_t
+object with the above function pointers. The compiled binary begins
+by calling
+.Fn gcobol_fileops Ns ,
+and then uses the supplied pointers to effect I/O.
+.El
+.
+.\" The following commands should be uncommented and
+.\" used where appropriate.
+.\" .Sh IMPLEMENTATION NOTES
+.\" This next command is for sections 2, 3, and 9 only
+.\" (function return values).
+.Sh RETURN VALUES
+I/O functions return
+.Sy void .
+.Fn gcobol_fileops
+returns
+.Vt gcobol_io_t* .
+.\" .Sh FILES
+.\" .Sh COMPATIBILITY
+.\" This next command is for sections 2, 3, 4, and 9 only
+.\" (settings of the errno variable).
+.\" .Sh ERRORS
+.\" .Sh SEE ALSO
+.Sh STANDARDS
+The I/O library supplied by
+.Nm ,
+.Sy libgcobolio.so ,
+supports the I/O semantics defined by ISO \*[lang].
+It is not intended to be compatible with any other ODF. That is,
+.Sy libgcobolio.so
+cannot be used to exchange data with any other \*[lang] implementation.
+.Pp
+The purpose of the
+.Vt gcobol_io_t
+structure is to allow the use of other I/O implementations with other ODF
representations.
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.Sh CAVEATS
+The library is not well tested, not least because it is not implemented.
+.Sh BUGS
+The future is yet to come.
diff --git a/gcc/cobol/help.gen b/gcc/cobol/help.gen
new file mode 100755
index 00000000000..6aa201f0ac7
--- /dev/null
+++ b/gcc/cobol/help.gen
@@ -0,0 +1,15 @@
+#! /usr/bin/awk -f
+
+BEGIN {
+ print "puts("
+}
+
+/^ {5}[-][[:alnum:]-]+/, /[.] / {
+ gsub(/[.] .+/, ". ")
+ gsub(/^ /, "");
+ print "\t\"" $0 "\\n\""
+}
+
+END {
+ print ");"
+}
