\input texinfo   @comment -*-texinfo-*-
@comment %**start of header
@comment *********************************************************************
@comment ** DOCUMENT HEADER                                                 **
@comment *********************************************************************
@comment ** SPECIAL INSTRUCTIONS WHEN RUNNING "MAKEINFO":                   **
@comment ** --------------------------------------------------------------- **
@comment ** Use the command "makeinfo --no-split gnucobsp.texi" to build    **
@comment ** an INFO file from this source.                                  **
@comment *********************************************************************
@comment ** SPECIAL INSTRUCTIONS WHEN RUNNING "TEXI2PDF":                   **
@comment ** --------------------------------------------------------------- **
@comment ** Use the command "texi2pdf -q -c gnucobsp-xx.texi" to build a    **
@comment ** PDF (xx="a4" or "letter")                                       **
@comment *********************************************************************
@set CHAPNAME Contents
@setfilename gnucobsp.info

@finalout
@include Macros.texi
@paragraphindent 0
@set BUILD 14 January 2024 at 15:30 GMT.
@set VERSION 3.2 - Final
@comment %**end of header
@setchapternewpage odd
@comment *********************************************************************
@comment ** COPYING POLICY STATEMENT                                        **
@comment *********************************************************************
@copying
This manual documents GnuCOBOL @value{VERSION}, @value{BUILD} build.

@verbatim
Document  Copyright 2009-2014 Gary L. Cutler, FSF (Free Software Foundation).
Updates:  Copyright 2014-2024 Vincent B. Coen, Gary L. Cutler & FSF.
@end verbatim
@quotation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License [FDL], Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU Free Documentation License".

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

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

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

@end quotation
@end copying
@dircategory GnuCOBOL
@direntry
* GnuCOBOL: (gnucobsp)        GnuCOBOL Sample Programs
@end direntry
@comment *********************************************************************
@comment ** TITLE PAGE (WHEN GENERATING PDF VIA TeX)                        **
@comment *********************************************************************
@titlepage
@title GnuCOBOL Sample Programs
@subtitle For Version @value{VERSION} [@value{BUILD}], for 3.3 and 4.0 (partial & tentative only).
@author Gary L. Cutler (@email{cutlergl@@gmail.com}).
@author For updates Vincent B. Coen (@email{vbcoen@@gmail.com}).
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@comment *********************************************************************
@comment ** TABLE OF CONTENTS (WHEN GENERATING PDF VIA TeX)                 **
@comment *********************************************************************
@headings off
@oddheading GnuCOBOL @value{VERSION} [@value{BUILD}] Sample Programs @| @| @thispage
@oddfooting @today{} @| @| @value{CHAPNAME}
@evenheading @thispage @| @| GnuCOBOL @value{VERSION} [@value{BUILD}] Sample Programs
@evenfooting @value{CHAPNAME} @| @| @today{}
@contents
@comment *********************************************************************
@comment ** TOP NODE POINT (Ignore if running TeX)                          **
@comment *********************************************************************
@ifinfo
@node Top
@top GnuCOBOL Sample Programs
This manual presents sample programs written for GnuCOBOL @value{VERSION} [@value{BUILD}].
@menu
* FileStat-Msgs. (A FILE-STATUS values copybook)
* COBDUMP.       (An ASCII/Hex dump subroutine)
* Colors.        (Show all possible color/attribute combinations)
* DAY-FROM-DATE. (Find day-of-week for any date)
* GCic.          (An interactive front-end to cobc)
* STREAMIO.      (Simplified stream I/O subroutine)
* GNU Free Documentation License.
@end menu
@end ifinfo
@settitle GnuCOBOL Sample Programs @value{VERSION} [@value{BUILD}]
@comment *********************************************************************
@comment ** Document Body                                                   **
@comment *********************************************************************
@comment *********************************************************************
@comment ** 1. FileStat-Msgs                                                **
@comment *********************************************************************
@newchapter{FileStat-Msgs}
The FileStat-Msgs.cpy copybook contains an EVALUATE statement to translate the two-digit file status codes that may be generated by file I/O statements.

