Use a text editor, such as vi or emacs, to create and revise your source files. For instance, to edit the file prog1.cob using the vi editor, type:

% vi prog1.cob

Figure 1.1, “Commands for Developing VSI COBOL Programs on UNIX” shows the basic steps in VSI COBOL program development on UNIX systems.

When naming a source file, choose one of the four file name extensions that the cobol compiler recognizes as COBOL file suffixes. These suffixes are:

Table 1.1, “Other File Name Suffixes ” shows other file name suffixes.

.c

.s

.o

.a

.so

% cobol prog1.cob

The cobol command automatically passes a standard default list of UNIX and VSI COBOL libraries to the ld linker. If all external routines used by a program reside in these standard libraries, additional libraries or object files are not specified on the cobol command line.

% a.out

If the executable image is not in your current directory path, specify the directory path in addition to the file name.

The COPY Statement and Libraries

As you write a program, you can use the COPY statement in your source program to include text from another file. With the COPY statement, separate programs can share common source text kept in libraries, reducing development and testing time as well as storage. The VSI COBOL Reference Manual explains how to use the COPY statement.

Special Considerations for Routines Named “main”

If you have a program or routine named “main,” declared either in a VSI COBOL or other module, your application may not work correctly. The VSI COBOL library contains a routine named “main,” which initializes the run-time environment for the CALL by data name statements, extended ACCEPT and DISPLAY statements, and some error handling. When your application also declares a “main,” your routine preempts the VSI COBOL routine, and the run-time initialization is not performed.

VSI recommends that you not name a VSI COBOL program “main.”

      void cob_init (       /* init the RTL */
        int argc,           /* argument count */
        char **argv,        /* arguments */
        char **envp         /* environment variable pointers */ )

To compile your program, use the cobol command.

The COBOL Command Driver

The cobol command invokes a compiler driver that is the actual user interface to the VSI COBOL compiler. It accepts a list of command flags and file names and causes one or more processors (compiler, assembler, or linker) to process each file.

After the VSI COBOL compiler processes the appropriate files to create one or more object files, the compiler driver passes a list of files, certain flags, and other information to the cc compiler. After the cc compiler (the default C compiler on your system) processes relevant files and information, it passes certain information (such as .o object files) to the ld linker. The cobol command executes each processor; if any processor returns other than normal status, further processing is discontinued and the VSI COBOL compiler displays a message identifying the processor (and its returned status, in hexadecimal) before terminating its own execution.

cobol [-flags [options]]... filename[.suffix][filename[.suffix]]... [-flags [options]]...

% cobol -v test.cob pas.o

% cobol -rsv foreign_extensions -flagger high_fips -warn information zeroes.cob

% cobol -rsv for -flagger high -warn info zeroes.cob

% man cobol

-align [padding]

-ansi

-arch

-arch generic

-arithmetic native

-arithmetic native

-arithmetic standard

-arithmetic native

-C

-c

-call_shared

-check all

-check [no]bounds

-check nobounds

-check [no]decimal

-check nodecimal

-check [no]perform

-check noperform

-check none

-conditionals [selector]

-convert [no]leading_blanks

-convert noleading_blanks

-copy

-copy_list

-cord

-cross_reference

-cross_reference alphabetical

-cross_reference declared

-D num 

-display_formatted

-feedback file 

-fips 74

-flagger [option]

-granularity byte

-granularity long

-granularity quad

-granularity quad

-g0

-g1

-g2

-g

-g3

-include

-K

-L

-Ldir

-list

-lstring

-mach

-machine_code

-map

-map alphabetical

-map declared

-math_intermediate cit3

-math_intermediate cit4

-math_intermediate float

-math_intermediate float

-names as_is

-names lower

-names lowercase

-names upper

-names uppercase

-names lowercase

-nationality japan

-nationality us

-nationality us

-nolocking

-noobject

-non_shared

-call_shared

-nowarn

-O0

-O1

-O2

-O3

-O4

-O

-o output

-p0

-p1

-p

-relax_key_checking

-rkc

-rsv [no]200x

-rsv no200x

-rsv [no]foreign_extensions

-rsv noforeign_extensions

-rsv [no]xopen

-rsv xopen

-seq

-sequence_check

-shared

-call_shared

-show code

-show copy

-show xref

-std

-std 85

-std [no]mia

-std nomia

-std [no]syntax

-std nosyntax

-std [no]v3

-std nov3

-std [no]xopen

-std xopen

-T num

-taso

-tps

-trunc

-tune

-tune generic

% cobol -o calc mainprog.cob array_calc.cob calc_aver.cob

% cobol -c array_calc.cob
% cobol -c calc_aver.cob
% cobol -o calc mainprog.cob array_calc.o calc_aver.o

% calc

% cat proga1.cob proga2.cob proga3.cob > com1.cob
% cat progb1.cob progb2.cob > com2.cob
% cobol -c com1.cob com2.cob

$ COBOL proga1+proga2+proga3,progb1+progb2

% cobol -g -o calc_debug  mainprog.cob array_calc.cob calc_aver.cob

% ladebug calc_debug

% cobol -o prog1.out test1.cob

cobol: severity: filename, line n, message-text
[text-in-error]
--------^

cobol: Severe: disp.cob, line 7: Missing period is assumed
        05 VAR-1 PIC X.
--------^

Once your program has compiled successfully, the system passes the resulting object file (which has the suffix .o by default) to the linker to create an executable image file. By default, the executable image file has the name a.out. (To change this default, specify -o filename on the cobol command line.) This file can be run on the UNIX system.

The linker produces an executable program image with a default name of a.out.

When you enter a cobol command, the ld linker is invoked automatically unless a compilation error occurs or you specify the -c flag on the command line.

% cobol -c ex.cob
% nm -o ex.o | grep U

% cobol  -O3 -c octagon.cob

% ld -shared -no_archive octagon.o \
     -lcob -lcurses -lFutil -lots2 -lots -lisam -lsort -lexc -lmld -lm

% cobol -call_shared test.cob -lX rest.o

% cobol -call_shared test.cob rest.o -lX

ld: message-text

% myprog.out

In addition to normal IO accesses, your VSI COBOL programs can read command-line arguments and access (read and write) environment variables.

% myprog 1028 powers.dat

% myprog2 "all of this is argument 1" argument2

  identification division.
 PROGRAM-ID. MYPROG.
 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
 SPECIAL-NAMES.
     SYSERR              IS STANDARD-ERROR
     ENVIRONMENT-NAME    IS NAME-OF-ENVIRONMENT-VARIABLE
     ENVIRONMENT-VALUE   IS ENVIRONMENT-VARIABLE
     ARGUMENT-NUMBER     IS POS-OF-COMMAND-LINE-ARGUMENT
     ARGUMENT-VALUE      IS COMMAND-LINE-ARGUMENT.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01 howmany-records PIC 9(5).
 01 env-dir PIC x(50).
 01 file-name PIC x(50).
 01 file-spec PIC x(100).
 PROCEDURE DIVISION.
 BEGIN.
   ACCEPT howmany-records FROM COMMAND-LINE-ARGUMENT
     ON EXCEPTION
       DISPLAY "No arguments specified"
         UPON STANDARD-ERROR
       END-DISPLAY
       STOP RUN
   END-ACCEPT.
   DISPLAY "COBOLPATH" UPON NAME-OF-ENVIRONMENT-VARIABLE.
   ACCEPT env-dir FROM ENVIRONMENT-VARIABLE
     ON EXCEPTION
       DISPLAY "Environment variable COBOLPATH is not set"
         UPON STANDARD-ERROR
       END-DISPLAY
     NOT ON EXCEPTION
       ACCEPT file-name FROM COMMAND-LINE-ARGUMENT
         ON EXCEPTION
           DISPLAY
           "Attempt to read beyond end of command line"
             UPON STANDARD-ERROR
           END-DISPLAY
         NOT ON EXCEPTION
           STRING env-dir "/" file-name delimited by " " into file-spec
           DISPLAY "Would have read " howmany-records " records from " file-spec
       END-ACCEPT
   END-ACCEPT.

% setenv COBOLPATH /usr/files

% cobol -o myprog myprog.cob
% myprog 1028 powers.dat

This manual primarily addresses the program development activities associated with development and testing phases. For information about topics usually considered during application design, specification, and maintenance, refer to your operating system documentation, appropriate reference pages, or appropriate commercially published documentation.

In most instances, use the cobol command to invoke both the VSI COBOL compiler and the ld linker. To link one or more object files created by the VSI COBOL compiler, you should use the cobol command instead of the ld command, because the cobol command automatically references the appropriate VSI COBOL Run-Time Libraries when it invokes ld. If the executable image is not in your current working directory, specify the directory path in addition to the file name.

Compilation does the following for you:

You use the cobol command to compile and link your program. The cobol command invokes the VSI COBOL compiler driver that is the actual user interface to the VSI COBOL compiler. The compiler driver can accept command options and multiple file names, and normally causes the compiler and linker to process each file. A variety of qualifiers to the compile command are available to specify optional processing and to specify the names of output files.

After the VSI COBOL compiler processes the source files to create one or more object files, the compiler driver passes a list of object files and other information to the linker.

To create and modify an VSI COBOL program, you must invoke a text editor. The default editor for OpenVMS is the Text Processing Utility (TPU). Other editors, such as EDT or the Language-Sensitive Editor (LSE), may be available on your system. Check with your system administrator and refer to the OpenVMS EDT Reference Manual (this manual has been archived but is available on the OpenVMS Documentation CD-ROM) for more information about EDT or the Guide to Language-Sensitive Editor for additional information about LSE.

Figure 1.2, “DCL Commands for Developing Programs ” shows the basic steps in VSI COBOL program development.

Use the text editor of your preference to create and revise your source files. For example, the following command line invokes the TPU editor and creates the source file PROG_1.COB:

$ EDIT PROG_1.COB

The file type .COB is used to indicate that you are creating an VSI COBOL program. COB is the default file type for all VSI COBOL programs.

The COPY Statement, Dictionaries, and Libraries

Including the COPY statement in your program allows separate programs to share common source text, reducing development and testing time as well as storage requirements. You can use the COPY statement to access modules in libraries. The COPY statement causes the compiler to read the file or module specified during the compilation of a program. When the compiler reaches the end of the included text, it resumes reading from the previous input file.

By using the /INCLUDE qualifier on the COBOL command line, you can set up a search list for files specified by the COPY statement. For more information, refer to the VSI COBOL Reference Manual.

You can use the COPY FROM DICTIONARY statement in your program to access a data dictionary and copy Oracle CDD/Repository record descriptions into your program as COBOL record descriptions. Before you can copy record descriptions from Oracle CDD/Repository, you must create the record descriptions using the Common Data Dictionary Language (CDDL) or Common Dictionary Operator (CDO).

For more information about using Oracle CDD/Repository and creating and maintaining text libraries, refer to the VSI COBOL Reference Manual and Using Oracle CDD/Repository on OpenVMS Systems.

To compile your program, use the COBOL command. The VSI COBOL compiler performs these primary functions:

The compiler outputs an object module that provides the following information:

To invoke the VSI COBOL compiler, use the COBOL command (explained in Section 1.2.2.1, “ Format of the COBOL Command on OpenVMS”). You can specify qualifiers with the COBOL command. The following sections discuss the COBOL command and its qualifiers.

COBOL [/qualifier] ... {file-spec [/qualifier] ...} ...

$ COBOL/LIST PROG_1, PROG_2/NOLIST, PROG_3

$ COBOL PROG_1 + PROG_2/LIST + PROG_3

$ COBOL/DEBUG myprog
$ LINK/DEBUG myprog
$ RUN/DEBUG myprog

..........................^
%COBOL-s-ident, message-text
At line number n in name

   12          PROCEDURE DIVISION.
   13          P-NAME
   14              MOVE ABC TO XYZ.
   ................^
%COBOL-E-NODOT, Missing period is assumed


   14              MOVE ABC TO XYZ.
   ............................^
%COBOL-F-UNDEFSYM, Undefined name

$  COBOL/LIST PROG_1.COB

$ HELP COBOL