The copybook assumes that the file status data item name is "STATUS" and the error message data item is named "MSG".  By using the COPY statement's REPLACING clause, however, you may use the data names you wish, as follows:

@example
COPY FileStat-Msgs
    REPLACING STATUS BY file-status-data-item-name
              MSG    BY error-message-data-item-name
@end example

Here's the current FileStat-Msgs.cpy copybook:

@example
EVALUATE STATUS
     WHEN 00 MOVE 'SUCCESS                  ' TO MSG
     WHEN 02 MOVE 'SUCCESS DUPLICATE        ' TO MSG
     WHEN 04 MOVE 'SUCCESS INCOMPLETE       ' TO MSG
     WHEN 05 MOVE 'SUCCESS OPTIONAL         ' TO MSG
     WHEN 06 MOVE 'LS Multiple records      ' TO MSG
     WHEN 07 MOVE 'SUCCESS NO UNIT          ' TO MSG
     WHEN 10 MOVE 'END OF FILE              ' TO MSG
     WHEN 14 MOVE 'OUT OF KEY RANGE         ' TO MSG
     WHEN 21 MOVE 'KEY INVALID              ' TO MSG
     WHEN 22 MOVE 'KEY EXISTS               ' TO MSG
     WHEN 23 MOVE 'KEY NOT EXISTS           ' TO MSG
     WHEN 24 MOVE 'KEY BOUNDARY VIOLATION   ' TO MSG
     WHEN 30 MOVE 'PERMANENT ERROR          ' TO MSG
     WHEN 31 MOVE 'INCONSISTENT FILENAME    ' TO MSG
     WHEN 34 MOVE 'BOUNDARY VIOLATION       ' TO MSG
     WHEN 35 MOVE 'FILE NOT FOUND           ' TO MSG
     WHEN 37 MOVE 'PERMISSION DENIED        ' TO MSG
     WHEN 38 MOVE 'CLOSED WITH LOCK         ' TO MSG
     WHEN 39 MOVE 'CONFLICT ATTRIBUTE       ' TO MSG
     WHEN 41 MOVE 'ALREADY OPEN             ' TO MSG
     WHEN 42 MOVE 'NOT OPEN                 ' TO MSG
     WHEN 43 MOVE 'READ NOT DONE            ' TO MSG
     WHEN 44 MOVE 'RECORD OVERFLOW          ' TO MSG
     WHEN 46 MOVE 'READ ERROR               ' TO MSG
     WHEN 47 MOVE 'INPUT DENIED             ' TO MSG
     WHEN 48 MOVE 'OUTPUT DENIED            ' TO MSG
     WHEN 49 MOVE 'I/O DENIED               ' TO MSG
     WHEN 51 MOVE 'RECORD LOCKED            ' TO MSG
     WHEN 52 MOVE 'END-OF-PAGE              ' TO MSG
     WHEN 57 MOVE 'I/O LINAGE               ' TO MSG
     WHEN 61 MOVE 'FILE SHARING FAILURE     ' TO MSG
     WHEN 71 MOVE 'BAD CHARACTER            ' TO MSG
     WHEN 91 MOVE 'FILE NOT AVAILABLE       ' TO MSG
     WHEN OTHER MOVE 'UNKNOWN ERROR         ' TO MSG
END-EVALUATE.
@end example
@comment *********************************************************************
@comment ** 2. COBDUMP                                                      **
@comment *********************************************************************
@newchapter{COBDUMP}
COBDUMP is a useful little utility subroutine to produce a formatted hexadecimal and character dump of the data area passed to it.

If you follow the GnuCOBOL forums, you've undoubtedly heard about the CBL_OC_DUMP subroutine that was the winning entry in a GnuCOBOL programming contest.  It's a great tool for producing data dumps, and it's now included in the official GnuCOBOL distributions.

For now though, I'll keep using my good ol' "COBDUMP" routine.  It's been my travelling companion from COBOL job to COBOL job since 1971.  Here it is, all tuned up for GnuCOBOL, with new tires and a fresh coat of paint.

In addition to general GnuCOBOL concepts, this program provides a useful demonstration of the following:
@itemize @bullet
@item
Coding a GnuCOBOL subroutine