After you compile an VSI COBOL source program or module, use the LINK command to combine your object modules into one executable image that the OpenVMS system can execute. A source program or module cannot run until it is linked.

When you execute the LINK command, the OpenVMS Linker performs the following functions:

The LINK command produces an executable image by default. However, you can specify qualifiers and qualifier options with the LINK command to obtain shareable images and system images.

See Table 1.5, “Commonly Used LINK Qualifiers” for a list of commonly used LINK command qualifiers. For a complete list and for more information about the LINK qualifiers, invoke the online help facility for the LINK command at the system prompt.

For a complete discussion of linker capabilities and for detailed descriptions of LINK qualifiers and qualifier options, refer to the VSI OpenVMS Linker Utility Manual.

LINK[/qualifier] ... {file-spec[/qualifier] ...} ...

$ LINK MAINPROG, SUBPROG1, SUBPROG2

$ LINK/EXE=name SYS$SHARE:STARLET/INCL=COB_NAME_START,your_modules...

$ LINK GARDEN, VEGETABLES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION)

$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY

$ DEFINE LNK$LIBRARY DEFLIB

$ LINK METRIC,DEFLIB/LIBRARY,APPLIC

$ LINK METRIC,APPLIC,DEFLIB/LIBRARY

* CALLER.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. CALLER.
******************************************************************
* This program calls a subprogram installed as a shareable image.*
******************************************************************
PROCEDURE DIVISION.
0.
     CALL "SUBSHR1"
         ON EXCEPTION
             DISPLAY "First CALL failed. Program aborted."
     END-CALL.
     STOP RUN.
END PROGRAM CALLER.

* SUBSHR1.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBSHR1.

******************************************************************
* This subprogram is linked as a shareable image. When it is called,*
* it calls another subprogram installed as a shareable image.       *
******************************************************************
PROCEDURE DIVISION.
0.
     DISPLAY "Call to SUBSHR1 successful. Calling SUBSHR2.".
     CALL "SUBSHR2"
         ON EXCEPTION
             DISPLAY "Second call failed. Control returned to CALLER."
     END-CALL.
END PROGRAM SUBSHR1.


* SUBSHR2.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBSHR2.
****************************************************************
* This subprogram is linked as a shareable image and is called by *
* another shareable image.                                     *
****************************************************************
PROCEDURE DIVISION.
0.
     DISPLAY "Call to SUBSHR2 successful!".
END PROGRAM SUBSHR2.

$! Create the main program and subprograms.
$! In this example CALLER.COB is the main program.
$! SUBSHR1.COB and SUBSHR2.COB are the subprograms to be installed
$! as shareable images.
$!
$! Compile the main program and subprograms.
$!
$  COBOL CALLER.COB
$  COBOL SUBSHR1.COB
$  COBOL SUBSHR2.COB
$!
$! Create an options file containing all the universal symbols
$! (entry points and other data symbols) for the subprograms.
$!
$  COPY SYS$INPUT OPTIONS1.OPT
$  DECK
   SYMBOL_VECTOR=(SUBSHR1=PROCEDURE,SUBSHR2=PROCEDURE)
$  EOD
$!
$! Link the subprograms using the /SHARE qualifier to the
$! shareable library and the options file.  For more information
$! on options files, refer to the VSI OpenVMS Linker Utility Manual.
$!
$  LINK/SHARE=MYSHRLIB SUBSHR1,SUBSHR2,OPTIONS1/OPT
$!
$! Assign a logical name for the shareable images.
$!
$  ASSIGN DEVICE:[DIRECTORY]MYSHRLIB.EXE MYSHRLIB
$!
$! Create a second options file to map the main program to the
$! shareable image library.
$!
$  COPY SYS$INPUT OPTIONS2.OPT
$  DECK
   MYSHRLIB/SHAREABLE
$  EOD
$!
$! Link the main program with the shareable image subprograms
$! through the options file.
$!
$  LINK CALLER,OPTIONS2/OPT
$!
$! Now you can run the main program.

After you compile and link your program, use the RUN command to execute it. In its simplest form the RUN command has the following format:

$ RUN myprog

In the preceding example MYPROG.EXE is the file specification of the image you want to run. If you omit the file type from the file specification, the system automatically provides a default value. The default file type is .EXE. If you omit a path specification, the system will expect MYPROG.EXE to be in the current directory.

$ MYPROG :== "$device:[dir]MYPROG.EXE"

$ MYPROG 1028 POWERS.DAT

$ myprog2 "all of this is argument 1" argument2

IDENTIFICATION DIVISION.
PROGRAM-ID. EXAMPLE.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SYSERR              IS STANDARD-ERROR
    ENVIRONMENT-NAME    IS NAME-OF-LOGICAL
    ENVIRONMENT-VALUE   IS LOGICAL-VALUE
    ARGUMENT-NUMBER     IS POS-OF-COMMAND-LINE-ARGUMENT
    ARGUMENT-VALUE      IS COMMAND-LINE-ARGUMENT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 howmany-records PIC 9(5).
01 env-dir PIC x(50).
01 file-name PIC x(50).
01 file-spec PIC x(100).
PROCEDURE DIVISION.
BEGIN.
    ACCEPT howmany-records FROM COMMAND-LINE-ARGUMENT
      ON EXCEPTION
        DISPLAY "No arguments specified"
          UPON STANDARD-ERROR
        STOP RUN
    END-ACCEPT.

    DISPLAY "COBOLPATH" UPON NAME-OF-LOGICAL.
    ACCEPT env-dir FROM LOGICAL-VALUE
      ON EXCEPTION
        DISPLAY "Logical COBOLPATH is not set"
          UPON STANDARD-ERROR
        END-DISPLAY
                   NOT ON EXCEPTION
        ACCEPT file-name FROM COMMAND-LINE-ARGUMENT
          ON EXCEPTION
            DISPLAY
            "Attempt to read beyond end of command line"
              UPON STANDARD-ERROR
            END-DISPLAY
          NOT ON EXCEPTION
            STRING env-dir file-name delimited by " " into file-spec
            DISPLAY "Would have read " howmany-records " records from " file-spec
        END-ACCEPT
    END-ACCEPT.

$ define COBOLPATH MYDEV:[MYDIR]

$ MYPROG 1028 powers.dat

RUN [/[NO]DEBUG] file-spec

$ RUN /DEBUG MYPROG

$ RUN MYPROG/NODEBUG

%COB-s-ident, message-text

%COB-E-DIVBY-ZER, divide by zero; execution continues

The Alpha and I64 architecture is a RISC (reduced instruction set computer) architecture. Many other processor architectures are CISC (complex instruction set computer) architectures. The main distinguishing characteristic of a RISC machine is that it has few instructions and each instruction does a small amount of work. A CISC machine generally has many instructions, most of which perform many complicated operations in one step.

By reducing the amount of work that is done in each instruction (and by reducing the number of instructions), the complexity of the hardware is reduced. These hardware changes, plus others, result in an increase in the number of instructions per second that can be completed. The result is much faster overall system performance.

A tradeoff of RISC systems is that compilers for these architectures generally must do a great deal more work than a corresponding compiler for a CISC architecture. For example, the compiler must compute the best way to use all of the functional units of the processor, and it must determine how to make the best use of registers and on-chip data cache because reads and writes to main memory are generally slow compared to the speed of the processor.

On the other hand, the VSI COBOL compiler was developed for the Alpha and I64 architectures. It is a globally optimizing compiler based on the most recent compiler technology. It does many optimizations including Peephole, loop unrolling, and instruction pipelining. Also, the compiler uses mathematical graph theory to construct an internal representation of the entire COBOL program, and it repeatedly traverses this structure at compile time, to produce the most efficient machine code for the program. This results in very high performance code, to the benefit of your users at run time. Although the VSI COBOL compiler on OpenVMS Alpha and I64 requires more resources than some other compilers to do this additional work at compile time, this cost is offset by better performance during the many run times that follow.

The recommendations that follow were determined by compiling one set of very large VSI COBOL modules on OpenVMS Alpha and I64. While your results may vary, the principles are generally applicable. For more detailed information on OpenVMS Alpha and I64 tuning, refer to the VSI OpenVMS System Manager's Manual.

Note that many tuning exercises are more beneficial if you work with a relatively quiet system, submit batch jobs, and retain the log files for later analysis.

MIN_VIRTUALPAGECNT = 400000

You need to choose a reference format before you set out to write a VSI COBOL program, and you must be aware of the format at compile time. The VSI COBOL compiler accepts source code written in either terminal or ANSI reference format. You cannot mix reference formats in the same source file.

On OpenVMS, when copying text from Oracle CDD/Repository, the VSI COBOL compiler translates the record descriptions into the reference format of the source program.

01  PAY-RECORD.
    03  P-NUMBER       PIC X(5).
    03  P-WEEKLY-AMT   PIC S9(5)V99  COMP-3.
    03  P-YEARLY-AMT   PIC S9(5)V99  COMP-3.
    03  P-MONTHLY-AMT  PIC S9(5)V99  COMP-3.
        .
        .
        .
PROCEDURE DIVISION.
ADD-TOTALS.
    ADD P-MONTHLY-AMT TO TOTAL-MONTHLY-AMT.
        .
        .
        .

You can minimize record field position errors by writing your file and record descriptions in a library file and then using the COPY statement in your programs. On OpenVMS systems, you can also use the COPY FROM DICTIONARY statement.

Choosing your test data carefully can minimize faulty data problems. For instance, rather than using actual or ideal data, use test files that include data extremes.

Determining when a program produces incorrect results can often help your debugging effort. You can do this by maintaining audit counts (such as total master in = nnn, total transactions in = nnn, total deletions = nnn, total master out = nnn) and displaying the audit counts when the program ends. Using conditional compilation lines (see Section 1.2.2.7, “Compiling Programs with Conditional Compilation”) in your program can also help you to debug it.

An input/output error is a condition that causes an I/O statement to fail. These I/O errors are detected at run time by the I/O system. Each time an I/O operation occurs, the I/O system generates a two-character file status value. One way to determine the nature of an I/O error is to check a file's I/O status by using file status data items. (Refer to the VSI COBOL Reference Manual for a list of file status values.) See Chapter 7: Handling Input/Output Exception Conditions for additional information about I/O exception condition handling.

FD  INDEXED-MASTER
    ACCESS MODE IS DYNAMIC
    FILE STATUS IS MASTER-STATUS
    RECORD KEY IN IND-KEY.
  .
  .
  .
WORKING-STORAGE SECTION.
01  MASTER-STATUS      PIC XX  VALUE SPACES.
  .
  .
  .
PROCEDURE DIVISION.
  .
  .
  .
050-READ-MASTER.
    READ INDEXED-MASTER
      INVALID KEY PERFORM 100-CHECK-STATUS
      GO TO 200-INVALID-READ.
      .
      .
      .
100-CHECK-STATUS.
    IF MASTER-STATUS = "23"
       DISPLAY "RECORD NOT IN FILE".
    IF MASTER-STATUS = "24"
       DISPLAY "BOUNDARY VIOLATION OR RELATIVE RECORD
       NUMBER TOO LARGE".
      .
      .
      .

If your program contains a Declarative USE procedure for a file and an I/O operation for that file fails, the I/O system performs the USE procedure, but does not display an error message.

A Declarative USE procedure can sometimes avoid program termination. For example, File Status 91 indicates that the file is locked by another program; rather than terminate your program, you can perform other procedures and then try reopening the file. If program continuation is not desirable, the Declarative USE procedure can perform housekeeping functions, such as saving data or displaying program-generated diagnostic messages.

If you specify an INVALID KEY phrase for a file and the I/O operation causes an INVALID KEY condition, the I/O system performs the associated imperative statement and no other file processing for the current statement. The Declarative USE procedure (if any) is not performed. The INVALID KEY phrase processes I/O errors due to invalid key conditions only.

If you do not specify an INVALID KEY phrase but declare a Declarative USE procedure for the file, the I/O system performs the Declarative USE procedure and returns control to the program.

cobrtl: severe: file AFILE.DAT not found

In this case, program run ends because you have not handled the error with a Declarative Use procedure.