@item
Using @code{USAGE POINTER} data items

@item
Using the @code{ANY LENGTH} data item attribute

@item
Coding for an @code{OPTIONAL} subprogram argument

@item
Using the @register{NUMBER-OF-CALL-PARAMETERS}

@item
Using the @subpgm{C$PRINTABLE}
@end itemize

The program source and cross-reference listing, produced using the GnuCOBOL Interactive Compiler front-end (GCic.cbl, one of the sample programs included here), begins on the next page.
@page
@include LISTING-COBDUMP.texi
@comment *********************************************************************
@comment ** 3. Colors                                                       **
@comment *********************************************************************
@newchapter{Colors}
Colors is a handy little GnuCOBOL utility program that will produce a screen showing all possible combinations of:
@itemize @bullet
@item
FOREGROUND-COLOR

@item
BACKGROUND-COLOR

@item
BLINKING (or absence of BLINKING)

@item
HIGHLIGHT, LOWLIGHT or absence of either (i.e. "Normal")

@item
REVERSE-VIDEO
@end itemize
@iftex

Here is a sample of the screen generated by this program:
@center @image{palette,5.5in}
@end iftex

The program source and cross-reference listing, produced using the cobxref, begins on the next page.
@page
@include LISTING-colors.texi
@comment *********************************************************************
@comment ** 4. DAY-FROM-DATE                                                **
@comment *********************************************************************
@newchapter{DAY-FROM-DATE}
DAY-FROM-DATE is a user-defined function that accepts a single numeric @code{USAGE DISPLAY} argument -- either a 7-digit Julian date in the form @i{yyyyddd} or an 8-digit Gregorian date in the form @i{yyyymmdd}.  This argument may be supplied either as a PIC 9(n) USAGE DISPLAY data item (n=7 or 8) or as a 7- or 8-digit numeric literal.

The subroutine will determine if the supplied date is a valid date in the year range 0000 through 9999 and what day of the week that date fell on.

The value returned will be zero if the date argument was invalid or an integer in the range 1-7, representing Sunday through Saturday.

In addition to general GnuCOBOL concepts, this program provides a useful demonstration of the following:
@itemize @bullet
@item
Coding a GnuCOBOL user-defined function

@item
Using the @code{ANY LENGTH} data item attribute

@item
Using the @code{RETURNING} option in a subprogram

@item
Using the @intrinsic{DATE-OF-INTEGER}

@item
Using the @subpgm{C$PARAMSIZE}
@end itemize

The program source and cross-reference listing, produced using the GnuCOBOL Interactive Compiler front-end (GCic.cbl, one of the sample programs included here), begins on the next page.
@page
@include LISTING-DAY-FROM-DATE.texi
@comment *********************************************************************
@comment ** 5. GCic                                                         **
@comment *********************************************************************
@newchapter{GCic}
This is MUCH more than a mere demonstration program -- it's also a very practical utility!  The "GCic" (GnuCOBOL Interactive Compiler) is a TUI (Textual User Interface) program that may be used as a full-screen interface to the "cobc" compiler.  In addition, GCic can produce neat, concise and useful cross-reference listings of GnuCOBOL programs, showing not only where user-defined names and built-in registers and intrinsic functions are referenced, but also where user-defined data items ARE MODIFIED by program code!

The program is well documented (IMHO) and you should find it fairly easy to follow.  The GCic.cbl program was written to work with a native Windows or Windows/MinGW build of GnuCOBOL as well as a Windows/Cygwin, UNIX or OS X build.

Source listings generated by GCic will show the original source code of your programs, with all indentation and comments preserved.  Additionally, any COPYed code will be included in the listing immediately (in compressed form) following the COPY statement that triggered its inclusion into your program.

Cross-reference listings will show all user-defined data items and procedures as well as intrinsic function and special register references.  In addition to showing the line numbers at which items were defined and referenced, those references that MODIFY the contents of the data item will have an asterisk appended to them.

In addition to general GnuCOBOL concepts, this program provides a useful demonstration of the following:
@itemize @bullet
@item
Creating a GnuCOBOL compilation unit that consists of multiple programs

@item
Using CDF conditional compilation facilities