I/O errors are detected by the I/O system, which (for OpenVMS systems) consists of Record Management Services (RMS) and the Run-Time Library (RTL). You can use the RMS special registers, which contain the primary and secondary RMS completion codes of an I/O operation, to detect errors. The RMS special registers are as follows:

RMS-STS

RMS-STV

RMS-FILENAME

RMS-CURRENT-STS

RMS-CURRENT-STV

RMS-CURRENT-FILENAME

Refer to the VSI COBOL Reference Manual and the VSI OpenVMS Record Management Services Reference Manual for more information about RMS special registers.

Examples Example 1.5, “Using RMS Special Registers to Detect Errors (OpenVMS)” and Example 1.6, “Using RMS-CURRENT Special Registers to Detect Errors (OpenVMS)” show how to use RMS special registers to detect errors.

IDENTIFICATION DIVISION.
PROGRAM-ID. RMSSPECREGS.
*
* This program demonstrates the use of RMS special registers to
* implement a different recovery for each of several errors with RMS files.
*
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT OPTIONAL EMP-FILE ASSIGN "SYS$DISK:ART.DAT".
    SELECT REPORT-FILE       ASSIGN "SYS$OUTPUT".
DATA DIVISION.
FILE SECTION.
FD  EMP-FILE VALUE OF ID IS VAL-OF-ID.
01  EMP-RECORD.
    02 EMP-ID     PIC 9(7).
    02 EMP-NAME    PIC X(15).
    02 EMP-ADDRESS PIC X(30).
FD  REPORT-FILE     REPORT IS RPT.
WORKING-STORAGE SECTION.
01  VAL-OF-ID     PIC X(20).
01  RMS$_EOF     PIC S9(9) COMP VALUE EXTERNAL RMS$_EOF.
01  SS$_BADFILENAME PIC S9(9) COMP VALUE EXTERNAL SS$_BADFILENAME.
01  RMS$_FNF     PIC S9(9) COMP VALUE EXTERNAL RMS$_FNF.
01  RMS$_DNF     PIC S9(9) COMP VALUE EXTERNAL RMS$_DNF.
01  RMS$_DEV     PIC S9(9) COMP VALUE EXTERNAL RMS$_DEV.
01  D-DATE     PIC 9(6).
01  EOF-SW     PIC X.
    88 E-O-F  VALUE "E".
    88 NOT-E-O-F VALUE "N".
01  VAL-OP-SW     PIC X.
    88 VALID-OP VALUE "V".
    88 OP-FAILED VALUE "F".
01  OP      PIC X.
    88 OP-OPEN  VALUE "O".
    88 OP-CLOSE VALUE "C".
    88 OP-READ  VALUE "R".
REPORT SECTION.
RD  RPT PAGE 26 LINES HEADING 1 FIRST DETAIL 5.
01  TYPE IS PAGE HEADING.
    02 LINE IS PLUS 1.
 03  COLUMN 1 PIC X(16) VALUE "Emplyee File on".
 03  COLUMN 18 PIC 99/99/99 SOURCE D-DATE.
    02 LINE IS PLUS 2.
 03  COLUMN 2 PIC X(5) VALUE "Empid".
 03  COLUMN 22 PIC X(4) VALUE "Name".
 03  COLUMN 43 PIC X(7) VALUE "Address".
 03  COLUMN 60 PIC X(4) VALUE "Page".
 03  COLUMN 70 PIC ZZ9  SOURCE PAGE-COUNTER.
01  REPORT-LINE TYPE IS DETAIL.
    02 LINE IS PLUS 1.
 03  COLUMN  IS 1    PIC 9(7) SOURCE EMP-ID.
 03  COLUMN  IS 20   PIC X(15) SOURCE IS EMP-NAME.
 03  COLUMN  IS 42   PIC X(30) SOURCE IS EMP-ADDRESS.
PROCEDURE DIVISION.
DECLARATIVES.
USE-SECT SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON EMP-FILE.
CHECK-RMS-SPECIAL-REGISTERS.
    SET OP-FAILED TO TRUE.
    EVALUATE RMS-STS OF EMP-FILE TRUE
 WHEN (RMS$_EOF)   OP-READ
     SET VALID-OP TO TRUE
     SET E-O-F TO TRUE
 WHEN (SS$_BADFILENAME)  OP-OPEN
 WHEN (RMS$_FNF)   OP-OPEN
 WHEN (RMS$_DNF)   OP-OPEN
 WHEN (RMS$_DEV)   OP-OPEN
     DISPLAY "File cannot be found or file spec is invalid"
     DISPLAY RMS-FILENAME OF EMP-FILE
     DISPLAY "Enter corrected file (control-Z to STOP RUN): "
      WITH NO ADVANCING
     ACCEPT VAL-OF-ID
  AT END STOP RUN
     END-ACCEPT
 WHEN ANY   OP-CLOSE
     CONTINUE
 WHEN ANY   RMS-STS OF EMP-FILE IS SUCCESS
     SET VALID-OP TO TRUE
 WHEN OTHER
     IF RMS-STV OF EMP-FILE NOT = ZERO
     THEN
  CALL "LIB$STOP" USING
      BY VALUE RMS-STS OF EMP-FILE
     END-IF
    END-EVALUATE.
END DECLARATIVES.
MAIN-PROG SECTION.
000-DRIVER.
    PERFORM 100-INITIALIZE.
    PERFORM WITH TEST AFTER UNTIL E-O-F
 GENERATE REPORT-LINE
 READ EMP-FILE
    END-PERFORM.
    PERFORM 200-CLEANUP.
    STOP RUN.
100-INITIALIZE.
    ACCEPT D-DATE FROM DATE.
    DISPLAY "Enter file spec of employee file: " WITH NO ADVANCING.
    ACCEPT VAL-OF-ID.
    PERFORM WITH TEST AFTER UNTIL VALID-OP
 SET VALID-OP TO TRUE
 SET OP-OPEN TO TRUE
 OPEN INPUT EMP-FILE
 IF OP-FAILED
 THEN
     SET OP-CLOSE TO TRUE
     CLOSE EMP-FILE
 END-IF
    END-PERFORM.
    OPEN OUTPUT REPORT-FILE.
    INITIATE RPT.
    SET NOT-E-O-F TO TRUE.
    SET OP-READ TO TRUE.
    READ EMP-FILE.
200-CLEANUP.
    TERMINATE RPT.
    SET OP-CLOSE TO TRUE.
    CLOSE EMP-FILE REPORT-FILE.
END PROGRAM RMSSPECREGS.

IDENTIFICATION DIVISION.
PROGRAM ID. RMS-CURRENT-SPEC-REGISTERS.
*
* This program demonstrates the use of RMS-CURRENT special registers
* to implement a single recovery for RMS file errors with multiple files.
*
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT FILE-1
        ASSIGN TO "SYS$DISK:ART_1.DAT".
SELECT FILE-2
        ASSIGN TO "SYS$DISK:ART_2.DAT".
SELECT FILE-3
        ASSIGN TO "SYS$DISK:ART_3.DAT".
DATA DIVISION.
FILE SECTION.
FD      FILE-1.
01      FILE-1-REC.
        02      F1-REC-FIELD    PIC 9(9).
FD      FILE-2.
01      FILE-2-REC.
        02      F2-REC-FIELD    PIC 9(9).
FD      FILE-3.
01      FILE-3-REC.
        02      F3-REC-FIELD    PIC 9(9).
PROCEDURE DIVISION.
DECLARATIVES.
USE-SECT SECTION.
        USE AFTER STANDARD EXCEPTION PROCEDURE ON INPUT.
CHECK-RMS-CURRENT-REGISTERS.
        DISPLAY "************** ERROR **************".
        DISPLAY "Error on file: " RMS-CURRENT-FILENAME.
        DISPLAY "Status Values:".
        DISPLAY "      RMS-STS = " RMS-CURRENT-STS WITH CONVERSION.
        DISPLAY "      RMS-STV = " RMS-CURRENT-STV WITH CONVERSION.
        DISPLAY "***********************************".
END DECLARATIVES.
MAIN-PROG SECTION.
MAIN-PARA.
        OPEN INPUT FILE-1.
        OPEN INPUT FILE-2.
        OPEN INPUT FILE-3.
        .
        .
        .
        CLOSE FILE-1.
        CLOSE FILE-2.
        CLOSE FILE-3.
        STOP RUN.
END-PROGRAM RMS-CURRENT-SPEC-REGISTERS.

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SWITCH 10 IS MY-SWITCH
      ON IS SWITCH-ON
      OFF IS SWITCH-OFF.
    .
    .
    .
PROCEDURE DIVISION.
000-SET-SWITCH.
    SET MY-SWITCH TO ON.
    IF SWITCH-ON
       THEN
    DISPLAY "Switch 10 is on".
    .
    .
    .

On OpenVMS systems, SET in COBOL will attempt to write a user mode logical name (COB$SWITCHES) to the first entry in the LNM$FILE_DEV chain. It will therefore fail if that logical name table denies WRITE access.

To change the status of internal switches during execution, turn them on or off from within your program. However, be aware that this information is not saved between runs of the program.

Refer to the VSI COBOL Reference Manual for more information about setting internal switches.

Switches that are set externally are handled differently on UNIX and OpenVMS, as described in this section.

Switches on UNIX

On UNIX systems, to set switches from outside the image, use the SETENV command to change the status of program switches, as follows:

% setenv COBOL_SWITCHES "switch-list"

To remove switch settings:

% unsetenv COBOL_SWITCHES

To check switch settings, enter this command:

% printenv COBOL_SWITCHES          Shows switch settings.

The switch-list can contain up to 16 switches separated by commas. To set a switch on, specify it in the switch-list. A switch is off (the default) if you do not specify it in the switch-list.

% setenv COBOL_SWITCHES "1,5,13"   Sets switches 1, 5, and 13 ON.

% setenv COBOL_SWITCHES "9,11,16"  Sets switches 9, 11, and 16 ON.

% setenv COBOL_SWITCHES " "        Sets all switches OFF

IDENTIFICATION DIVISION.
PROGRAM-ID. TSW.

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SWITCH 12 IS SW12 ON IS SW12-ON OFF IS SW12-OFF.

PROCEDURE DIVISION.
01-S.
    DISPLAY "**TEST SWITCHES**".
    IF SW12-ON
       DISPLAY "SWITCH 12 IS ON".
    IF SW12-OFF
       DISPLAY "SWITCH 12 IS OFF".

    DISPLAY "**END**".
    STOP RUN.
END PROGRAM TSW.

% setenv COBOL_SWITCHES 12
% tsw

**TEST SWITCHES**
SWITCH 12 IS ON
**END**

Switches on OpenVMS

$ DEFINE COB$SWITCHES "switch-list" 

The switch-list can contain up to 16 switches separated by commas. To set a switch ON, specify it in the switch-list. A switch is OFF (the default) if you do not specify it in the switch-list.

$ DEFINE COB$SWITCHES "1,5,13"   Sets switches 1, 5, and 13 ON.
$ DEFINE COB$SWITCHES "9,11,16"  Sets switches 9, 11, and 16 ON.
$ DEFINE COB$SWITCHES " "        Sets all switches OFF.

The order of evaluation for logical name assignments is image, process, group, system. System and group assignments (including VSI COBOL program switch settings) continue until they are changed or deassigned. Process assignments continue until they are changed, deassigned, or until the process ends. Image assignments end when they are changed or when the image ends.

$ SHOW LOGICAL COB$SWITCHES

$ DEASSIGN COB$SWITCHES

For information about these DCL commands, refer to the VSI OpenVMS DCL Dictionary.

IDENTIFICATION DIVISION.
PROGRAM-ID. TSW.

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SWITCH 12 IS SW12 ON IS SW12-ON OFF IS SW12-OFF.

PROCEDURE DIVISION.
01-S.
    DISPLAY "**TEST SWITCHES**".
    IF SW12-ON
       DISPLAY "SWITCH 12 IS ON".
    IF SW12-OFF
       DISPLAY "SWITCH 12 IS OFF".

    DISPLAY "**END**".
    STOP RUN.