@item
Using the @code{SCREEN SECTION} and associated @code{ACCEPT} and @code{DISPLAY} statements

@item
Using @code{DECLARATIVES} to trap file I/O errors

@item
Using @code{FILE-STATUS}

@item
Using the @code{REPLACING} clause on a CDF @code{COPY} statement

@item
Using the following statements:
@itemize o
@item
@statement{ACCEPT FROM COMMAND-LINE}

@item
@statement{ACCEPT FROM DATE/TIME}

@item
@statement{ACCEPT FROM ENVIRONMENT}

@item
@statement{EXIT PERFORM}

@item
@statement{EXIT SECTION}

@item
@statement{INSPECT}

@item
@statement{PERFORM FOREVER}

@item
@statement{SEARCH ALL}

@item
@statement{SET ENVIRONMENT}

@item
@statement{SORT}

@item
@statement{STRING}

@item
@statement{UNSTRING}
@end itemize

@item Using the following built-in subroutines:
@itemize o
@item
@subpgm{C$JUSTIFY}

@item
@subpgm{C$SLEEP}

@item
@subpgm{CBL_CHANGE_DIR}

@item
@subpgm{CBL_CHECK_FILE_EXIST}

@item
@subpgm{CBL_DELETE_FILE}

@item
@subpgm{SYSTEM}
@end itemize

@item Using the following intrinsic functions:
@itemize o
@item
@intrinsic{CONCATENATE}

@item
@intrinsic{LENGTH}

@item
@intrinsic{LOWER-CASE}

@item
@intrinsic{NUMVAL}

@item
@intrinsic{TRIM}

@item
@intrinsic{UPPER-CASE}
@end itemize

@item Using the @register{COB-CRT-STATUS,Special Registers}
@item Programmatically producing a report destined for either portrait or landscape printing
@end itemize
@iftex
@page

Here is a sample of the screen generated by this program:
@center @image{tui,6in,3.8in}
@end iftex

The program source and cross-reference listing, generated by cobxref, begins on the next page.
@page

@comment @include LISTING-GCic.texi
@include gcic.texi

@comment *********************************************************************
@comment ** 6. STREAMIO                                                     **
@comment *********************************************************************
@newchapter{STREAMIO}
STREAMIO is a utility I created to assist with handling stream I/O functions.  I've used it to construct a number of useful little command-line utilities.

Usage of this subroutine is completely documented in the program comments.  The program COPY's a copybook named STREAMIOcb, the format of which is described in the program comments.

Both STREAMIO.cbl and STREAMIOcb.cpy are included in the "samples" directory of any pre-built distributions of GnuCOBOL that I have created.

In addition to general GnuCOBOL concepts, this program provides a useful demonstration of the following:
@itemize @bullet
@item
Coding a GnuCOBOL subroutine

@item
Using the @code{REPLACING} clause on a CDF @statement{COPY}

@item
Using hexadecimal alphanumeric literals

@item
Using the following statements:
@itemize o
@item
@statement{ACCEPT FROM ENVIRONMENT}

@item
@statement{INSPECT}

@item
@statement{STRING}
@end itemize

@item Using the following built-in subroutines:
@itemize o
@item
@subpgm{C$PARAMSIZE}

@item
@subpgm{CBL_CLOSE_FILE}

@item
@subpgm{CBL_DELETE_FILE}

@item
@subpgm{CBL_EXIT_PROC}

@item
@subpgm{CBL_OPEN_FILE}

@item
@subpgm{CBL_READ_FILE}

@item
@subpgm{CBL_WRITE_FILE}
@end itemize

@item Using the following intrinsic functions:
@itemize o
@item
@intrinsic{RANDOM}

@item
@intrinsic{TRIM}
@end itemize
@end itemize
@page

First, here is the STREAMIOcb.cpy copybook:
@include LISTING-STREAMIOcb.texi

The program source and cross-reference listing, produced using the GnuCOBOL Interactive Compiler front-end (GCic.cbl, one of the sample programs included here), begins on the next page.
@page
@include LISTING-STREAMIO.texi
@page
@newchapter{GNU Free Documentation License}
@include fdl.texi
@bye