END PROGRAM TSW.

$ DEFINE COB$SWITCHES 12
$ RUN TSW

**TEST SWITCHES**
SWITCH 12 IS ON
**END**

IF FIELD1 > FIELD2 ... 

If the relation condition is true, the program control takes the true path of the statement.

Comparison of two numeric operands is valid regardless of their USAGE clauses.

The length of the literal or arithmetic expression operands (in terms of the number of digits represented) is not significant. Zero is a unique value, regardless of the sign.

Unsigned numeric operands are assumed to be positive for comparison. The results of relation tests involving invalid (nonnumeric) data in a numeric item are undefined.

IF FIELD1 > 0 ...

IF FIELD1 POSITIVE ...

Both of these tests accomplish the same thing and always arrive at the same result. The sign test, however, shortens the statement and makes it more obvious that the sign is being tested.

Sign tests do not execute faster or slower than relation tests because the compiler substitutes the equivalent relation test for every correctly written sign test.

IF FIELD1 IS NUMERIC ...

If the item is numeric, the test condition is true, and program control takes the true path of the statement.

Both relation and sign tests determine only if an item's contents are within a certain range. Therefore, certain items in newly prepared data can pass both the relation and sign tests and still contain data preparation errors.

The NUMERIC class test checks alphanumeric or numeric DISPLAY or COMP-3 usage items for valid numeric digits. If the item being tested contains a sign (whether carried as an overpunched character or as a separate character), the test checks it for a valid sign value. If the character position carrying the sign contains an invalid sign value, the NUMERIC class test rejects the item, and program control takes the false path of the IF statement.

The ALPHABETIC class test check is not valid for an operand described as numeric.

The SET statement is typically in the called program, but the calling program may also SET the status of status-code-id. The SUCCESS class condition is true if status-code-id has been set to SUCCESS, otherwise it is false. The FAILURE class condition is true if status-code-id has been set to FAILURE, otherwise it is false. The results are unspecified if status-code is not set.

…
PROGRAM-ID.  MAIN-PROG.
…
O1   RETURN-STATUS      PIC S9(9) COMP.
…
    CALL "PROG-1" GIVING RETURN-STATUS.
    IF RETURN-STATUS IS FAILURE PERFORM FAILURE-ROUTINE.
…
PROGRAM-ID. PROG-1.
….
WORKING-STORAGE SECTION.
01  RETURN-STATUS     PIC S9(9) COMP.
PROCEDURE DIVISION GIVING RETURN-STATUS.
…
    IF NUM-1 = NUM-2
              SET RETURN-STATUS TO SUCCESS
    ELSE
              SET RETURN-STATUS TO FAILURE.
…
    EXIT PROGRAM.
END PROGRAM PROG-1.
END PROGRAM MAIN-PROG.

If both items of a MOVE statement are elementary items and the receiving item is numeric, it is an elementary numeric move. The sending item can be numeric, alphanumeric, or numeric-edited. The elementary numeric move converts the data format of the sending item to the data format of the receiving item.

The elementary numeric move accepts the figurative constant ZERO and considers it to be equivalent to the numeric literal 0. It treats alphanumeric sending items as unsigned integers of DISPLAY usage.

When the sending item is numeric-edited, de-editing is applied to establish the unedited numeric value, which may be signed; then the unedited numeric value is moved to the receiving field.

If necessary, the numeric move operation converts the sending item to the data format of the receiving item and aligns the sending item's decimal point on that of the receiving item. Then it moves the sending item's digits to the corresponding receiving item's digits.

If the sending item has more digit positions than the receiving item, the decimal point alignment operation truncates the value of the sending item, with resulting loss of digits.

The end truncated (high-order or low-order) depends upon the number of sending item digit positions that find matches on each side of the receiving item's decimal point. If the receiving item has fewer digit positions on both sides of the decimal point, the operation truncates both ends of the sending item. Thus, if an item described as PIC 999V999 is moved to an item described as PIC 99V99, it loses one digit from the left end and one from the right end.

01 AMOUNT1 PIC 99V99 VALUE ZEROS.
   .
   .
   .
   MOVE 123.321 TO AMOUNT1.
Before execution:
00^00 After execution:   23^32

01  TOTAL-AMT PIC 999V99 VALUE ZEROS.
    .
    .
    .
    MOVE 1 TO TOTAL-AMT.
Before execution:   000^00
After execution:    001^00

MOVE 001.00 TO TOTAL-AMT.
MOVE "1" TO TOTAL-AMT.

     Statement                 TOTAL-AMT After Execution
MOVE 00100 TO TOTAL-AMT                  100^00
MOVE "00100" TO TOTAL-AMT                100^00

Literals with leading or trailing zeros have no advantage in space or execution speed in VSI COBOL, and the zeros are often lost by decimal point alignment.

The MOVE statement's receiving item dictates how the sign will be moved. When the receiving item is a signed numeric item, the sign from the sending item is placed in it. If the sending item is unsigned, and the receiving item is signed, a positive sign is placed in the receiving item. If the sending item is signed and the receiving item is unsigned, the absolute value of the sending item is moved to the receiving item.

An elementary numeric move to a numeric-edited receiving item is considered an elementary numeric-edited move. The sending item of an elementary numeric-edited move can be numeric, numeric-edited, or alphanumeric. When the sending item is numeric-edited, de-editing is applied to establish the item's unedited numeric value, which may be signed; then the unedited numeric value is moved to the receiving field. Alphanumeric sending items in numeric-edited moves are considered unsigned DISPLAY usage integers.

For a complete description of these symbols, refer to the VSI COBOL Reference Manual.

The numeric-edited move operation first converts the sending item to DISPLAY usage and aligns both items on their decimal point locations. The sending item is truncated or zero-filled until it has the same number of digit positions on both sides of the decimal point as the receiving item. The operation then moves the sending item to the receiving item, following the VSI COBOL editing rules.

MOVE FLD-B TO TOTAL-AMT.

The currency symbol ($ or other currency sign) and the editing sign control symbols (+ and –) are the only floating symbols. To float a symbol, enter a string of two or more occurrences of that symbol, one for each character position over which you want the symbol to float.

Any item (other than a data item that is not subordinate to an OCCURS clause) of a MOVE statement can be subscripted, and the referenced item can be used to subscript another name in the same statement.

For additional information, see Section 3.6.4, “Subscripted Moves” in Chapter 3, Handling Nonnumeric Data.

VSI COBOL allows numeric items and literals with up to 31 decimal digits on Alpha and I64, and up to 18 decimal digits on VAX. (See Section 2.7.2, “Standard and Native Arithmetic (Alpha, I64)” for more specific information.) It is quite easy to construct arithmetic expressions that produce too many digits.

Most forms of the arithmetic statements perform their operations in temporary work locations, then move the results to the receiving items, aligning the decimal points and truncating or zero-filling the resultant values. The actual size of a temporary work item (also called an intermediate result item) varies for each statement; it is determined at compile time, based on the sizes of the operands used by the statement and the arithmetic operation being performed. Should the temporary work item exceed the maximum size, truncation occurs.

On Alpha and I64 systems, the maximum temporary work item size is 31 digits for standard arithmetic and for native CIT4 arithmetic, and is 38 digits for some operations using native float or native CIT3.

Programs should not arbitrarily specify sizes significantly larger than the values actually anticipated for the lifetime of the application. Although the generous limits in VSI COBOL are useful for many applications, specifying many more digits than needed is likely to add extra processing cycles and complexity that is wasteful.

VSI COBOL supports two modes of arithmetic, standard and native. Standard arithmetic is preferable for greater precision with large values and for compatibility with other standard implementations of COBOL. These considerations are sometimes overridden by the need for compatibility with earlier versions of VSI COBOL or for compatibility with VSI COBOL, in which case native arithmetic is the appropriate mode.

Native arithmetic has three submodes: FLOAT, CIT3, and CIT4. (CIT stands for COBOL Intermediate Temporary).

You can specify the arithmetic mode and submode with the two COBOL command-line qualifiers /ARITHMETIC (or -arithmetic) and /MATH_INTERMEDIATE (or -math_intermediate). The use of these qualifiers is described in this section.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. MUL31.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  XD PIC S9(31) VALUE 3.
 01  YD PIC S9(31) VALUE 258718314234781388692555698765.
 01  ZD PIC S9(31).
 PROCEDURE DIVISION.
 0.
     MULTIPLY XD BY YD GIVING ZD
         ON SIZE ERROR DISPLAY "Size error raised"
         NOT ON SIZE ERROR DISPLAY ZD WITH CONVERSION.

                                                    Intermediate maintains
             MATH   ZD                              the most significant
             -----  ------------------------------  ----------------------
             FLOAT  776154942704344283789821739008  53 bits
             CIT3   776154942704344164000000000000  18 digits
             CIT4   776154942704344166077667096295  32 digits

The -trunc flag (on UNIX) or the /[NO]TRUNCATE qualifier (on OpenVMS) specifies how the VSI COBOL compiler stores values in COMPUTATIONAL receiving items.

By default (assuming that the -trunc flag is turned off, or /NOTRUNCATE is set), VSI COBOL truncates values according to the Alpha, I64 hardware storage unit (word, longword, or quadword) allocated to the receiving item.

If you specify -trunc or /TRUNCATE, the compiler truncates values according to the number of decimal digits specified by the PICTURE clause.

Rounding is an important option that you can use with arithmetic operations.

You can use the ROUNDED phrase with any VSI COBOL arithmetic statement. Rounding takes place only when the ROUNDED phrase requests it, and then only if the intermediate result has low-order digits that cannot be stored in the result.

VSI COBOL rounds off by adding a 5 to the leftmost truncated digit of the absolute value of the intermediate result before it stores that result.

The SIZE ERROR phrase detects the loss of high-order nonzero digits in the results of VSI COBOL arithmetic operations. It does this by checking the absolute value of an arithmetic result against the PICTURE character-string of each resultant identifier. For example, if the absolute value of the result is 100.05, and the PICTURE character-string of the resultant identifier is 99V99, the SIZE ERROR phrase detects that the high-order digit, 1, will be lost, and the size error condition will be raised.

You can use the phrase in any VSI COBOL arithmetic statement.

When the execution of a statement with no ON SIZE ERROR phrase results in a size error, and native arithmetic is used, the values of all resultant identifiers are undefined. When standard arithmetic is used, or when the same statement includes an ON SIZE ERROR phrase, receiving items for which the size error exists are left unaltered; the result is stored in those receiving items for which no size error exists. The ON SIZE ERROR imperative phrase is then executed.

If the statement contains both ROUNDED and SIZE ERROR phrases, the result is rounded before a size error check is made.

 01 AMOUNT-A PIC S9(8)V99.
 01 AMOUNT-B PIC S9(4)V99.
        .
        .
        .
        MOVE AMOUNT-A TO AMOUNT-B.

 1.  IF AMOUNT-A NOT > 9999.99
        MOVE AMOUNT-A TO AMOUNT-B
        ELSE ...
 2.  ADD ZERO AMOUNT-A GIVING AMOUNT-B
        ON SIZE ERROR ...
 3.  COMPUTE AMOUNT-B = AMOUNT-A
        ON SIZE ERROR ...

All three alternatives allow the MOVE operation to occur only if AMOUNT-A loses no significant digits. If the value in AMOUNT-A is too large, all three avoid altering AMOUNT-B and take the alternate execution path.

You can also use a NOT ON SIZE ERROR phrase to branch to, or perform, sections of code only when no size error occurs.

The GIVING phrase moves the intermediate result of an arithmetic operation to a receiving item. The phrase acts exactly like a MOVE statement in which the intermediate result serves as the sending item, and the data item following the word GIVING serves as the receiving item. When a statement contains a GIVING phrase, you can have a numeric-edited receiving item.

The receiving item can also have the ROUNDED phrase. If the receiving item is also numeric-edited, rounding takes place before the editing.

ADD A,B GIVING C.

Both the ADD and SUBTRACT statements can contain a series of operands preceding the word TO, FROM, or GIVING.

As in all VSI COBOL statements, the commas in these statements are optional.

A group item is a data item that is followed by one or more elementary items or other group items, all of which have higher-valued level numbers than the group to which they are subordinate.

The size of a group item is the sum of the sizes of its subordinate elementary items. The compiler considers all group items to be alphanumeric DISPLAY items regardless of the class and usage of their subordinate elementary items.

An elementary item is a data item that has no subordinate data item.

 01 TRANREC.
    03 FIELD-1 PIC X(7).
    03 FIELD-2 PIC S9(5)V99.

Both elementary items require seven bytes of memory; however, item FIELD-1 contains seven alphanumeric characters while item FIELD-2 contains seven decimal digits, an operational sign, and an implied decimal point. Operations on such items are independent of the mapping of the item into memory words (32-bit words that hold four 8-bit bytes). An item can begin in the leftmost or rightmost byte of a word with no effect on the function of any operation that refers to that item. (However, the position of items in memory can have an effect on run-time performance.)

In effect, the compiler sees memory as a continuous array of bytes, not words. This becomes particularly important when you are defining a table using the OCCURS clause (see Chapter 4, Handling Tables).

In VSI COBOL, all records, and elementary items with level 01 or 77, begin at an address that is a multiple of 8 bytes (a quadword boundary). By default, the VSI COBOL compiler will locate a subordinate data item at the next unassigned byte location.

Refer to Chapter 16, Managing Memory and Data Access, Chapter 15, Optimizing Your VSI COBOL Program, and the SYNCHRONIZED clause in the VSI COBOL Reference Manual for a complete discussion of alignment.

An IF statement with a relation condition can compare the value in a nonnumeric data item with another value and use the result to alter the flow of control in the program.

An IF statement with a relation condition compares two operands. Either of these operands can be an identifier or a literal, but they cannot both be literals. If the stated relation exists between the two operands, the relation condition is true.

IF ITEM-1 IS NUMERIC...
IF ITEM-2 IS ALPHABETIC...
IF ITEM-3 IS NOT NUMERIC...

If the data item consists entirely of the ASCII characters 0 to 9, with or without the operational sign, the class condition is NUMERIC. If the item consists entirely of the ASCII characters A to Z (upper- or lowercase) and spaces, the class condition is ALPHABETIC.

The ALPHABETIC-LOWER test is true if the operand contains any combination of the lowercase alphabetic characters a to z, and the space. Otherwise the test is false.

The ALPHABETIC-UPPER test is true if the operand contains any combination of the uppercase alphabetical characters A to Z, and the space. Otherwise, the test is false.

You can also perform a class test on a data item that you define with the CLASS clause of the SPECIAL-NAMES paragraph.

A class test is true if the operand consists entirely of the characters listed in the definition of the CLASS-NAME in the SPECIAL-NAMES paragraph. Otherwise, the test is false.

When the reserved word NOT is present, the compiler considers it and the next key word as one class condition defining the class test to be executed. For example, NOT NUMERIC determines if an operand contains at least one nonnumeric character.

For further information on using class conditions with numeric items, refer to the VSI COBOL Reference Manual.

If either the sending or receiving item is a group item, the compiler considers the move to be a group move. It treats both the sending and receiving items as if they were alphanumeric items.

If the sending item is a group item, and the receiving item is an elementary item, the compiler ignores the receiving item description except for the size description, in bytes, and any JUSTIFIED clause. It conducts no conversion or editing on the sending item's data.

If both items of a MOVE statement are elementary items, their PICTURE character-strings control their data movement. If the receiving item was described as numeric or numeric edited, the rules for numeric moves control the data movement (see Section 2.6, “Using the MOVE Statement”). Nonnumeric receiving items are alphanumeric, alphanumeric edited, or alphabetic.

In all valid moves, the compiler treats the sending item as though it had been described as PIC X(n). A JUSTIFIED clause in the sending item's description has no effect on the move. If the sending item's PICTURE character-string contains editing characters, the compiler uses them only to determine the item's size.

The JUSTIFIED clause and editing characters are mutually exclusive.

When an item that contains no editing characters or JUSTIFIED clause in its description is used as the receiving item of a nonnumeric elementary MOVE statement, the compiler moves the characters starting at the leftmost position in the item and proceeding, character by character, to the rightmost position. If the sending item is shorter than the receiving item, the compiler fills the remaining character positions with spaces. If the sending item is longer than the receiving item, truncation occurs on the right.

Numeric items used in nonnumeric elementary moves must be integers in DISPLAY format.

If the description of the numeric data item indicates the presence of an operational sign (either as a character or an overpunched character), or if there are P characters in its character-string, the compiler first moves the item to a temporary location. It removes the sign and fills out any P character positions with zero digits. It then uses the temporary value as the sending item as if it had been described as PIC X(n). The temporary value can be shorter than the original value if a separate sign was removed, or longer than the original value if P character positions were filled with zeros.

If the sending item is an unsigned numeric class item with no P characters in its character-string, the MOVE is accomplished directly from the sending item, and a temporary item is not required.

If the numeric sending item is shorter than the receiving item, the compiler fills the receiving item with spaces.

MOVE FIELD1 TO FIELD2

MOVE FIELD1 TO FIELD2

If you write a MOVE statement containing more than one receiving item, the compiler moves the same sending item value to each of the receiving items. It has essentially the same effect as a series of separate MOVE statements, all with the same sending item.

The receiving items need have no relationship to each other. The compiler checks the validity of each one independently and performs an independent move operation on each one.

MOVE SPACES TO LIST-LINE, EXCEPTION-LINE, NAME-FLD.
MOVE ZEROS TO EOL-FLAG, EXCEPT-FLAG, NAME-FLAG.
MOVE 1 TO COUNT-1, CHAR-PTR, CURSOR.

Any item (other than a data item that is not subordinate to an OCCURS clause) of a MOVE statement can be subscripted, and the referenced item can be used to subscript another name in the same statement.

MOVE FIELD1(FIELD2) TO FIELD2 FIELD3.

MOVE FIELD1(FIELD2) TO TEMP.
MOVE TEMP TO FIELD2.
MOVE TEMP TO FIELD3.

MOVE FIELD1 TO FIELD2 FIELD3(FIELD2).

MOVE FIELD1 TO FIELD2.
MOVE FIELD1 TO FIELD3(FIELD2).

The compiler considers any MOVE statement that contains a group item (whether sending or receiving) to be a group move. If an elementary item contains editing characters or a numeric integer, these attributes of the receiving item have no effect on the action of a group move.

WORKING-STORAGE SECTION.
01  ITEMA  PIC X(10)  VALUE IS "XYZABCDEFG".
        .
        .
        .
    MOVE ITEMA(4:3) TO...


IDENTIFIER                 VALUE
ITEMA (4:3)                ABC

For more information on reference modification rules, refer to the VSI COBOL Reference Manual.

To define fixed-length tables, use Format 1 of the OCCURS clause (refer to the VSI COBOL Reference Manual). This format is useful when you are storing large amounts of stable or frequently used reference data. Options allow you to define single or multiple keys, or indexes, or both.

 01  TABLE-A.
     05  ITEM-B PIC X OCCURS 2 TIMES.

The organization of TABLE-A is shown in Figure 4.1, “Organization of the One-Dimensional Table in Example 4.1, “One-Dimensional Table””.

 01  TABLE-A.
     05  GROUP-B OCCURS 2 TIMES.
         10  ITEMC PIC X.
         10  ITEMD PIC X.

The organization of this table is shown in Figure 4.2, “Organization of Multiple Data Items in a One-Dimensional Table”.

Example 4.1, “One-Dimensional Table” and Example 4.2, “Multiple Data Items in a One-Dimensional Table” both do not use the KEY IS or INDEXED BY optional phrases. The INDEXED BY phrase implicitly defines an index name. This phrase must be used if any Procedure Division statements contain indexed references to the data name that contains the OCCURS clause. The KEY IS phrase means that repeated data is arranged in ascending or descending order according to the values in the data items that contain the OCCURS clause. (The KEY IS phrase does not cause the data in the table to be placed in ascending or descending order; rather, it allows you to state how you have arranged the data.) For further information about these OCCURS clause options, refer to the VSI COBOL Reference Manual.

 01  TABLE-A.
     05  ELEMENTB OCCURS 5 TIMES
                  ASCENDING KEY IS ITEMC
                  INDEXED BY INDX1.
         10  ITEMC PIC X.
         10  ITEMD PIC X.

The organization of this table is shown in Figure 4.3, “Organization of a Table with an Index and an Ascending Search Key”.

VSI COBOL allows 48 levels of OCCURS nesting. If you want to define a two-dimensional table, you define another one-dimensional table within each element of the one-dimensional table. To define a three-dimensional table, you define another one-dimensional table within each element of the two-dimensional table, and so on.

 01  2D-TABLE-X.
     05  LAYER-Y OCCURS 2 TIMES.
         10  LAYER-Z OCCURS 2 TIMES.
             15  CELLA PIC X.
             15  CELLB PIC X.

The organization of this two-dimensional table is shown in Figure 4.4, “Organization of a Two-Dimensional Table”.

 01 TABLE-A.
     05  LAYER-B OCCURS 2 TIMES.
         10  ITEMC PIC X.
         10  ITEMD PIC X OCCURS 3 TIMES.
         10  ITEME OCCURS 2 TIMES.
             15  CELLF PIC X.
             15  CELLG PIC X OCCURS 3 TIMES.

The organization of this three-dimensional table is shown in Figure 4.5, “Organization of a Three-Dimensional Table”.

To define a variable-length table, use Format 2 of the OCCURS clause (refer to the VSI COBOL Reference Manual). Options allow you to define single or multiple keys, or indexes, or both.

Example 4.6, “Defining a Variable-Length Table” illustrates how to define a variable-length table.

It uses from two to four occurrences depending on the integer value assigned to NUM-ELEM. You specify the table's minimum and maximum size with the OCCURS (minimum size) TO (maximum size) clause. The minimum size value must be equal to or greater than zero and the maximum size value must be greater than the minimum size value. The DEPENDING ON clause is also required when you use the TO clause.

The data-name of an elementary, unsigned integer data item is specified in the DEPENDING ON clause. Its value specifies the current number of occurrences. The data-name in the DEPENDING ON clause must be within the minimum to maximum range.

Unlike fixed-length tables, you can dynamically alter the number of element occurrences in variable-length tables.

 01  NUM-ELEM PIC 9.
        .
        .
        .
 01  VAR-LEN-TABLE.
     05  TAB-ELEM OCCURS 2 TO 4 TIMES DEPENDING ON NUM-ELEM.
         10 A PIC X.
         10 B PIC X.

The compiler maps the table elements into memory, following mapping rules that depend on the use of COMP, COMP-1, COMP-2, POINTER, and INDEX data items in the table element, the presence or absence of the SYNCHRONIZED (SYNC) clause with those data items, and the -align flag (on the UNIX operating system) or the /ALIGNMENT qualifier (on the OpenVMS Alpha and I64 operating systems).

 01 TABLE-A.
     03 GROUP-G PIC X(5) OCCURS 5 TIMES.

Figure 4.6, “Memory Map for Example 4.7, “Sample Record Description Defining a Table”” shows how the table defined in Example 4.7, “Sample Record Description Defining a Table” is mapped into memory.

Alphanumeric data items require 1 byte of storage per character. Therefore, each occurrence of GROUP-G occupies 5 bytes. The first byte of the first element is automatically aligned at the left record boundary and the first 5 bytes occupy all of word 1 and part of 2. A memory longword is composed of 4 bytes. Succeeding occurrences of GROUP-G are assigned to the next 5 adjacent bytes so that TABLE-A is composed of five 5-byte elements for a total of 25 bytes. Each table element, after the first, is allowed to start in any byte of a word with no regard for word boundaries.

4.1.4.1. Using the SYNCHRONIZED Clause

By default, the VSI COBOL compiler tries to allocate a data item at the next unassigned byte location. However, you can align some data items on a 2-, 4-, or 8-byte boundary by using the SYNCHRONIZED clause. The compiler may then have to skip one or more bytes before assigning a location to the next data item. The skipped bytes, called fill bytes, are gaps between one data item and the next.

The SYNCHRONIZED clause explicitly aligns COMP, COMP-1, COMP-2, POINTER, and INDEX data items on their natural boundaries: one-word COMP items on 2-byte boundaries, longword items on 4-byte boundaries, and quadword items on 8-byte boundaries. Thus the use of SYNC can have a significant effect on the amount of memory required to store tables containing COMP and COMP SYNC data items.

Note

The examples in this section assume compilation without the -align flag (on UNIX systems) or the /ALIGNMENT qualifier (on OpenVMS Alpha and I64 systems).

Example 4.8, “Record Description Containing a COMP SYNC Item” describes a table containing a COMP SYNC data item. Figure 4.7, “Memory Map for Example 4.8, “Record Description Containing a COMP SYNC Item”” illustrates how it is mapped into memory.

 01 A-TABLE.
    03 GROUP-G OCCURS 4 TIMES.
       05 ITEM1 PIC X.
       05 ITEM2 PIC S9(5) COMP SYNC.

Because a 5-digit COMP SYNC item requires one longword (or 4 bytes) of storage, ITEM2 must start on a longword boundary. This requires the addition of 3 fill bytes after ITEM1, and each GROUP-G occupies 8 bytes. In Example 4.8, “Record Description Containing a COMP SYNC Item”, A-TABLE requires 32 bytes to store four elements of 8 bytes each.

If, in the previous example, you define ITEM2 as a COMP data item of the same size without the SYNC clause, the storage required will be considerably less. Although ITEM2 will still require one longword of storage, it will be aligned on a byte boundary. No fill bytes will be needed between ITEM1 and ITEM2, and A-TABLE will require a total of 20 bytes.

If you now add a 3-byte alphanumeric item (ITEM3) to Example 4.8, “Record Description Containing a COMP SYNC Item” and locate it between ITEM1 and ITEM2 (see Example 4.9, “Adding an Item Without Changing the Table Size”), the new item occupies the space formerly occupied by the 3 fill bytes. This adds 3 data bytes without changing the table size, as Figure 4.8, “Memory Map for Example 4.9, “Adding an Item Without Changing the Table Size”” illustrates.

 01 A-TABLE.
    03 GROUP-G OCCURS 4 TIMES.
       05 ITEM1 PIC X.
       05 ITEM3 PIC XXX.
       05 ITEM2 PIC 9(5) COMP SYNC.

 01 A-TABLE.
    03 GROUP-G OCCURS 4 TIMES.
       05 ITEM1 PIC X.
       05 ITEM2 PIC 9(5) COMP SYNC.
       05 ITEM3 PIC XXX.

If, however, you place ITEM3 after ITEM2, the additional 3 bytes add their own length plus another fill byte. The additional fill byte is added after the third ITEM3 character to ensure that all occurrences of the table element are mapped in an identical manner. Now, each element requires 12 bytes, and the complete table occupies 48 bytes. This is illustrated by Example 4.10, “How Adding 3 Bytes Adds 4 Bytes to the Element Length” and Figure 4.9, “Memory Map for Example 4.10, “How Adding 3 Bytes Adds 4 Bytes to the Element Length””.

Note that GROUP-G begins on a 4-byte boundary because of the way VSI COBOL allocates memory.

A subscript can be an integer literal, an arithmetic expression, a data name, or a subscripted data name that has an integer value. The integer value represents the desired element of the table. An integer value of 3, for example, refers to the third element of a table.

Table Description:
        01 A-TABLE.
          03 A-GROUP PIC X(5)
             OCCURS 10 TIMES.
Instruction:
           MOVE A-GROUP(2) TO I-RECORD.

If the table is multidimensional, follow the data name of the desired data item with a list of subscripts, one for each OCCURS clause to which the item is subordinate. The first subscript in the list applies to the first OCCURS clause to which that item is subordinate. This is the most inclusive level, and is represented by A-GROUP in Example 4.16, “Subscripting a Multidimensional Table”. The second subscript applies to the next most inclusive level and is represented by ITEM3 in the example. Finally, the third subscript applies to the least inclusive level, represented by ITEM5. (Note that VSI COBOL can have 48 subscripts that follow the pattern in Example 4.15, “Using a Literal Subscript to Access a Table”.)

Table Description:
        01 A-TABLE.
          03 A-GROUP OCCURS 5 TIMES.
             05 ITEM1           PIC X.
             05 ITEM2           PIC 99 COMP OCCURS 20 TIMES.
             05 ITEM3 OCCURS 20 TIMES.
                07 ITEM4        PIC X.
                07 ITEM5        PIC XX OCCURS 4 TIMES.
       01 I-FIELD5              PIC XX.
Procedural Instruction:
              MOVE ITEM5(2, 11, 3) TO I-FIELD5.

You can also use data names to specify subscripts. To use a data name as a subscript, define it with COMP, COMP-1, COMP-2, COMP-3, or DISPLAY usage and with a numeric integer value. If the data name is signed, the sign must be positive at the time the data name is used as a subscript.

A data name that is a subscript can also be subscripted; for example, A(B(C)). Note that for efficiency your subscripts should be S9(5) to S9(9) COMP.

The same rules apply for specifying indexes as for subscripts, except that the index must be named in the INDEXED BY phrase of the OCCURS clause.

Table Description:
        01 A-TABLE.
          03 A-GROUP OCCURS 5 TIMES
             INDEXED BY IND-NAME
             05   ITEMC   PIC X  VALUE "C".
             05   ITEMD   PIC X  VALUE "D".
        01 I-FIELD     PIC X(5).
Procedural Instructions:
       SET IND-NAME TO 3.
       MOVE A-GROUP(IND-NAME) TO I-FIELD.

To perform relative indexing when referring to a table element, you follow the index name with a plus or minus sign and an integer literal. Although it is easy to use, relative indexing generates additional overhead each time a table element is referenced in this way. The run-time overhead for relative indexing of variable-length tables is significantly greater than that required for fixed-length tables. If any of the range checks reveals an out-of-range index value, program execution terminates, and an error message is issued. You can use the -check flag (on UNIX systems) or the /CHECK qualifier (on OpenVMS systems) to check the range when you compile the program.

On UNIX, see Chapter 1, Developing VSI COBOL Programs or the cobol man page for more information about the -check flag.

On OpenVMS, invoke the online help facility for VSI COBOL at the OpenVMS system prompt for more information about the /CHECK qualifier.

 SET IND-NAME TO 1.
 MOVE A-GROUP(IND-NAME + 3) TO I-FIELD.

Often a program requires that the value of an index be stored outside of that item. VSI COBOL provides the index data item to fulfill this requirement.

Index data items are stored as longword COMP items and must be declared with a USAGE IS INDEX phrase in the item description. Index data items can be explicitly modified only with the SET statement.

You can use the SET statement to assign values to indexes associated with tables to reference particular table elements. The following sections discuss the two relevant SET statement formats. (All six SET statement formats are shown in the VSI COBOL Reference Manual.)

 SET IND-5 TO 5.

 SET INDEX-A TO COUNT-1.

 SET TAB1-IND TAB2-IND TO 15.

 SET INDEX-ITEM TO TAB-IND.
          .
          .
          .
 DISPLAY INDEX-ITEM WITH CONVERSION.

 SET TABLE-INDEX UP BY 12.
 SET TABLE-INDEX DOWN BY 5.

The SEARCH statement is used to search a table for an element that satisfies a known condition. The statement provides for sequential and binary searches, which are described in the following sections.

DATA DIVISION.
WORKING-STORAGE SECTION.
01  TEMP-IND                            USAGE IS INDEX.
01  FED-TAX-TABLES.
    02  ALLOWANCE-DATA.
        03  FILLER                      PIC X(70) VALUE
            "0101440
-           "0202880
-           "0304320
-           "0405760
-           "0507200
-           "0608640
-           "0710080
-           "0811520
-           "0912960
-           "1014400".
    02  ALLOWANCE-TABLE REDEFINES ALLOWANCE-DATA.
        03  FED-ALLOWANCES OCCURS 10 TIMES
            ASCENDING KEY IS ALLOWANCE-NUMBER
            INDEXED BY IND-1.
            04  ALLOWANCE-NUMBER        PIC XX.
            04  ALLOWANCE               PIC 99999.
    02 SINGLES-DEDUCTION-DATA.
        03  FILLER                      PIC X(112) VALUE
            "0250006700000016
-           "0670011500067220
-           "1150018300163223
-           "1830024000319621
-           "2400027900439326
-           "2790034600540730
-           "3460099999741736".
   02   SINGLE-DEDUCTION-TABLE REDEFINES SINGLES-DEDUCTION-DATA.
        03  SINGLES-TABLE OCCURS 7 TIMES
            ASCENDING KEY IS S-MIN-RANGE S-MAX-RANGE
            INDEXED BY IND-2, TEMP-INDEX.
            04  S-MIN-RANGE             PIC 99999.
            04  S-MAX-RANGE             PIC 99999.
            04  S-TAX                   PIC 9999.
            04  S-PERCENT               PIC V99.
    02  MARRIED-DEDUCTION-DATA.
        03  FILLER                      PIC X(119) VALUE
            "04800096000000017
-           "09600173000081620
-           "17300264000235617
-           "26400346000390325
-           "34600433000595328
-           "43300500000838932
-           "50000999991053336".
    02  MARRIED-DEDUCTION-TABLE REDEFINES MARRIED-DEDUCTION-DATA.
        03 MARRIED-TABLE OCCURS 7 TIMES
           ASCENDING KEY IS M-MIN-RANGE M-MAX-RANGE
           INDEXED BY IND-0, IND-3.
           04  M-MIN-RANGE              PIC 99999.
           04  M-MAX-RANGE              PIC 99999.
           04  M-TAX                    PIC 99999.
           04  M-PERCENT                PIC V99.

01   TAXABLE-INCOME PIC 9(6) VALUE 50000.
01   FED-TAX-DEDUCTION PIC 9(6).
PROCEDURE DIVISION.
BEGIN.
       PERFORM SINGLE.
       DISPLAY FED-TAX-DEDUCTION.
       STOP RUN. SINGLE.
       IF TAXABLE-INCOME < 02500
               GO TO END-FED-COMP.
       SET IND-2 TO 1.
       SEARCH SINGLES-TABLE AT END
               GO TO TABLE-2-ERROR
          WHEN TAXABLE-INCOME = S-MIN-RANGE(IND-2)
               MOVE S-TAX(IND-2) TO FED-TAX-DEDUCTION
          WHEN TAXABLE-INCOME < S-MAX-RANGE(IND-2)
               COMPUTE FED-TAX-DEDUCTION =
                   S-TAX(IND-2) + (TAXABLE-INCOME - S-TAX(IND-2)) *
                   S-PERCENT(IND-2).
⋮

01   TAXABLE-INCOME PIC 9(6) VALUE 50000.
01   FED-TAX-DEDUCTION PIC 9(6).
PROCEDURE DIVISION.
BEGIN.
       PERFORM MARRIED.
       DISPLAY FED-TAX-DEDUCTION.
       STOP RUN.
MARRIED.
       IF TAXABLE-INCOME < 04800
               MOVE ZEROS TO FED-TAX-DEDUCTION
               GO TO END-FED-COMP.
       SET IND-3 TO 1.
       SEARCH MARRIED-TABLE VARYING IND-3 AT END
               GO TO TABLE-3-ERROR
          WHEN TAXABLE-INCOME = M-MIN-RANGE(IND-3)
               MOVE M-TAX(IND-3) TO FED-TAX-DEDUCTION
          WHEN TAXABLE-INCOME < M-MAX-RANGE(IND-3)
               COMPUTE FED-TAX-DEDUCTION =
                   M-TAX(IND-3) + (TAXABLE-INCOME - M-TAX(IND-3)) *
                   M-PERCENT(IND-3).
   .
   .
   .

01   TAXABLE-INCOME PIC 9(6) VALUE 50000.
01   FED-TAX-DEDUCTION PIC 9(6).
PROCEDURE DIVISION.
BEGIN.
       PERFORM SINGLE.
       DISPLAY FED-TAX-DEDUCTION.
       STOP RUN.
SINGLE.
       IF TAXABLE-INCOME < 02500
               GO TO END-FED-COMP.
       SET IND-2 TO 1.
       SEARCH SINGLES-TABLE VARYING TEMP-IND AT END
               GO TO TABLE-2-ERROR
          WHEN TAXABLE-INCOME = S-MIN-RANGE(IND-2)
               MOVE S-TAX(IND-2) TO FED-TAX-DEDUCTION
          WHEN TAXABLE-INCOME < S-MAX-RANGE(IND-2)
               MOVE S-TAX(IND-2) TO FED-TAX-DEDUCTION
               SUBTRACT S-MIN-RANGE(IND-2) FROM TAXABLE-INCOME
               MULTIPLY TAXABLE-INCOME BY S-PERCENT(IND-2) ROUNDED
               ADD TAXABLE-INCOME TO FED-TAX-DEDUCTION.

   .
   .
   .

01   TAXABLE-INCOME PIC 9(6) VALUE 50000.
01   FED-TAX-DEDUCTION PIC 9(6).
PROCEDURE DIVISION.
BEGIN.
       PERFORM SINGLE.
       DISPLAY FED-TAX-DEDUCTION.
       STOP RUN. SINGLE.
        IF TAXABLE-INCOME < 02500
               GO TO END-FED-COMP.
        SET IND-2 TO 1.
        SEARCH SINGLES-TABLE VARYING IND-0 AT END
               GO TO TABLE-2-ERROR
          WHEN TAXABLE-INCOME = S-MIN-RANGE(IND-2)
               MOVE S-TAX(IND-2) TO FED-TAX-DEDUCTION
          WHEN TAXABLE-INCOME < S-MAX-RANGE(IND-2)
               MOVE S-TAX(IND-2) TO FED-TAX-DEDUCTION
               SUBTRACT S-MIN-RANGE(IND-2) FROM TAXABLE-INCOME
               MULTIPLY TAXABLE-INCOME BY S-PERCENT(IND-2) ROUNDED
               ADD TAXABLE-INCOME TO FED-TAX-DEDUCTION.

   .
   .
   .

01   NR-DEPENDENTS     PIC 9(2)  VALUE 3.
01   GROSS-WAGE        PIC 9(6)  VALUE 50000.
01   TAXABLE-INCOME    PIC 9(6)  VALUE 50000.
01   FED-TAX-DEDUCTION PIC9(6).
01   MARITAL-STATUS    PIC X     VALUE "M".
PROCEDURE DIVISION.
BEGIN.
       PERFORM FED-DEDUCT-COMPUTATION.
       DISPLAY TAXABLE-INCOME.
       STOP RUN.
FED-DEDUCT-COMPUTATION.
          SET IND-1 TO 1.
          SEARCH FED-ALLOWANCES AT END
                 GO TO TABLE-1-ERROR
            WHEN ALLOWANCE-NUMBER(IND-1) = NR-DEPENDENTS
                 SUBTRACT ALLOWANCE(IND-1) FROM GROSS-WAGE
                     GIVING TAXABLE-INCOME ROUNDED.
          IF MARITAL-STATUS = "M"
                 GO TO MARRIED.
MARRIED.

   .
   .
   .

IDENTIFICATION DIVISION.
PROGRAM-ID. MULTI-KEY-SEARCH.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DIRECTORY-TABLE.
   05 NAMES-NUMBERS.
      10 FILLER                PIC X(30)
         VALUE "SMILEY    HAPPY     T.213-4332".
      10 FILLER                PIC X(30)
         VALUE "SMITH     ALAN      C.881-4987".
      10 FILLER                PIC X(30)
         VALUE "SMITH     CHARLES   J.345-2398".
      10 FILLER                PIC X(30)
         VALUE "SMITH     FREDERICK   745-0223".
      10 FILLER                PIC X(30)
         VALUE "SMITH     HARRY     C.573-3306".
      10 FILLER                PIC X(30)
         VALUE "SMITH     HARRY     J.295-3485".
      10 FILLER                PIC X(30)
         VALUE "SMITH     LARRY     X.976-5504".
      10 FILLER                PIC X(30)
         VALUE "SMITHWOOD ALBERT    J.349-9927".
   05 PHONE-DIRECTORY-TABLE REDEFINES NAMES-NUMBERS OCCURS 8 TIMES
                                  ASCENDING KEY IS LAST-NAME
                                                   FIRST-NAME
                                                   MID-INIT
                                  INDEXED BY DIR-INDX.
         15 LAST-NAME          PIC X(10).
         15 FIRST-NAME         PIC X(10).
         15 MID-INIT           PIC XX.
         15  PHONE-NUM         PIC X(8).
PROCEDURE DIVISION.
MULTI-KEY-BINARY-SEARCH.
    SEARCH ALL PHONE-DIRECTORY-TABLE
           WHEN LAST-NAME(DIR-INDX) = "SMITH"
           AND FIRST-NAME(DIR-INDX) = "HARRY"
           AND MID-INIT(DIR-INDX) = "J."
               NEXT SENTENCE.
DISPLAY-RESULTS.
    DISPLAY LAST-NAME(DIR-INDX)","
            FIRST-NAME(DIR-INDX)
            MID-INIT(DIR-INDX) " "
            PHONE-NUM(DIR-INDX).

STRING FIELD1A FIELD1B FIELD1C DELIMITED BY SIZE
                           INTO FIELD2.

In this sample STRING statement, FIELD1A, FIELD1B, and FIELD1C are all sending items. The compiler moves them to the receiving item (FIELD2) in the order in which they appear in the statement, from left to right, resulting in the concatenation of their values.

If FIELD2 is not large enough to hold all three items, the operation stops when it is full. If the operation stops while moving one of the sending items, the compiler ignores the remaining characters of that item and any other sending items not yet processed. For example, if FIELD2 is filled while it is receiving FIELD1B, the compiler ignores the rest of FIELD1B and all of FIELD1C.

If the sending items do not fill the receiving item, the operation stops when the last character of the last sending item (FIELD1C) is moved. It does not alter the contents nor space-fill the remaining character positions of the receiving item.

01 ADDRESS-GROUP.
   03 CITY           PIC X(20).
   03 STATE          PIC XX.
   03 ZIP            PIC X(5).
01 ADDRESS-LINE      PIC X(31).
      .
      .
      .
PROCEDURE DIVISION.
BEGIN.
   STRING CITY SPACE STATE ". " SPACE ZIP
        DELIMITED BY SIZE INTO ADDRESS-LINE.
      .
      .
      .

Although the sending items of the STRING statement are fixed in size at compile time, they are frequently filled with spaces. For example, if a 20-character city item contains the text MAYNARD followed by 13 spaces, the STRING statement using the DELIMITED BY SIZE phrase would move the text (MAYNARD) and the unwanted 13 spaces (assuming the receiving item is at least 20 characters long). The DELIMITED BY phrase, written with a data name or literal, eliminates this problem.

The delimiter can be a literal, a data item, a figurative constant, or the word SIZE. It cannot, however, be ALL literal, because ALL literal has an indefinite length. When the phrase contains the word SIZE, the compiler moves each sending item in total, until it either exhausts the characters in the sending item or fills the receiving item.

If you use the code in Example 5.1, “Using the STRING Statement and Literals”, and CITY is a 20-character item, the result of the STRING operation might look like Figure 5.1, “Results of the STRING Operation”.

AYER, MA. 01432 

MOVE 1 TO P.
STRING CITY DELIMITED BY SPACE
        INTO ADDRESS-LINE WITH POINTER P.
STRING ", " STATE ". " ZIP
        DELIMITED BY SIZE
        INTO ADDRESS-LINE WITH POINTER P.

This example makes use of the POINTER phrase (see Section 5.1.3, “Using the POINTER Phrase”). The first STRING statement moves data characters until it encounters a space character - a match of the delimiter SPACE. The second STRING statement supplies the literal, the 2-character STATE item, another literal, and the 5-character ZIP item.

STRING CITY DELIMITED BY SPACE
        ", " STATE ". "
        ZIP DELIMITED BY SIZE
        INTO ADDRESS-LINE.

STRING CITY ", " STATE ". " ZIP
        DELIMITED BY "  " INTO ADDRESS-LINE. 

Because only the CITY item contains two consecutive spaces, the delimiter's search of the other items will always be unsuccessful, and the effect is the same as moving the full item (delimiting by SIZE).

Data movement under control of a data name or literal generally executes more slowly than data movement delimited by SIZE.

MOVE SPACES TO ADDRESS-LINE.

This statement guarantees a space-fill to the right of the concatenated result. Alternatively, the last item concatenated by the STRING statement can be an item previously set to SPACES. This sending item must either be moved under control of a delimiter other than SPACE or use the value of POINTER and reference modification.

MOVE 5 TO P.
STRING FIELD1A FIELD1B DELIMITED BY SIZE
        INTO FIELD2 WITH POINTER P.

The value of P determines the starting character position in the receiving item. In this example, the 5 in P causes the program to move the first character of FIELD1A into character position 5 of FIELD2 (the leftmost character position of the receiving item is character position 1), and leave positions 1 to 4 unchanged.

When the STRING operation is complete, P points to one character position beyond the last character replaced in the receiving item. If FIELD1A and FIELD1B are both four characters long, P contains a value of 13 (5+4+4) when the operation is complete (assuming that FIELD2 is at least 13 characters long).

When the SIZE option of the DELIMITED BY phrase controls the STRING operation, and the pointer value is either known or the POINTER phrase is not used, you can add the PICTURE sizes of sending items together at program development time to see if the receiving item is large enough to hold the sending items. However, if the DELIMITED BY phrase contains a literal or an identifier, or if the pointer value is not predictable, it can be difficult to tell whether or not the size of the receiving item will be large enough at run time. If the size of the receiving item is not large enough, an overflow can occur.

An overflow occurs when the receiving item is full and the program is either about to move a character from a sending item or is considering a new sending item. Overflow can also occur if, during the initialization of the statement, the pointer contains a value that is either less than 1 or greater than the length of the receiving item. In this case, the program moves no data to the receiving item and terminates the operation immediately.

STRING FIELD1A FIELD1B DELIMITED BY "C"
        INTO FIELD2 WITH POINTER PNTR
        ON OVERFLOW GO TO 200-STRING-OVERFLOW.

The ON OVERFLOW phrase cannot distinguish the overflow caused by a bad initial value in the pointer from the overflow caused by a receiving item that is too short. Only a separate test preceding the STRING statement can distinguish between the two.

Additionally, even if an overflow condition does not exist, you can use the NOT ON OVERFLOW phrase to branch to or execute other sections of code.

DATA DIVISION.
     .
     .
     .
01 FIELD1 PIC XXX VALUE "ABC".
01 FIELD2 PIC XXXX.
PROCEDURE DIVISION.
           .
           .
           .
1.    STRING FIELD1 QUOTE DELIMITED BY SIZE INTO FIELD2
             ON OVERFLOW DISPLAY "overflow at 1".
2.    STRING FIELD1 FIELD1 DELIMITED BY SIZE INTO FIELD2
             ON OVERFLOW DISPLAY "overflow at 2".
3.    STRING FIELD1 FIELD1 DELIMITED BY "C" INTO FIELD2
             ON OVERFLOW DISPLAY "overflow at 3".
4.    STRING FIELD1 FIELD1 FIELD1 FIELD1
             DELIMITED BY "B" INTO FIELD2 ON OVERFLOW DISPLAY "overflow at 4".
5.    STRING FIELD1 FIELD1 "D" DELIMITED BY "C"
             INTO FIELD2 ON OVERFLOW DISPLAY "overflow at 5".
6.    MOVE 2 TO P.
       MOVE ALL QUOTES TO FIELD2.
       STRING FIELD1 "AC" DELIMITED BY "C"
             INTO FIELD2 WITH POINTER P ON OVERFLOW DISPLAY "overflow at 6". 

UNSTRING FIELD1 INTO FIELD2A FIELD2B FIELD2C.

The compiler-generated code performs the UNSTRING operation by scanning across FIELD1, the sending item, from left to right. When the number of characters scanned equals the number of characters in the receiving item, the scanned characters are moved into that item and the next group of characters is scanned for the next receiving item.

If each of the receiving items in the preceding example (FIELD2A, FIELD2B, and FIELD2C) is 5 characters long, and FIELD1 is 15 characters long, FIELD1 is scanned until the number of characters scanned equals the size of FIELD2A (5). Those first five characters are moved to FIELD2A, and scanning is resumed at the sixth character position in FIELD1. Next, FIELD1 is scanned from character position 6, until the number of scanned characters equals the size of FIELD2B (five). The sixth through the tenth characters are then moved to FIELD2B, and the scanner is set to the next (eleventh) character position in FIELD1. For the last move in this example, characters 11 to 15 of FIELD1 are moved into FIELD2C.

FIELD2A is an alphanumeric item. Therefore, the statement simply conducts an elementary nonnumeric move with the first five characters.

FIELD2B, however, has a leading separate sign that is not included in its size. Thus, the compiler moves only five numeric characters and generates a positive sign (+) in the separate sign position.

FIELD2C has an implied decimal point with two character positions to the right of it, plus an overpunched sign on the low-order digit. The sending item should supply five numeric digits. However, because the sending item is alphanumeric, the compiler treats it as an unsigned integer; it truncates the two high-order digits and supplies two zero digits for the decimal positions. Furthermore, it supplies a positive overpunch sign, making the low-order digit a +0 (ASCII { ). There is no way to have the UNSTRING statement recognize a sign character or a decimal point in the sending item in a single statement.

If the sending item is shorter than the sum of the sizes of the receiving items, the compiler ignores the remaining receiving items. If the compiler reaches the end of the sending item before it reaches the end of one of the receiving items, it moves the scanned characters into that receiving item. It either left-justifies and fills the remaining character positions with spaces for alphanumeric data, or else it decimal point-aligns and zero-fills the remaining character positions for numeric data.

UNSTRING FIELD1 INTO FIELD2A FIELD2B.

The size of the data to be moved can be controlled by a delimiter, rather than by the size of the receiving item. The DELIMITED BY phrase supplies the delimiter characters.

UNSTRING delimiters can be literals, figurative constants (including ALL literal), or identifiers (identifiers can even be subscripted data names). This section describes the use of these three types of delimiters. Subsequent sections cover multiple delimiters, the COUNT phrase, and the DELIMITER phrase.

UNSTRING FIELD1 DELIMITED BY SPACE
         INTO FIELD2.

In this example, the compiler scans the sending item (FIELD1), searching for a space character. If it encounters a space, it moves all of the scanned (nonspace) characters that precede that space to the receiving item (FIELD2). If it finds no space character, it moves the entire sending item. When the compiler has determined the size of the sending item, it moves the contents of that item following the rules for the MOVE statement, truncating or zero-filling as required.

UNSTRING FIELD1 DELIMITED BY "*"
         INTO FIELD2.

If the delimiter matches the first character in the sending item, the compiler considers the size of the sending item to be zero. The operation still takes place, however, and fills the receiving item with spaces (if it is nonnumeric) or zeros (if it is numeric).

UNSTRING FIELD1 DELIMITED BY SPACE
         INTO FIELD2A FIELD2B. 

The compiler generates code that scans FIELD1 searching for a character that matches the delimiter. If it finds a match, it moves the scanned characters to FIELD2A and sets the scanner to the next character position to the right of the character that matched. The compiler then resumes scanning FIELD1 for a character that matches the delimiter. If it finds a match, it moves all of the characters between the character that first matched the delimiter and the character that matched on the second scan, and sets the scanner to the next character position to the right of the character that matched.

The DELIMITED BY phrase handles additional items in the same manner as it handled FIELD2B.

UNSTRING FIELD1 DELIMITED BY "*"
         INTO FIELD2A FIELD2B.

The previous examples illustrate the limitations of a single-character delimiter. To overcome these limitations, a delimiter of more than one character or a delimiter preceded by the word ALL may be used.

UNSTRING FIELD1 DELIMITED BY "**"
         INTO FIELD2A FIELD2B.

UNSTRING FIELD1 DELIMITED BY ALL "*"
         INTO FIELD2A FIELD2B.

UNSTRING FIELD1 DELIMITED BY ALL "**"
         INTO FIELD2A FIELD2B.

UNSTRING FIELD1 DELIMITED BY DEL1
         INTO FIELD2A FIELD2B.

The data name DEL1 must be alphanumeric; it can be either a group or an elementary item. If the delimiter contains a subscript, the subscript may vary as a side effect of the UNSTRING operation.

UNSTRING FIELD1 DELIMITED BY ALL SPACE
         OR ", "
         OR ","
         OR TAB
         OR CR
         INTO FIELD2A FIELD2B FIELD2C.

The COUNT phrase keeps track of the size of the sending string and stores the length in a user-supplied data area.

The length of a delimited sending item can vary from zero to the full length of the item. Some programs require knowledge of this length. For example, some data is truncated if it exceeds the size of the receiving item, so the program's logic requires this information.

UNSTRING FIELD1 DELIMITED BY ALL "*"
         INTO FIELD2A COUNT IN COUNT2A
         FIELD2B COUNT IN COUNT2B
         FIELD2C.

The compiler generates code that counts the number of characters between the leftmost position of FIELD1 and the first asterisk in FIELD1 and places the count into COUNT2A. The delimiter is not included in the count because it is not a part of the string. The data preceding the first asterisk is then moved into FIELD2A.

The compiler then counts the number of characters between the last contiguous asterisk in the first scan and the next asterisk in the second scan, and places the count in COUNT2B. The data between the delimiters of the second scan is moved into FIELD2B.

The third scan begins at the first character after the last contiguous asterisk in the second scan. Any data between the delimiters of this scan is moved to FIELD2C.

The COUNT phrase should be used only where it is needed. In this example, the length of the string moved to FIELD2C is not needed, so no COUNT phrase follows it.

If the receiving item is shorter than the value placed in the count item, the code truncates the sending string. If the number of integer positions in a numeric item is smaller than the value placed into the count item, high-order numeric digits have been lost. If a delimiter match is found on the first character examined, a zero is placed in the count item.

The COUNT phrase can be used only in conjunction with the DELIMITED BY phrase.

By using the DELIMITER and COUNT phrases, you can make the flow of program logic dependent on both the size of the sending string and the delimiter terminating the string.

UNSTRING FIELD1 DELIMITED BY ","
         OR TAB
         OR ALL SPACE
         OR CR
         INTO FIELD2A DELIMITER IN DELIMA
         FIELD2B DELIMITER IN DELIMB
         FIELD2C.

After moving the first sending string to FIELD2A, the character (or characters) that delimited that string is placed in DELIMA. In this example, DELIMA contains either a comma, a tab, a carriage return, or any number of spaces. Because the delimiter string is moved under the rules of the elementary nonnumeric MOVE statement, the compiler truncates or space-fills with left or right justification.

The second sending string is then moved to FIELD2B and its delimiting character is placed into DELIMB.

When a sending string is delimited by the end of the sending item rather than by a match on a delimiter, the delimiter string is of zero length and the DELIMITER item is space-filled. The phrase should be used only where needed. In this example, the character that delimits the last sending string is not needed, so no DELIMITER phrase follows FIELD2C.

The data item named in the DELIMITER phrase must be described as an alphanumeric item. It can contain editing characters, and it can also be a group item.

When you use both DELIMITER and COUNT phrases, the DELIMITER phrase must precede the COUNT phrase. Both of the data items named in these phrases can be subscripted or indexed. If they are subscripted, the subscript can be varied as a side effect of the UNSTRING operation.

Although the UNSTRING statement scan usually starts at the leftmost position of the sending item, the POINTER phrase lets you control the character position where the scan starts. Scanning, however, remains left to right.

When a sending item is to be unstrung into multiple receiving items, the choice of delimiters and the size of subsequent receiving items depends on the size of the first sending string and the character that delimited that string. Thus, the program needs to move the first sending item, hold its scanning position in the sending item, and examine the results of the operation to determine how to handle the sending items that follow.

This is done by using an UNSTRING statement with a POINTER phrase that fills only the first receiving item. When the first string has been moved to a receiving item, the compiler begins the next scanning operation one character beyond the delimiter that caused the interruption. The program examines the new position, the receiving item, the delimiter value, and the sending string size. It resumes the scanning operation by executing another UNSTRING statement with the same sending item and pointer data item. In this way, the UNSTRING statement moves one sending string at a time, with the form of each succeeding move depending on the context of the preceding string of data.

MOVE 1 TO PNTR. UNSTRING FIELD1 DELIMITED BY ":"
          OR TAB
          OR CR
          OR ALL SPACE
          INTO FIELD2A DELIMITER IN DELIMA COUNT IN LSIZEA
          WITH POINTER PNTR.
 IF LSIZEA = 0 GO TO NO-LABEL-PROCESS.
 IF DELIMA =  ":"
          IF PNTR > 8 GO TO BIG-LABEL-PROCESS
          ELSE GO TO LABEL-PROCESS.
 IF DELIMA = TAB GO TO BAD-LABEL PROCESS.
          .
          .
          .
 UNSTRING FIELD1 DELIMITED BY ... WITH POINTER PNTR.

PNTR contains the current position of the scanner in the sending item. The second UNSTRING statement uses PNTR to begin scanning the additional sending strings in FIELD1.

 01 FIELD1.
    02 FIELD1-CHAR OCCURS 40 TIMES.
    .
    .
    .
    UNSTRING FIELD1
             .
             .
             .
             WITH POINTER PNTR.
    IF FIELD1-CHAR(PNTR) = "X" ...

 UNSTRING FIELD1
          .
          .
          .
          WITH POINTER PNTR.
 UNSTRING FIELD1 INTO CHAR1 WITH POINTER PNTR.
 SUBTRACT 1 FROM PNTR.
 IF CHAR1 = "X" ... 

The program must decrement PNTR by 1 to work, because the second UNSTRING statement increments the pointer by 1.

The program must initialize the POINTER phrase data item before the UNSTRING statement uses it. The compiler will terminate the UNSTRING operation if the initial value of the pointer is less than one or greater than the length of the sending item. Such a pointer value causes an overflow condition. Overflow conditions are discussed in Section 5.2.7, “Exiting an UNSTRING Statement Using the OVERFLOW Phrase”.

The TALLYING phrase counts the number of receiving items that received data from the sending item.

 MOVE 0 TO RCOUNT.
 UNSTRING FIELD1 DELIMITED BY ","
          OR ALL SPACE
          INTO FIELD2A
               FIELD2B
               FIELD2C
               FIELD2D
               FIELD2E
               TALLYING IN RCOUNT.

If the compiler has moved only three sending strings when it reaches the end of FIELD1, it adds 3 to RCOUNT. The first three receiving items (FIELD2A, FIELD2B, and FIELD2C) contain data from the UNSTRING operation, but the last two (FIELD2D and FIELD2E) do not.

The UNSTRING statement does not initialize the TALLYING data item. The TALLYING data item always contains the sum of its initial contents plus the number of receiving items receiving data. Thus, you might want to initialize the tally count before each use.

You can use the POINTER and TALLYING phrases together in the same UNSTRING statement, but the POINTER phrase must precede the TALLYING phrase. Both phrases must follow all of the item names, the DELIMITER phrase, and the COUNT phrase. The data items for both phrases must contain numeric integers without editing characters or the symbol P in their PICTURE character-strings; both data items can be either COMP or DISPLAY usage. They can be signed or unsigned and, if they are DISPLAY usage, they can contain any desired sign option.

If the UNSTRING operation causes the scan to move past the rightmost position of the sending item (thus exhausting it), the compiler does not execute the OVERFLOW phrase.

       MOVE 1 TO TLY PNTR.
 PAR1. UNSTRING FIELD1 DELIMITED BY ","
                OR CR
                INTO FIELD2(TLY) WITH POINTER PNTR
                TALLYING IN TLY
                ON OVERFLOW GO TO PAR1.