COBOL
COBOL
COBOL
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page ix.
This edition applies to the IBM* ILE* COBOL/400* licensed program (Program 5763-CB1), Version 3 Release 0 Modifi-
cation 5, and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you
are using the proper edition for the level of the product.
Order publications through your IBM representative or the IBM branch serving your locality. Publications are not
stocked at the address given below.
A form for readers’ comments is provided at the back of this publication. If the form has been removed, you may
address your comments to:
You can also send your comments by facsimile (attention: RCF Coordinator), or you can send your comments elec-
tronically to IBM. See “Communicating Your Comments to IBM” for a description of the methods. This page imme-
diately precedes the Readers’ Comment Form at the back of this publication.
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way
it believes appropriate without incurring any obligation to you.
Contents v
Handling Data Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
PICTURE Clauses for Numeric Items . . . . . . . . . . . . . . . . . . . . . 268
Eight-Byte Binary Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Segmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Calling a COBOL Program from a Non-COBOL Program . . . . . . . . . . 268
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
*NORANGE Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
*DUPKEYCHK Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Relative Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Commitment Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Reading without Record Locks . . . . . . . . . . . . . . . . . . . . . . . . . 270
Initializing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Blocking Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Program Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Tracing a Loop in a Program . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Errors That Can Cause a Loop . . . . . . . . . . . . . . . . . . . . . . . . . 271
Appendix D. COBOL/400 Messages, the FIPS Flagger, and SAA Flagging 327
COBOL/400 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Interactive Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Compilation Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Responding to Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
COBOL Message Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
The Federal Information Processing Standard (FIPS) Flagger . . . . . . . . . 331
SAA Flagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Contents vii
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
| these patents. You can send license inquiries, in writing, to the IBM Director of
| Licensing, IBM Corporation, 208 Harbor Drive, Stamford, Connecticut, USA
| 06904-2501
Important changes or additions to the text are indicated by a vertical line (|) to the
left of the change or addition.
This publication contains examples of data and reports used in daily business oper-
ations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
This manual refers to other IBM publications. These publications are listed in the
“Bibliography” on page 383 with their full title and base order number. When they
are referred to in text, a shortened version of the title is used.
Use this manual with the COBOL/400 Reference, SC09-1813, which describes
each component and feature of the COBOL/400 language. The COBOL/400 User’s
Guide, SC09-1812 and the COBOL/400 Reference together describe the
COBOL/400 compiler and language.
For information about the complete library of AS/400 documents, consult the
Publications Guide, GC41-9678, which contains a brief description of the contents
of each AS/400 manual.
Before you use this manual, you should be familiar with the following information:
How to use the controls and indicators on your display and how to use the keys
on your keyboard, such as:
– Cursor movement keys
– Function keys
– Field exit keys
– Insert and Delete keys
– Error Reset key.
For information about your display station, refer to:
– New User’s Guide, SC41-8211.
Portions of this manual are copied from American National Standard Programming
Language COBOL, ANSI X3.23-1985, ISO 1989-1985 and reproduced with permis-
sion from American National Standard Programming Language COBOL, ANSI
X3.23-1985, ISO 1989-1985 (copyright 1985 by the American National Standards
Institute), copies of which you can purchase from the American National Standard
Institute at 1430 Broadway, New York, New York, 10018.
The COBOL/400 Compiler and Library is an IBM licensed program that accepts and
runs COBOL programs that follow the ANSI X3.23-1985 (American National
Standard Programming Language COBOL, ANSI X3.23-1985, ISO 1989-1985)
standard. ANSI is an organization consisting of producers, consumers, and general
interest groups, that establishes the procedures by which accredited organizations
create and maintain voluntary industry standards in the United States.
When you can choose from two or more items, they appear vertically, in a
stack. If you must choose one of the items, one item of the stack appears on
the main path. If choosing an item is optional, the entire stack appears below
the main path:
55───STATEMENT───┬──required choice1──┬─────┬────────────────────┬────5%
└──required choice2──┘ ├──optional choice1──┤
└──optional choice2──┘
An arrow returning to the left above an item indicates that this item can be
repeated:
┌────────────────┐
6 │
55───STATEMENT─────repeatable item──┴─────────────────────────────────5%
Format
.3/
┌──────────┐
.1/ .2/ 6 │
55───STATEMENT──┬──identifier─1──┬──────┬──────────┼───────────────────5
└──literal─1─────┘ └──item─1──┘
5─┬────┬─identifier-3──┬───────────┬─┬─────────────────────────────────5 ±
└─TO─┘ └──ROUNDED──┘ │ ┌────────────────────────┐ .5/
│ 6 .4/ │
└─identifier-4─┬───────────┼──────5 ²
└──ROUNDED──┘
± 5──────────────────────────────────────────────┬─┬─────────────────┬──5%
.6/ │ └──END─STATEMENT──┘
² 5─┬─────────────────────────────────────────┬──┘ .7/
└─┬────┬──SIZE ERROR imperative-statement─┘
└─ON─┘
IBM extensions within figures or tables are shown in boxes unless they are explic-
itly identified as extensions.
Clauses and statements illustrated within syntax diagrams that are COBOL/400 lan-
guage extensions to ANSI X3.23-1985 COBOL are enclosed in double lines, as
follows:
╔══════════════════════════╗
5────RECORD─┬─────┬──┬────┬──┬──╫─EXTERNALLY-DESCRIBED-KEY─╫──┬─────────5
└─KEY─┘ └─IS─┘ │ ╚══════════════════════════╝ │
└────data-name-2─────────────────┘
IBM Extension
COBOL/400 language extensions to ANSI X3.23-1985 COBOL that are part of the
text description are enclosed in IBM Extension bars, like this paragraph.
COBOL clauses and statements illustrated within syntax diagrams that are syntax
checked, but are treated as documentation by the COBOL/400 compiler, are
enclosed by asterisks, as follows:
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
5────┬──────────────────────────────────────────┬─────────────────────────────5
\ └──RESERVE────integer────┬────────────┬────┘ \
\ ├────AREA────┤ \
\ └────AREAS───┘ \
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
CL Entry Codes
The box that appears in the lower right corner of each CL syntax diagram contains
the entry codes that specify the environment in which the command can be
entered. The codes indicate whether or not the command can be:
Used in a batch or interactive job (outside a compiled program; Job:B or I)
Used in a batch or interactive compiled program (Pgm:B or I)
Used in a batch or interactive REXX procedure (REXX:B or I)
Used as a parameter for the CALL CL command, or passed as a character
string to the system program QCMDEXC (Exec).
You can specify various compiler options by using the CRTCBLPGM command, or
by using the PROCESS statement with the desired options. Any options specified
in the PROCESS statement override the corresponding options on the
CRTCBLPGM command. This process is explained in detail in Chapter 3, “Com-
piling a COBOL/400 Program.”
The COBOL/400 compiler provides the following functions for program testing and
debugging:
Debugging features
Formatted dump.
These features allow you to monitor specific program operations during run time.
You must decide what to monitor and what information to retrieve for debugging
purposes.
See Chapter 5, “Debugging Your Program” for more information on debugging fea-
tures.
When your program has ended, the system returns control to whoever called the
program.
For more information on running your program, see Chapter 4, “Running Your
COBOL Program.”
There are two ways to enter a COBOL source program into the system:
You can enter your source program using the Source Entry Utility (SEU). This
is the method documented in this chapter.
You can enter your source program from diskette or tape by using the OS/400
copy function.
Refer to the CL Reference for more information on how to use the COPY func-
tion for entry of the source program from diskette or tape.
To enter your COBOL source program using SEU, enter the Start Source Entry
Utility (STRSEU) command, and specify CBL for the TYPE parameter. Refer to the
SEU User’s Guide and Reference for further information on the STRSEU command
and using SEU.
IBM supplies a source file where you can store your source records if you do not
want to create your own file. This file, named QLBLSRC, is in library QGPL and
has a record length of 92 characters.
Continuation
Area-A Area-B
FILE -CONTROL.
For a complete description of how to enter a source program using SEU, refer to
the SEU User’s Guide and Reference.
Any time a source line is entered or changed, up to 496 lines of source code can
be syntax checked as one unit. The length of a single unit of syntax-checking is
determined by extending from an entered or changed line as follows:
A unit of syntax-checking extends towards the beginning of the source member
until the first source line, or a line that ends in a period is found.
A unit of syntax-checking extends towards the end of the source member until
the last source line, or a line that ends in a period is found.
If this unit spans more than 496 source lines (not including comment lines), the
system responds with an appropriate message.
Syntax checking occurs line by line as you enter the source code. Error messages
are generated by lines consisting of incomplete statements. These disappear when
the statements are completed, as in the example:
ADD A
TO BCD.
An error message is generated after the first line is entered and disappears after
the second line is entered, when the statement is completed. A COBOL sentence
can span a maximum of 496 lines. Also, if a source line is entered or changed, up
to 496 lines of source code can be syntax checked as one unit.
The following regulations apply to syntax checking for COBOL source functions:
Source code on a line with an asterisk (*) or a slash (/) in column 7 is not
syntax checked. An asterisk indicates a comment line; a slash indicates a
comment line and page eject.
No compiler options are honored during syntax checking.
For example, the syntax checker accepts both quotation marks or apostrophes
as nonnumeric delimiters provided they are not mixed within one unit of syntax
checking. The syntax checker does not check if the delimiter is the one that
will be specified in the CRTCBLPGM command for compiling COBOL source
statements, or in the PROCESS statement.
The first sentence following any of the paragraph headers listed below must
begin on the same line as the paragraph header.
PROGRAM-ID.
AUTHOR.
INSTALLATION.
DATE-WRITTEN.
DATE-COMPILED.
SECURITY.
SOURCE-COMPUTER.
OBJECT-COMPUTER.
SPECIAL-NAMES.
Character replacement specified by the CURRENCY and DECIMAL-POINT
clauses of the SPECIAL-NAMES paragraph is not honored during interactive
syntax checking.
When using the REPLACING Identifier-1 BY Identifier-2 clause of the COPY
statement and when either identifier includes reference modification, SEU
checks for matching parentheses only. for more information on reference mod-
ification, see Chapter 11, “COBOL/400 Programming Considerations.”
5──EXEC SQL──sql-statement──END-EXEC.─────────────────────────────5%
If there are errors in the embedded SQL statement as well as errors in the pre-
ceding COBOL statements, the SQL error message will only be displayed after the
preceding COBOL errors are corrected.
For more information about SQL statements, refer to the SQL/400* Reference.
5──EXEC CICS──cics-statement──END-EXEC.─────────────────────────────5%
If the member type for the source program is CICSCBL or CICSSQLCBL, when the
COBOL syntax checker encounters a CICS statement, the COBOL syntax checker
checks for only basic syntax errors.
For more information about CICS/400 statements, refer to the CICS/400 Application
Programming Guide.
You can specify various compiler options by using the CRTCBLPGM command, or
from within the program using the PROCESS statement. Any options specified in
the PROCESS statement override the corresponding options on the CRTCBLPGM
command. The PROCESS statement is discussed later in “Using the PROCESS
Statement to Specify Compiler Options” on page 32.
┌───────────┐ ┌─────────┐
│ COBOL │ │ COBOL │
│ Source ├──────────5COBOL Compiler──┬───────5│ Object │
│ Program │ & & & │ │ Program │
└───────────┘ │ │ │ │ └─────────┘
│ │ 6 │
┌───────────┐ │ │ OS/4ðð │
│ Externally│ │ │ Operating │ ┌────────────────────────┐
│ Described ├───────────┘ │ System └───────5│ Listing │
│ Files │ │ │ - Command summary │
└───────────┘ │ │ - Compiler options │
& │ │ - Source listing │
│ │ │ - Verb usage │
│ │ │ - Data Division map │
┌─────┴─────┐ │ │ - FIPS messages │
│ DDS for │ ┌──────┴─┐ │ - SAA messages │
│ Externally│ │ Copy │ │ - Cross-reference │
│ Described │ │ Source │ │ - Messages │
│ Files │ │ Text │ └────────────────────────┘
└───────────┘ └────────┘
During compilation, the compiler checks the syntax of the COBOL source program
line by line, and also checks the relationships between the lines.
Programming Note: The number of entries in the Object Definition Table (ODT)
and the amount of storage required by a COBOL program varies with the number
and kinds of COBOL statements used in the program. A combination of these
factors can cause the AS/400 internal size limits for the program to be exceeded. If
this occurs, try using the *NOUNREF option of the GENOPT parameter. If the
problem persists, the program must be rewritten.
When the *NOUNREF option is specified, only names that are referenced or are
needed for data structuring are defined. This option is useful when the program
contains many unreferenced identifiers.
Each parameter on this display shows a default value. Move the cursor past the
items where you want default values to apply. Type over any items to set different
values or options. If you are unsure about the setting of a parameter value, type a
question mark (?) in the first position of the field and press Enter, or F4 (Prompt), to
receive more detailed information. The question mark must be followed by a blank.
Figure 3 shows the CRTCBLPGM prompt displays. When you see the first
CRTCBLPGM prompt display, you see only the required parameters prompted. To
see the additional parameters, press F10. You see the first display shown in
Figure 3. To see the remainder of the parameters, as shown in the second and
third displays in Figure 3, page forward.
Additional Parameters
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
á ñ
à@ Create COBOL Program (CRTCBLPGM)
ð
Type choices, press Enter.
Message Limit:
Number of messages . . . . . . \NOMAX 1-9999, \NOMAX
Message limit severity . . . . 29 ð-29
Print file . . . . . . . . . . . QSYSPRT Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB
FIPS flagging . . . . . . . . .
+ for more values
SAA flagging . . . . . . . . . . \NOFLAG \NOFLAG, \FLAG
Extended display options . . . . \DFRWRT, \NODFRWRT...
+ for more values
Flagging severity . . . . . . . ð ð-99
Replace program . . . . . . . . \YES \NO, \YES
Target release . . . . . . . . . \CURRENT \CURRENT, \PRV, V2R1Mð...
User profile . . . . . . . . . . \USER \USER, \OWNER
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
á ñ
à@ Create COBOL Program (CRTCBLPGM)
ð
Type choices, press Enter.
Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
á ñ
Figure 3. The CRTCBLPGM Prompt Displays
All object names specified for the CRTCBLPGM command must follow AS/400 naming conventions: the
names may be basic names, 10 characters in length, composed of alphanumeric characters, the first of
which must be alphabetic; or the names may be quoted names, 8 characters in length, enclosed in double
quotes.
If you want to relate these parameter descriptions to the CRTCBLPGM syntax diagram, refer to Figure 4
on page 29.
source-file-name
Enter the name of the source file that con-
PGM Parameter:
tains the COBOL source to be compiled.
Specifies the program name and library name
This source file should have a record
for the COBOL program object you are cre-
length of 92.
ating. The possible values are:
The possible library values are:
*PGMID
The name for the program object is taken *LIBL
from the PROGRAM-ID paragraph in the If you do not specify a library name, the
COBOL source program. system searches the library list to find the
library where the source file is located.
program-name
Enter a name to identify the compiled *CURLIB
COBOL program. If you specify a The current library is used. If you have
program name for this parameter, and run not assigned a library as the current
the compilation in batch mode, the first library, QGPL is used.
program in the batch job uses this name;
any other programs use the name speci-
library-name
Enter the name of the library where the
fied in the PROGRAM-ID paragraph in the
source file is located.
source program.
SRCMBR Parameter:
The possible library values are:
Specifies the name of the member that con-
*CURLIB tains the COBOL source to be compiled. You
If you do not specify a library name, the can specify this parameter only if the source
current library is used. If you have not file referenced in the SRCFILE parameter is a
assigned a library as the current library, database file. The possible values are:
QGPL is used.
*PGM
library-name If you specified a program name for the
Enter the name of the library to contain PGM parameter, the compiler looks for the
the created program object. source program in a member having the
same name as the program, and creates
SRCFILE Parameter:
an object program with the same name as
Specifies the name of the source file that con-
the program and member.
tains the COBOL source to be compiled. The
possible values are: If you did not specify a program name for
the PGM parameter, the compiler looks for
QLBLSRC the program source in the first member of
Specifies that the source file, QLBLSRC, the database source file, and creates an
contains the COBOL source to be com- object program using the name specified
piled. in the PROGRAM-ID paragraph.
*BLANK
No text is specified. *NOVBSUM
Verb usage counts are not printed.
text-description
Enter the text that briefly describes the *VBSUM
program and its function. The text can be Verb usage counts are printed.
a maximum of 50 characters in length and
must be enclosed in apostrophes. The
apostrophes are not part of the *NONUMBER
50-character string. The source-file sequence numbers are
used for reference numbers.
OPTION Parameter:
Specifies the options to use when the COBOL *NUMBER
source is compiled. The possible values are: The user-supplied sequence numbers
(columns 1 through 6) are used for refer-
*SOURCE or *SRC
ence numbers.
The compiler produces a source listing,
consisting of the COBOL source input and
all compilation-time error messages.
*NOMAP *PRTCORR
The compiler does not list the Data Divi- The compiler inserts comment lines in the
sion map. compiler listing indicating which elemen-
tary items were included as a result of the
*MAP
use of the CORRESPONDING phrase.
The compiler lists the Data Division map.
*NOPRTCORR
The compiler does not insert comment
*NOOPTIONS lines in the compiler listing when the
Options in effect are not listed for this CORRESPONDING phrase is used.
compilation.
*OPTIONS
*NOSRCDBG
Options in effect are listed for this compi-
This option determines the kind of infor-
lation.
mation you see on your programmable
work station when using the CoOperative
Development Environment/400 to compile
*QUOTE
your COBOL programs. See the note on
Specifies that the delimiter quotation mark
page 21 for further information.
(") is used for nonnumeric literals and
Boolean literals. This also specifies that The compiler does not produce source-
the value of the figurative constant level debugging information. If
QUOTE has the EBCDIC value of a quo- *NOLSTDBG is also in effect, the compiler
tation mark. does not produce source-level error infor-
mation either.
Note: Boolean data is a category of data
items that are limited to a value of 1 or 0. *SRCDBG
A Boolean literal is a literal composed of a This option determines the kind of infor-
Boolean character enclosed in quotation mation you see on your programmable
marks and preceded by a B; for example: work station when using the CoOperative
B"1". Development Environment/400 product to
compile your COBOL programs. See the
*APOST
note on page 21 for further information.
Specifies that the delimiter apostrophe (')
is used for nonnumeric literals and The compiler produces source-level error
Boolean literals. This also specifies that information and source-level debugging
the value of the figurative constant information.
QUOTE has the EBCDIC value of an You cannot specify *SRCDBG and
apostrophe. *LSTDBG together. Specify one or the
other.
*ATR
*PRINT Lists the attributes for the IRP source.
The compiler produces a spool listing.
*NOPRINT
The compiler does not produce a spool *RANGE
listing. At runtime, the system verifies that sub-
scripts are within the correct ranges, but
does not verify index ranges. It also
*CRTF
Files that are unavailable at the time of an
*UNREF OPEN operation are created dynamically.
Includes unreferenced data items in the | When created, the file will inherit authority
compiled program. | from the job profile. (See the discussion
*NOUNREF of the OPEN statement in the COBOL/400
Does not include unreferenced data items Reference manual for the conditions under
in the compiled program. This reduces which dynamic file creation can occur.)
the number of ODT (object definition Note: The maximum record length for a
table) entries used, allowing a larger file that will be created dynamically
program to be compiled. The unrefer- is 32 766.
enced data items still appear in the cross-
reference listings produced by specifying
OPTION (*XREF). *NODUPKEYCHK
Does not check for duplicate keys for
INDEXED files.
*NOOPTIMIZE
The compiler performs only standard opti- *DUPKEYCHK
mizations for the program. Checks for duplicate keys for INDEXED
files. (See the discussion of the READ
*OPTIMIZE statement in the COBOL/400 Reference
The compiler attempts to create a | manual for the conditions under which the
program that operates more efficiently and | existence of records with duplicate keys
uses less storage. However, specifying | will be signalled to a program.
*OPTIMIZE can substantially increase the
| Warning: Specifying this option can
time required to compile a program.
| result in a loss in compiler performance.
*NODDSFILLER
*STDERR
If no matching fields are found by a COPY
Standard error handling is used. See
DDS statement, no field descriptions are
Chapter 6, “COBOL/400 Exception and
generated.
message-severity
The possible values for the maximum
*NOGRAPHIC
error severity level are:
DBCS-graphic data types are ignored, and
are declared as FILLER fields. 29 Compilation stops if the number of
errors with severity level 29 or higher
*GRAPHIC
exceeds the maximum number of
Fixed-length DBCS-graphic data types are
error messages specified.
declared as fixed-length alphanumeric
fields, and are accessible to the program. maximum-severity-level
When the *VARCHAR option is also in Specify a one or two-digit number, 0
use, variable-length DBCS-graphic data through 29. Compilation stops if the
types are declared as fixed-length group number of errors with the specified
items, and are accessible to the program. severity level or higher exceeds the
For more information on DBCS-graphic maximum number of error messages
data types, refer to “DBCS-Graphic Fields” you specify.
on page 133. PRTFILE Parameter:
MSGLMT Parameter: Specifies the name of the file to which the
Controls compilation by indicating the compiler listing is directed and the library
maximum number of error messages of a where the file is located. The file should have
given error severity level that can occur before a minimum record length of 132. If a file with
compilation stops. a record length less than 132 is specified,
information is lost.
For example, you can stop compilation if more
than three errors with a severity level of 20 or The possible values are:
higher occur. In this example, you would QSYSPRT
specify 3 for the maximum number of error If you do not specify a file name, the com-
messages, and 20 for the maximum error piler listing is directed to QSYSPRT, an
severity level. If three errors of severity level IBM-supplied file.
20 or higher occur, compilation continues, but
when a fourth is encountered, compilation file-name
stops. If no messages equal or exceed the Enter the name of the file to which the
maximum severity level, compilation continues compiler listing is directed.
regardless of the number of errors encount-
The possible library values are:
ered.
*LIBL
message-limit
If a library-name is not specified, the
The possible values for the maximum
system searches the library list, *LIBL, to
number of error messages are:
find the library where the file is located.
*HIGH *DFRWRT
FIPS flag for high subset. Extended DISPLAY statements are held in
a buffer until an extended ACCEPT state-
ment is encountered, or until the buffer is
*NOSEG filled.
The optional module SEGMENTATION is
If an extended ACCEPT statement is not
not FIPS flagged.
encountered before the buffer is filled, the
*SEG1 contents of the buffer are written to the
FIPS flag for optional module SEGMEN- display. When an extended ACCEPT
TATION level 1 and higher. statement is encountered, the current con-
tents of the buffer are written to the
*SEG2 display.
FIPS flag for optional module SEGMEN-
TATION level 2. *NODFRWRT
Each extended DISPLAY statement is per-
formed as it is encountered.
*NODEB
The optional module DEBUG is not FIPS
flagged. *UNDSPCHR
Displayable and undisplayable characters
*DEB1 are handled by extended ACCEPT and
FIPS flag for optional module DEBUG extended DISPLAY statements.
level 1 and higher.
*NOUNDSPCHR
*DEB2 | Use this option when the data to be dis-
FIPS flag for optional module DEBUG | played contains extended DBCS charac-
level 2. | ters. Only displayable characters are
handled by extended ACCEPT and
extended DISPLAY statements.
*CURRENT
The object is to be used on the release of
*ACCUPDALL
the operating system currently running on
All types of data are predisplayed in the
your system. You can also use the object
extended ACCEPT statements regardless
on a system with any subsequent release
of the existence of the UPDATE phrase.
of the operating system installed.
*ACCUPDNE
*PRV
Only numeric edited data are predisplayed
The object is to be used on the previous
in the extended ACCEPT statements that
release with modification level 0 of the
do not contain the UPDATE phrase.
operating system. You can also use the
FLAG Parameter: object on a system with any subsequent
Specifies the minimum severity level of mes- release of the operating system installed.
sages to be printed. The possible values are:
release-level
0 All messages are printed. Specify the release in the format VxRxMx.
The object can be used on a system with
severity-level the specified release or with any subse-
Enter a one or two-digit number that spec- quent release of the operating system
ifies the minimum severity level of mes- installed.
sages to be printed. Messages that have
severity levels of the specified value or Valid values depend on the current
higher are listed. version, release, and modification level,
and they change with each new release.
REPLACE Parameter:
Specifies if a new program object is created USRPRF Parameter:
when a program object of the same name in Specifies the user profile that will run the com-
the same library already exists. The possible piled COBOL program. The profile of the
values are: program owner or the program user is used to
run the program and control which objects can
*YES be used by the program (including the
A new program object is created and any authority the program has for each object).
existing program object of the same name This parameter is not updated if the program
in the specified library is moved to library already exists. To change the value of
QRPLOBJ. USRPRF, delete the program and recompile
using the correct value.
*NO
A new program object is not created if a The possible values are:
program object of the same name already
*USER
exists in the specified library.
The user profile of the program user is to
TGTRLS Parameter: be used when the program is run.
Specifies the release of the operating system
*OWNER
on which you intend to use the object being
The user profiles of both the program’s
created. You can specify an exact release
owner and user are to be used when the
level in the format VxRxMx, where Vx is the
program is run. The collective sets of
version, Rx is the release, and Mx is the mod-
Example 1
CRTCBLPGM SRCFILE(QGPL/QLBLSRC) SRCMBR(SAMPLE) SAAFLAG(\FLAG)
Example 2
CRTCBLPGM PGM(TEST) SRCFILE(SOURCE1) CVTOPT(\GRAPHIC)
In the preceding example, the compiler looks for the file SOURCE1 in the library
list, and looks for the member called TEST within that file. (The value for the
SRCMBR parameter defaulted to *PGM, specifying to look for a member with the
same name as the program to be created.) The compiler creates a COBOL/400
program called TEST from the source program found in the member TEST in the
file SOURCE1. Specifying *GRAPHIC for the CVTOPT parameter indicates that if
the DDS contains DBCS-graphic data types, you want the COBOL program to be
able to reference them as alphanumeric fields.
55──CRTCBLPGM───PGM──(─┬─\CURLIB/──────┬─┬─\PGMID───────┬─)───────────────────5
└─library-name/─┘ └─program-name─┘
5───────────┬────────────────────────────────────────────────────────────┬────5
└─SRCFILE──(──┬─\LIBL/────────┬──────┬─QLBLSRC──────────┬──)─┘
├─\CURLIB/──────┤ └─source-file-name─┘
└─library-name/─┘
5───────────┬─────────────────────────────────────────┬───────────────────────5
└─SRCMBR──(─┬─\PGM────────────────────┬─)─┘
└─source-file-member-name─┘
5───────────┬────────────────────────────┬───┬────────────────────────────┬───5
└─OPTION──(─option-details─)─┘ └─GENOPT──(─genopt-details─)─┘
5───────────┬──────────────────────────────────────────────────────────────┬──5
└─CVTOPT────(─┬─\NOVARCHAR─┬──┬─\NODATETIME─┬──┬─\NOGRAPHIC─┬─)┘
└─\VARCHAR───┘ └─\DATETIME───┘ └─\GRAPHIC───┘
5───────────┬───────────────────────────────────────────────────────────┬─────5
└─MSGLMT──(─┬──\NOMAX─────────┬───┬──29─────────────────┬─)─┘
└──message-limit──┘ └──max-severity-level─┘
5───────────┬────────────────────────────────┬────────────────────────────────5
└─GENLVL──(─┬─29─────────────┬─)─┘
└─severity-level─┘
5───────────┬─────────────────────────────────────────────────┬───────────────5
└─PRTFILE──(─┬─\LIBL/─────────┬──┬─QSYSPRT───┬─)──┘
├─\CURLIB/───────┤ └─file-name─┘
└─library-name/──┘
5───────────┬──────────────────────────────────────────────────────────────┬──5
└─FLAGSTD─(─┬\NOFIPS──────┬─┬\NOSEG┬─┬\NODEB┬─┬\NOOBSOLETE─┬─)─┘
├\MINIMUM─────┤ ├\SEG1─┤ ├\DEB1─┤ └\OBSOLETE───┘
├\INTERMEDIATE┤ └\SEG2─┘ └\DEB2─┘
└\HIGH────────┘
5───────────┬──────────────────────────┬──────────────────────────────────────5
└─SAAFLAG──(─┬─\NOFLAG─┬─)─┘
└─\FLAG───┘
5───────────┬───────────────────────────────────────────────────────────────┬─5
└─EXTDSPOPT─(─┬─\DFRWRT───┬───┬─\UNDSPCHR───┬──┬─\ACCUPDALL─┬─)─┘
└─\NODFRWRT─┘ └─\NOUNDSPCHR─┘ └─\ACCUPDNE──┘
5───────────┬──────────────────────────────┬──────┬─────────────────────┬─────5
└─FLAG──(─┬─ð──────────────┬─)─┘ └─REPLACE─(─┬─\YES─┬)─┘
└─severity-level─┘ └─\NO──┘
5───────────┬──────────────────────────────────────┬──────────────────────────5
└─AUT──(─┬─\LIBCRTAUT──────────────┬─)─┘
├─\ALL────────────────────┤
├─\CHANGE─────────────────┤
├─\USE────────────────────┤
├─\EXCLUDE────────────────┤
└─authorization-list-name─┘
5───────────┬──────────────────────────────────────┬──────────────────────────5
└─TEXT──(─┬─\SRCMBRTXT───────────┬─)───┘
├─\BLANK───────────────┤
└─'description-text'───┘
5───────────┬───────────────────────────────────────────────────────────┬─────5
└─DUMP──(───starting-statement───────ending-statement───)───┘
5───────────┬───────────────────────┬────────────────────────────────────────5%
└─ITDUMP─(─dump-option─)┘
┌───────────────────────────────────┐
│Job: B,I Pgm: B,I REXX: B,I Exec│
└───────────────────────────────────┘
OPTION Details:
5──┬─\SRC──────┬─┬─\NOXREF─┬─┬─\GEN─────┬─┬─\NOSEQUENCE─┬─┬─\NOVBSUM────┬─────5
├─\SOURCE───┤ └─\XREF───┘ └─\NOGEN───┘ └─\SEQUENCE───┘ └─\VBSUM──────┘
├─\NOSRC────┤
└─\NOSOURCE─┘
5──┬─\NONUMBER───┬─┬─\NOMAP──┬─┬─\NOOPTIONS┬─┬───\QUOTE────┬─┬─\NOSECLVL───┬──5
├─\NUMBER─────┤ └─\MAP────┘ └─\OPTIONS──┘ └───\APOST────┘ └─\SECLVL─────┘
└─\LINENUMBER─┘
5──┬─\PRTCORR───┬─┬─\NOSRCDBG──┬─┬──\NOLSTDBG──┬─┬─\PRINT──────┬──────────────5
└─\NOPRTCORR─┘ └─\SRCDBG────┘ └──\LSTDBG────┘ └─\NOPRINT────┘
GENOPT Details:
5──┬─\NOLIST─┬───┬─\NOXREF─┬───┬─\NOPATCH─┬───┬─\NODUMP─┬───┬─\NOATR─┬────────5
└─\LIST───┘ └─\XREF───┘ └─\PATCH───┘ └─\DUMP───┘ └─\ATR───┘
5──┬─\RANGE───┬─┬\UNREF───┬─┬\NOOPTIMIZE─┬─┬\NODDSFILLER─┬─┬─\NOSYNC─┬────────5
└─\NORANGE─┘ └\NOUNREF─┘ └\OPTIMIZE───┘ └\DDSFILLER───┘ └─\SYNC───┘
5──┬─\NOCRTF─┬───┬─\NODUPKEYCHK─┬───┬─\STDERR────┬───┬─\NOEXTACCDSP──┬────────5
└─\CRTF───┘ └─\DUPKEYCHK───┘ └─\NOSTDERR──┘ └─\EXTACCDSP────┘
5──┬─\NOINZDLT──┬──┬──\NOBLK────┬───┬──\STDINZ───┬───┬─\FS21DUPKY────┬────────5
└─\INZDLT────┘ └──\BLK──────┘ └──\NOSTDINZ─┘ └─\NOFS21DUPKY──┘
For more information about the TGTRLS parameter, see page 26.
Format
┌─────────┐
6 │
55───PROCESS────option-1──┴─────┬─────┬────────────────────────────────5%
└──.──┘
The EXTDSPOPT option on the PROCESS statement should be coded with the
associated options in brackets similar to FLAG(nn) syntax. You can specify more
than one option within the brackets for the EXTDSPOPT option. For example, to
specify DFRWRT and UNDSPCHR, type
EXTDSPOPT(DFRWRT UNDSPCHR)
It is also valid to specify EXTDSPOPT or EXTDSPOPT( ).
When EXTDSPOPT alone is specified in the PROCESS statement, then all the
default values for the additional options are in effect.
If conflicting options are specified, the last option specified overrides the others.
All object programs are stored in the library specified on the PGM parameter. If
program-name is specified for the PGM parameter, the first program in the batch
job has that name, and all other programs use the name specified in the
PROGRAM-ID paragraph in the source program.
The Format 1 COPY statement can be used within the PROCESS statement to
retrieve compiler options previously stored in a source library, and include them in
the PROCESS statement. COPY can be used to include options that override
those specified as defaults by the compiler. Any PROCESS statement options can
be retrieved with the COPY statement.
Compiler options can both precede and follow the COPY statement within the
PROCESS statement. The last encountered occurrence of an option overrides all
preceding occurrences of that option.
IBM Extension
If you specify the EJECT statement in your program, the next source statement
prints at the top of the next page in the compiler listing. This statement may be
written anywhere in Area A or Area B and must be the only statement on the line.
The SKIP1/2/3 statement causes blank lines to be inserted in the compiler listing.
A SKIP1/2/3 statement can be written anywhere in Area A or B. It must be the only
statement on the line.
SKIP1 inserts a single blank line (double spacing).
SKIP2 inserts two blank lines (triple spacing).
SKIP3 inserts three blank lines (quadruple spacing).
Each of the above SKIP statements causes a single insertion of one, two, or three
lines.
You can selectively list or suppress your COBOL source statements by using the
*CONTROL, *CBL, or COPY statements:
*CONTROL NOSOURCE and *CBL NOSOURCE suppress the listing of source
statements.
*CONTROL SOURCE and *CBL SOURCE continue the listing of source state-
ments.
A COPY statement bearing the SUPPRESS phrase suppresses the listing of
copied statements. For its duration, this statement overrides any *CONTROL
or *CBL statement. If the copied member contains *CONTROL or *CBL state-
ments, the last one runs once the COPY member has been processed.
Refer to the COBOL/400 Reference for additional information about the EJECT,
SKIP1/2/3, *CONTROL, *CBL, COPY, and TITLE statements.
Time-Separation Characters
The TIMSEP parameter of job-related commands (such as CHGJOB) now specifies
the time-separation character used in the time stamps that appear on compiler
listings. In the absence of a TIMSEP value, the system value QTIMSEP is used by
default.
à@ ð
Columns . . . : 1 71 Edit XMPLIB/QLBLSRC
SEU==> XMPLE
FMT CB ......-A+++B+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ðð14.ðð DATA DIVISION.
ðð15.ðð FILE SECTION.
ðð16.ðð FD FILE1
ðð17.ðð RECORD CONTAINS 56 CHARACTERS
ðð18.ðð LABEL RECORDS ARE OMITTED
ðð19.ðð DATA RECORD IS REB-1.
ðð2ð.ðð ð1 REC-1 PIC X(56).
_______________________________________________________________________________
Columns . . . : 1 71 Browse Spool file . . : XMPLE
SEU==>
ðððð.5ð STMT
ðððð.51 \ 19 MSGID: LBL1327 SEVERITY: 3ð SEQNBR: ðð19ðð
ðððð.52 Message . . . . : 'REB-1' not defined in the program. Clause
ðððð.53 ignored.
ðððð.54 \ \ \ \ \ E N D O F M E S S A G E S \ \
ðððð.55 Message Summary
ðððð.56 Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39)
While browsing the compiler listing, you can scan for errors and correct those
source statements that have errors. To scan for errors, type F \ERR on the SEU
command line.
For complete information on browsing through a compiler listing, see the SEU
User’s Guide and Reference.
Command Summary
This summary, which is produced as a result of compilation, lists all options speci-
fied in the CRTCBLPGM command. Refer to “Using the Create COBOL Program
(CRTCBLPGM) Command” on page 15 for more information about user-defined
options.
Source Listing
Figure 8 illustrates a source listing. The statements in the source program are
listed exactly as submitted. The source is not listed if the NOSOURCE option is
specified. After the page in which the PROGRAM-ID paragraph is listed, all com-
piler output pages have the program-id name listed in the heading before the
system name.
.C/ Sequence error indicator column: An S in this column indicates that the
line is out of sequence. Sequence checking is performed on the reference
number field only if the SEQUENCE option is specified.
.D/ Copyname: The copyname, as specified in the COBOL COPY statement,
is listed here for all records included in the source program by that COPY
statement. If the DDS-ALL-FORMATS phrase is used, the name
<--ALL-FMTS appears under COPYNAME.
.E/ Change/date field: The date the line was last modified is listed here.
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Data Division Map TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 7
STMT LVL SOURCE NAME SECTION DISP LENGTH TYPE I-NAME ATTRIBUTES
.F/ .G/ .H/ .I/ .J/ .K/ .L/ .M/ .N/
18 FD FILE-1 FS .Fð1 DEVICE DISK, ORGANIZATION SEQUENTIAL,
ACCESS SEQUENTIAL, RECORD CONTAINS 2ð
CHARACTERS, LABEL RECORDS STANDARD
22 ð1 RECORD-1 FS ðððððððð 2ð GROUP .Dðð633C
23 ð2 FIELD-A FS ðððððððð 2ð AN .Dðð63AE
25 ð1 FILLER WS ðððððððð 56 GROUP .Dðð642ð
26 ð2 KOUNT WS ðððððððð 2 PACKED .Dðð649ð
27 ð2 LETTERS WS ððððððð2 26 AN .Dðð6512 VALUE
28 ð2 ALPHA WS ððððððð2 1 AN .Dðð65Bð REDEFINES .Dðð6512, DIMENSION(26)
3ð ð2 NUMBR WS ðððððð28 2 PACKED .Dðð6632
31 ð2 DEPENDENTS WS ðððððð3ð 26 AN .Dðð66B4 VALUE
32 ð2 DEPEND WS ðððððð3ð 1 AN .Dðð6754 REDEFINES .Dðð66B4, DIMENSION(26)
35 ð1 WORK-RECORD WS ðððððððð 19 GROUP .Dðð67D6
36 ð2 NAME-FIELD WS ðððððððð 1 AN .Dðð684C
37 ð2 FILLER WS ððððððð1 1 AN .Dðð68Cð VALUE
38 ð2 RECORD-NO WS ððððððð2 3 ZONED .Dðð693C
39 ð2 FILLER WS ððððððð5 1 AN .Dðð69C2 VALUE
4ð ð2 LOCATION WS ððððððð6 3 A .Dðð7A98 VALUE
41 ð2 FILLER WS ððððððð9 1 AN .Dðð7B2ð VALUE
42 ð2 NO-OF-DEPENDENTS WS ðððððð1ð 2 AN .Dðð7B9C
44 ð2 FILLER WS ðððððð12 7 AN .Dðð7C16 VALUE
45 77 WORKPTR WS ðððððððð 16 POINTR .Dðð7C92
FILE SECTION uses 2ð bytes of storage
WORKING-STORAGE SECTION uses 75 bytes of storage
\ \ \ \ \ E N D O F D A T A D I V I S I O N M A P \ \ \ \ \
.M/ Internal name: The compiler-generated internal names are listed here and
are assigned as follows:
File names
The internal name uses the form .Fnn, where .F indicates a file name, and
nn is a unique two-digit number.
Data names
The internal name uses the form .Dxxxxxx, where .D indicates a data name
or index name, and xxxxxx is a unique six-digit hex value. These names
appear in the IRP listing if generated.
.N/ Attributes: The attributes of the item are listed here as follows:
For files, the following information can be given:
Device type
ORGANIZATION
ACCESS MODE
BLOCK CONTAINS information
RECORD CONTAINS information
LABEL information
RERUN is indicated
SAME AREA is indicated
CODE-SET is indicated
SAME RECORD AREA is indicated
LINAGE is indicated.
FIPS Messages
The FIPS messages, Figure 11, are listed when the FLAGSTD parameter is speci-
fied. See page 25 for more information about specifying the option for FIPS flag-
ging. Only messages for the requested FIPS subset, optional modules and/or
obsolete elements are listed.
Note: The sequence number and column number are given for each time the
message is issued.
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL FIPS Messages TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 8
FIPS-ID DESCRIPTION AND SEQUENCE NUMBERS FLAGGED.P/
.O/
LBL82ðð Following nonconforming standard items valid only at FIPS intermediate level or higher.
LBL82ð1 COPY statement.
ðð34ðð ððð8
LBL83ðð Following nonconforming standard items valid only at FIPS high level. .Q/
LBL83ð3 DATE-COMPILED paragraph.
ððð8ðð ðð1ð
LBL85ðð Following nonconforming nonstandard items are IBM-defined or are IBM extensions. .Q/
LBL85ð4 Assignment-name in ASSIGN clause.
ðð15ðð ðð36
LBL8518 USAGE IS COMPUTATIONAL-3.
ðð26ðð ðð36
ðð3ððð ðð36
LBL852ð USAGE IS POINTER.
ðð35ðð ðð26
LBL8561 COPY statement with default library assumed.
ðð34ðð ðð19
7 FIPS violations flagged..R/
\ \ \ \ \ E N D O F C O B O L F I P S M E S S A G E S \ \ \ \ \
Option Heading
NONUMBER DESCRIPTION AND SEQUENCE NUMBERS FLAGGED
NUMBER DESCRIPTION AND USER-SUPPLIED NUMBERS
FLAGGED
LINENUMBER DESCRIPTION AND LINE NUMBERS FLAGGED
.Q/ Items grouped by level: These headings subdivide the FIPS messages by
level and category.
.R/ FIPS violations flagged: The total number of FIPS violations flagged is
included at the end of the FIPS listing.
SAA Messages
Figure 12 shows the SAA messages that are listed when you specify the SAA flag-
ging option. See the SAAFLAG parameter on page 25 or “Using the PROCESS
Statement to Specify Compiler Options” on page 32 for more information about
specifying this option.
5763CB1 V3RðM5 ðð1ððð SAA COBOL Messages TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 9
MSGID DESCRIPTION, SEQUENCE NUMBERS and COLUMN NUMBERS FLAGGED
LBL88ðð The following items have been flagged as non-portable across other SAA COBOL systems.
LBL88ð1 Options APOST,NUMBER,SEQUENCE,GRAPHIC,NOCRTF,NODUPKEYCHK,NOSYNC and EXTACCDSP are not SAA COBOL.
ððð1ðð ððð8
LBL88ð9 PROCESS statement.
ððð1ðð ððð8
LBL8843 USAGE IS POINTER.
ðð35ðð ðð26
3 SAA COBOL Messages were flagged.
\ \ \ \ \ E N D O F S A A C O B O L M E S S A G E S \ \ \ \ \
For more information about SAA flagging, see “SAA Flagging” on page 333.
Cross-Reference Listing
Figure 13 shows the cross-reference listing, which is produced when the XREF
option is specified. It provides a list of all data references and procedure-name
references, by statement number, within the source program.
Messages
Figure 14 shows the messages that are generated during program compilation.
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Messages TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 11
STMT .X/
\.V/ 18 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ðð18ðð .W/
Message . . . . : Blocking/Deblocking for file 'FILE-1' will
be performed by compiler-generated code. .Y/
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
.Z/ 1 1 ð ð ð ð
Source records read . . . . . . . . : 79
Copy records read . . . . . . . . . : 1ð
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program SAMPLE created in library TESTER.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \
When a message is issued for a record from a copy file, the number is
preceded by a +.
.X/ MSGID and Severity Level: These fields contain the message number and
its associated severity level. Severity levels are defined as follows:
ðð Informational
1ð Warning
2ð Error
3ð Severe Error
4ð Unrecoverable (usually a user error)
5ð Unrecoverable (usually a compiler error)
.Y/ Message: The message identifies the condition and indicates the action
taken by the compiler.
.Z/ Message statistics: This field lists the total number of messages and the
number of messages by severity level.
The totals listed are the number of messages generated for each severity
by the compiler and are not always the number listed. For example, if
FLAG(10) is specified, no messages of severity less than 10 are listed.
The counts, however, do indicate the number that would have been printed
if they had not been suppressed.
1 The statement number and the reference number do not appear on certain messages that reference missing items. For example,
if the PROGRAM-ID paragraph is missing, message LBL0031 appears on the listing with no statement or reference number listed.
You can use a CL CALL command interactively, as part of a batch job, or include it
in a CL program. An example of a CL CALL command is CALL PAYROLL.
PAYROLL is the name of a COBOL program that is called and run.
Any COBOL program can call another program with the COBOL CALL statement.
(See the “CALL Statement” section of the COBOL/400 Reference for more informa-
tion.)
à@ ð
PAYROLL DEPARTMENT MENU
Option:____
You can also create a command yourself to run a COBOL program by using a
command definition. A command definition is an object that contains the defi-
nition of a command (including the command name, parameter descriptions, and
validity-checking information), and identifies the program that performs the function
requested by the command. The system-recognized identifier for the object is
*CMD.
For example, you can create a command, PAY, that calls a program, PAYROLL.
PAYROLL is the name of a COBOL program that is called and run. You can enter
the command interactively, or in a batch job. See the CL Programmer’s Guide for
further information about using the command definition.
When a COBOL program ends normally, the system returns control to the caller.
The caller could be a work station user, a CL program (such as the menu-handling
program), or another COBOL program.
If a program ends for any reason other than by the use of the STOP statement or
by falling through to the end of the program, the return code is set to 2. See the
RTVJOBA and DSPJOB commands in the CL Programmer’s Guide for more infor-
mation about return codes.
When you are running a batch job that uses the ACCEPT statement, the input data
is taken from the job stream. This data must be placed immediately following the
CL CALL for the COBOL program. It is your responsibility to request (through mul-
tiple ACCEPT statements) the same amount of data as is available. See the
“ACCEPT Statement” section of the COBOL/400 Reference for more information.
Note: If more data is requested than is available, the CL command following the
data is treated as input data. If more data is available than is requested,
each extra line of data is treated as a CL command. In each instance,
undesirable results can occur.
You can add the inquiry messages to a system reply list to provide automatic
replies to the messages. The replies for these messages may be specified individ-
ually or generally. This method of replying to inquiry messages is especially suit-
able for batch programs, which would otherwise require an operator to issue
replies.
You can add the following COBOL/400 inquiry messages to the system reply list:
LBE7200
LBE7201
LBE7203
LBE7204
LBE7205
LBE7206
LBE7207
LBE7208
LBE7209
LBE7210
LBE7211
LBE7604.
The reply list is only used when an inquiry message is sent by a job that has the
Inquiry Message Reply (INQMSGRPY) attribute specified as INQMSGRPY(\SYSRPYL).
You can use the Add Reply List Entry (ADDRPYLE) command to add entries to the
system reply list, or the Work with Reply List Entry (WRKRPYLE) command to
change or remove entries in the system reply list. See the CL Reference for details
of the ADDRPYLE and WRKRPYLE commands. You can also reply to runtime
inquiry messages with a user-defined error-handler. For more information about
error-handling APIs, refer to the System Programmer’s Interface Reference.
The OS/400 functions let you test programs while protecting your production files,
and let you observe and debug operations as a program runs. No special source
code is required for using the OS/400 functions.
Source code is required for using COBOL debugging features and formatted dump
capability. A formatted dump can also be obtained by a user’s response to a run-
time message.
While testing your programs, ensure that your library list is changed to direct the
programs to a test library containing test data so that any existing real data is not
affected.
No special statements for testing are contained in the program being tested. The
program can be run normally without modification. All testing functions are speci-
fied in the job that contains the program, not in the actual program.
Testing functions apply only to the job in which they are specified. A program can
be used concurrently in two jobs: one job that is in a test environment and another
that is in a normal processing environment.
Testing functions allow you to observe the operations being performed while the
program is running. These functions include using breakpoints and traces. (See
“Using Breakpoints” on page 57 and “Using a Trace” on page 64 for more informa-
tion.)
The compiler can detect errors when compiling your source program. While it
makes corrections based on assumptions about certain errors it finds, you still need
to correct the source and compile again if you have errors.
The following errors appear only when you run your program:
Failing to match the record description in your source program with the format
of the actual records on the file to be read. This can either be an error by you
(the records are correct, but your description is incorrect) or an error by the
person who created the records your program reads. (For example, your
description is correct, but one or more records were entered incorrectly.)
Moving a data item whose subscript or index is too large, is negative, or is 0.
Such a move could overlay and destroy part of your code or could fetch faulty
data.
Forgetting to define a sign field for items that can hold negative values. (In
such a case, the sign is lost, and the negative number mistakenly becomes
positive.)
Moving data into an area too small for it, causing unwanted truncation.
Forgetting to initialize the data items in the Working-Storage section before they
are used. This may result in a decimal data error.
In a called program, incorrectly matching the data descriptions in the Linkage
Section with those of the caller. Or, in the calling program, incorrectly identi-
fying the data to be passed.
Moving a group item to another group item when the subordinate data
descriptions are incompatible.
Specifying USAGE for a redefined data item that is different from the USAGE
originally specified for the redefined item, and then forgetting about the change
once the redefinition takes place.
Including a GO TO statement with no procedure name, and failing to initialize it
with an ALTER statement before the running program reaches that point.
Failing to include the AT END or INVALID KEY clauses or the USE procedures
on files described in the program.
Failing to match the TRANSACTION file source record description with the
display format record description.
When a breakpoint statement is about to be run for an interactive job, the system
displays the breakpoint at which the program has stopped and, if requested, the
values of program variables. After you get this information (in a display), you can
go to a Command Entry display and then enter OS/400 commands to request other
functions (such as displaying or changing a variable, adding a breakpoint, or adding
a trace). See the CL Programmer’s Guide for more information on breakpoint con-
cepts.
For a batch job, a breakpoint program can be called when a breakpoint is reached.
The breakpoint information is passed to the breakpoint program.
OS/400 Commands:
STRDBG TESTPRT
ADDBKP STMT(43)
ADDBKP STMT(52)
PGMVAR(KOUNT)
.1/ The first breakpoint shows you where you are in the program. The following
information is displayed when the break occurs:
à@ Display Breakpoint
ð
Statement/Instruction . . . . . . . . . : 43 /ðð17
Program . . . . . . . . . . . . . . . . : TESTPRT
Recursion level . . . . . . . . . . . . : 1
á ñ
Figure 17. First Breakpoint Displayed
à@ Display Breakpoint
ð
Statement/Instruction . . . . . . . . . : 52 /ðð56
Program . . . . . . . . . . . . . . . . : TESTPRT
Recursion level . . . . . . . . . . . . : 1
Start position . . . . . . . . . . . . : 1
Format. . . . . . . . . . . . . . . . . : \CHAR
Length. . . . . . . . . . . . . . . . . : \DCL
Variable. . . . . . . . . . . . . . . . : ð5 KOUNT
Type. . . . . . . . . . . . . . . . . : PACKED
Length. . . . . . . . . . . . . . . . : 2 ð
' 26'
á ñ
Figure 18. Second Breakpoint Displayed
To specify a variable for the PGMVAR parameter, begin every name you enter with
an alphanumeric character (A through Z, $, #, or @). It can be followed by the
characters (A through Z, 0 though 9, $, #, @, or _ ).
STRDBG TESTPRT
ADDBKP STMT(58)
PGMVAR('RECORD-NO')
To display the value of a table element, enter the appropriate occurrence numbers
(subscripts) with the variable name. Up to seven dimensions of subscripting are
allowed, and the subscripts must be separated by commas.
The following example shows how to specify the COBOL variable TABLE1 with
three dimensions.
One or more blanks are allowed after each comma separating subscripts, but the
total length of the variable plus subscripts, parentheses, commas, and blanks speci-
fied with the PGMVAR keyword cannot exceed 132 characters. For more informa-
tion on how to code variables in CL commands, see the CL Reference.
PGMVAR('NAME-FIELD OF WORK-RECORD')
Another technique can be used to display variables that are not elements of a
multi-dimensional table. For example, to display the field NAME-FIELD, you can
use the COBOL Data Division map to find its COBOL internal name (I-NAME).
Next, use the IRP cross-reference listing to find the Object Definition Table (ODT)
number for the internal-name. (See “Using the PROCESS Statement to Specify
Compiler Options” on page 32 for information on how to obtain these listings.)
Figure 19 shows the Data Division map, and Figure 20 on page 62 shows the
cross-reference listing for the program example, TESTPRT.
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Data Division Map TESTER/TESTPRT AS4ððSYS ð3/3ð/94 17:ð5:37 Page 4
STMT LVL SOURCE NAME SECTION DISP LENGTH TYPE I-NAME ATTRIBUTES
16 FD FILE-1 FS .Fð1 DEVICE DISK, ORGANIZATION SEQUENTIAL,
ACCESS SEQUENTIAL, RECORD CONTAINS 2ð
CHARACTERS, LABEL RECORDS STANDARD
2ð ð1 RECORD-1 FS ðððððððð 2ð GROUP .Dðð633C
21 ð2 FIELD-A FS ðððððððð 2ð AN .Dðð63AE
23 ð1 FILLER WS ðððððððð 56 GROUP .Dðð642ð
24 ð2 KOUNT WS ðððððððð 2 PACKED .Dðð649ð
25 ð2 LETTERS WS ððððððð2 26 AN .Dðð6512 VALUE
26 ð2 ALPHA WS ððððððð2 1 AN .Dðð65Bð REDEFINES .Dðð6512, DIMENSION(26)
28 ð2 NUMBR WS ðððððð28 2 PACKED .Dðð6632
29 ð2 DEPENDENTS WS ðððððð3ð 26 AN .Dðð66B4 VALUE
3ð ð2 DEPEND WS ðððððð3ð 1 AN .Dðð6754 REDEFINES .Dðð66B4, DIMENSION(26)
32 ð1 WORK-RECORD WS ðððððððð 19 GROUP .Dðð67D6
33 ð2 NAME-FIELD WS ðððððððð 1 AN .Dðð684C .1/
34 ð2 FILLER WS ððððððð1 1 AN .Dðð68Cð VALUE
35 ð2 RECORD-NO WS ððððððð2 3 ZONED .Dðð693C
36 ð2 FILLER WS ððððððð5 1 AN .Dðð69C2 VALUE
37 ð2 LOCATION WS ððððððð6 3 A .Dðð6A98 VALUE
38 ð2 FILLER WS ððððððð9 1 AN .Dðð6B2ð VALUE
39 ð2 NO-OF-DEPENDENTS WS ðððððð1ð 2 AN .Dðð6B9C
41 ð2 FILLER WS ðððððð12 7 AN .Dðð6C16 VALUE
FILE SECTION uses 2ð bytes of storage
WORKING-STORAGE SECTION uses 75 bytes of storage
\ \ \ \ \ E N D O F D A T A D I V I S I O N M A P \ \ \ \ \
Now you can use ODT number 021C (for NAME-FIELD), with the following com-
mands, to add a breakpoint to the program example at statement 52.
STRDBG TESTPRT
ADDBKP STMT(52)
PGMVAR('/ð21C')
à@ Display Breakpoint
ð
Statement/Instruction . . . . . . . . . : 52 /ðð56
Program . . . . . . . . . . . . . . . . : TESTPRT
Recursion level . . . . . . . . . . . . : 1
Start position. . . . . . . . . . . . . : 1
Format. . . . . . . . . . . . . . . . . : \CHAR
Length. . . . . . . . . . . . . . . . . : \DCL
proc=display.
Variable. . . . . . . . . . . . . . . . : /ð21C
Type. . . . . . . . . . . . . . . . . : CHARACTER
Length. . . . . . . . . . . . . . . . : 2
\...+....1....+....2....+....3....+....4....+....5
'Z'
á ñ
Figure 21. Breakpoint at Statement 52
You can use the DSPPGMVAR command to display pointer data items, but you
cannot use CHGPGMVAR to change pointer data items. To change pointer data
items, you use the CHGHLLPTR or CHGPTR commands. For more information on
the CHGHLLPTR and CHGPTR commands, refer to the CL Reference.
Using a Trace
A trace is a record of some or all of the statements run in a program. If requested,
a trace also records the values of specific variables used in the program state-
ments.
Program Trace
┌─────────────┐ ┌─────────────────────────────────────┐
│ Statement │ │ Processing Order Variables │
│ 1 ...... │ │ 1 ─────────5 ....... │
│ 2 ...... │ │ 6 ─────────5 ....... │
│ 3 ...... │ │ 7 ─────────5 ....... │
│ 4 ...... │ │ 8 ─────────5 ....... │
│ 5 ...... │ │ 6 ─────────5 ....... │
│ 6 ...... │ │ 7 ─────────5 ....... │
│ 7 ...... │ │ 2 ─────────5 ....... │
│ 8 ...... │ │ 6 ─────────5 ....... │
│ . │ │ 7 ─────────5 ....... │
│ . │ │ . │
│ . │ │ . │
│ │ │ │
│ │ │ │
└─────────────┘ └─────────────────────────────────────┘
A trace differs from a breakpoint because the number of statements involved in the
trace affects where the trace will end. The system records all the traced state-
ments that were processed. You can request a display of the traced information,
which shows the sequence in which the statements were processed and, if
requested, the values of the variables used in the statements.
You specify which statements the system will trace. You can also specify that vari-
ables be displayed only when their value has changed since the last trace state-
ment was run.
If you choose the F option, the dump also includes a list of compiler-generated
fields and their contents.
Both the D option and the F option will dump the first 256 characters of program
variables. Any variable greater than 256 characters will be truncated.
If you do not want a dump, specify C (cancel with no dump). Reply C is also the
default reply for all COBOL inquiry messages that allow a dump.
For more information about reply modes see “Replying to Run-Time Inquiry
Messages” on page 52.
The output for the dump is sent to the IBM-supplied printer file QPPGMDMP.
The COBOL/400 compiler provides two error-handling methods: standard and non-
standard. Standard error handling is not available on compilers released earlier
than Version 1 Release 3.
Release Sensitivity!
During arithmetic operations, typical errors are size (MCH1210) errors and decimal
data (MCH1202) errors; the corresponding error-handling phrase is the SIZE
ERROR phrase.
Most MCH errors are not directly detected by COBOL; they are detected by the
operating system and result in system messages. COBOL then monitors for these
messages, setting internal bits that determine whether to run a SIZE ERROR
imperative statement or issue a run-time message (LBE7200) to end the program.
COBOL does detect errors that result from division by zero during an arithmetic
operation. If detected by COBOL, these errors cause the SIZE ERROR imperative
statement to run.
System message MCH1210 occurs when you move a numeric field to a receiver
that is too small. This error is monitored by COBOL, and also results in the running
of the SIZE ERROR imperative statement.
For I/O operations, there are several important error handling phrases and clauses.
These are the AT END/INVALID KEY and NO DATA phrases (coded at the COBOL
statement level), the USE procedure, and the FILE STATUS clause (coded at the
file level). During arithmetic and I/O operations, errors are detected by the system,
which sends messages; the messages are then monitored by COBOL. Similar to
the case of an error that results from division by zero, COBOL does detect some
errors during an I/O operation. Regardless of how an error is detected during an
| I/O operation, the result will always be an internal file status in which the first char-
| acter is not zero, run-time message, or both.
The Retrieve COBOL Error Handler (QLRRTVCE) API allows you to retrieve the
name of the current or pending COBOL error-handling program. You can call it
from any programming language.
The Set COBOL Error Handler (QLRSETCE) API allows you to specify the identity
of a COBOL error-handling program. You can call it from any programming lan-
guage.
You can also use the Change COBOL Main Program (QLRCHGCM) API to create
multiple run units, each with its own error handler.
For detailed information on all of these APIs, refer to the System Programmer’s
Interface Reference.
The FILE STATUS clause designates one or two data items (coded in the
WORKING-STORAGE section) to hold a copy of the result of an I/O operation.
Your copy of the first of these items is called the external file status. If you use a
TRANSACTION file, you have a further record of the result called the external
return code, which consists of the external major and minor return codes.
During the processing of an I/O statement, the file status can be updated in one of
three ways, as described below. The contents of the file status determine which
error handling procedures to run.
Error handling procedures take control after an unsuccessful input or output opera-
| tion, which is denoted by any file status in which the first character is not zero.
Before any of these procedures run, the file status is copied into the external file
status.
002
Call on data management to perform I/O operation
– Method C: Monitor for messages sent by data management and set
internal file status accordingly.
– Method A: Check system information blocks and set internal file
status if not already set using Method C.
Is the file a transaction file?
Yes No
003
Set external file status
– Move internal file status to external file status (specified in file status
clause). Based on internal file status, run error handling code.
004
Check major and minor return codes from system
– Method B: If data management has sent a message, translate major
and minor return codes associated with system message
into internal file status.
Continue at Step 003
005
Continue at Step 003
Unlike a USE procedure (which may not be active during an entire program), a
COBOL message monitor becomes active as soon as the program starts.
Message monitors set file statuses and indicate SIZE ERROR, END-OF-PAGE, and
OVERFLOW conditions.
Message monitors generated by COBOL are grouped into several sets, generated
under certain conditions within a COBOL program. The following table provides
general guidelines regarding the generation of message monitors:
Return Codes
When you specify a TRANSACTION file in your program, the FILE STATUS clause
of your SELECT statement can contain two data names: the external file status,
and the (major and minor) return code. As described under “Internal and External
File Status” on page 70, a file status can be set in one of three ways; however,
return codes are set by the system after any transaction I/O that calls data man-
agement. Consequently, most error conditions that result in a system message
also have an associated return code.
Return codes are similar to file status values. That is, CPF messages sent by the
system are grouped together under message monitors, and each message monitor
sets one or more file statuses.
Similarly, CPF messages are grouped together, and each group of messages gen-
erates the same major return code. (The minor return code is not necessarily the
same.)
The main difference between file statuses and return codes is that the grouping of
CPF messages is different.
Although COBOL only sets return codes for TRANSACTION files, other types of
files (such as printer files) also set return codes. You can access the return codes
for these files through an ACCEPT from I-O-FEEDBACK operation.
I /O Oper at i on
i s not s ucces s f ul
No
Retur n t o
Set COBOL program
i nt er nal
f i l e s t at us
I ssue
End of f i l e What Al l ot her s Yes i nf or mat i onal
Moni t ored
t ype of er r or mes s age
severe
is it? (e. g. LBE7421);
er r o r ?
s et f i l e s t at us t o 90
I nval i d No
key
Is Is Is
Is
there an No there an No No there a No
t her e an E r r or
AT END I NVA L I D K E Y f i l e s t at us
Decl arati ve?
phr as e? phr as e? cl ause?
Run Run
Run
AT END I NVA L I D K E Y
Er ror
i mperati ve i mperati ve
Decl arati ve
st at ement st at ement
Ret ur n t o
COBOL program
Note: = Go to on next page
I ss ue er r or
mes s age
LBE7207
D, F What i s C
Per f or m End
r es pons e t o
COBOL dump COBOL program
LBE7207?
End Ret ur n t o
COBOL program COBOL program
Does
an Retur n t o
er r or handl er previ ous di agram
ex i s t ?
Cal l er r or
handler
Yes
No
What
is
retur n code?
G
*1 Yes
I ssue
C,D,F
severe E er r or mes s age
er r or ? LBE7200
No
*2
Yes
I ssue
Moni tored
severe er r or mes s age,
E
er r or ? e. g. L BE 7 0 21
No
Set
i nter nal
f i l e s t at us
*3 Is Is
f i l e s t at us Yes Yes
Run
t her e an Er r or Er r or
equal to Decl arati ve?
9 0 or 9 P ? Declarative
No No
What
End of f i l e Al l ot her s
t ype of er r or
is it?
I nval i d
key
Is Is Is
there an No there an No No
t her e an E r r or
AT END I N VAL I D K E Y Decl arati ve?
phr as e? phr as e?
Run Run
Run
AT END I N VAL I D K E Y
Er r or
i mperati ve i mperati ve
Decl arati ve
st at ement st at ement
Ret ur n t o
COBOL program
An I/O exception may occur that is being specifically monitored for and which,
according to the nonstandard error handling model, is severe enough to stop the
program. In this situation no file status is set.
During an I/O operation, a problem may occur that is not expected by the system.
These problems generally result in messages (such as those starting with “MCH”)
that fall outside the CPF4xxx and CPF5xxx range. Such errors, known as unmoni-
tored severe errors, follow the Yes branch from position *1 in Figure 25. These
errors are handled by an all-purpose message monitor and result in an ending of
the COBOL program. No file status is set.
Note that the file status shown here refers to the internal file status.
File Status
is set
What Is
is leftmost leftmost Is Run
0 2 or higher No Yes
character of character of file there a USE USE
file status? status equal to procedure? procedure
2?
1 Yes No
Is Run Is Run
there an Yes AT END there an Yes INVALID KEY
AT END imperative INVALID KEY imperative
phrase? statement phrase? statement
No No
Is
there a Run
Yes
USE USE
procedure? procedure
No
Continue
COBOL program
Note: = Go to on next page
No
Is
Is
leftmost Yes Run
there a Yes
character of file status NOT INVALID KEY
NOT INVALID KEY
equal to imperative statement
phrase?
0?
No No
Is
Is Run
leftmost
Yes there a Yes NOT AT END
character of file status
NOT AT END imperative
equal to
phrase? statement
0?
No No
Continue
COBOL program
Note: Follow the parts of the diagram that apply to your statements.
For a job failure (either because of user or system error), files under commitment
control are restored as part of job termination to the files’ status at the previous
commitment boundary.
Because files under commitment control are rolled back after system or process
failure, this feature can be used to help in restarting. You can create a separate
record to store data that may be useful should it become necessary to restart a job.
This restart data can include items such as totals, counters, record key values, rela-
tive key values, and other relevant processing information from an application.
If you keep the restart data mentioned above in a file under commitment control,
the restart data will also be permanently stored in the database when a COMMIT
statement is issued. When a ROLLBACK occurs after job or process failure, you
can retrieve a record of the extent of processing successfully processed before
failure. Note that the above method is only a suggested programming technique
and will not always be suitable, depending on the application.
For potentially recoverable I/O errors on TRANSACTION files, the system initiates
action in addition to the steps that must be taken in the application program to
attempt error recovery. For more information about action taken by the system,
see the Remote Work Station Guide.
By examining the file status after an I/O operation, the application program can
determine whether a recovery from an I/O error on the TRANSACTION file is pos-
sible. If the File Status Key has a value of 9N, the application program may be
able to recover from the I/O error. A recovery procedure must be coded as part of
the application program and varies depending on whether a single device was
acquired by the TRANSACTION file or whether multiple devices were attached.
Conditioning
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* D I S P L AY F I LE F OR E R R OR R E COV E R Y E X AMP L E
A*
A I ND A R A
A R F OR MA T 1 CF 0 1 ( 0 1 ' E ND O F P R OGR AM ' )
A*
A 12 2 8 ' E N T E R I NP U T '
A I NP U T F L D 5 I 12 42
A 28 2 6 ' F 1 = T E RM I NA T E '
A
A
A
A
A
A
A
A
A
A
A
A
.1/ This defines processing that takes place when an I/O error occurs on
RECOVFILE.
.2/ This prints out information to help in diagnosing the problem.
.3/ If the file-status equals 9N (temporary error), and no previous error recovery
has been attempted for this I/O operation, error recovery is now attempted.
.4/ To avoid program looping, recovery is not attempted now if it was attempted
previously.
.5/ Recovery consists of dropping, then reacquiring, the program device on
which the I/O error occurred.
.6/ The mainline of the program consists of writing to and reading from a device
until the user signals an end to the program by pressing F1.
.7/ If the WRITE operation failed but recovery was done, the WRITE is
attempted again.
.8/ If the READ operation failed, processing will continue by writing to the device
again, and then attempting the READ again.
The maximum number of files that you can define and open within number of files
used by a program a COBOL program is 99. If you use extended display options,
the maximum number is 98. For information on specifying the extended display
options, refer to page 23 .
The files are kept online and serve as the connecting link between a program and
the device used for I/O. The actual device association is made when the file is
processed. In some instances, this type of I/O control allows the user to change
the attribute of the file (and, in some cases, change the device) used in a program
without changing the program.
Printer
The COBOL device name in the ASSIGN clause defines the COBOL functions that
can be processed on the selected file. At compilation time, certain COBOL func-
For example, assume that the file name FILEY is associated in the COBOL
program with the FORMATFILE device. The device FORMATFILE is an inde-
pendent device type. Therefore, no line or page control specifications are valid in
the COBOL program in the WRITE ADVANCING statement. When the program is
run, the actual I/O device is specified in the description of FILEY. For example, the
device might be a printer; only the default line and page control or those defined in
the DDS would be used:
Printer
FILEX
Compile
Time DEV(QPRINT)
COBOL Program
Override Command:
SELECT file-name OVRDKTF FILE(FILEX) TOFILE (FILEA)
ASSIGN TO FORMATFILE-FILEX
FILEA
Diskette
Run DEV(QDKT)
Time
Not all file redirections or overrides are valid. At run time, checking occurs to
ensure that the specifications within the COBOL program are valid for the file being
processed. The OS/400 operating system allows some file redirections even if
device specifics are contained in the program. For example, if the COBOL device
name is PRINTER and the actual file the program uses is not a printer, the oper-
ating system ignores the COBOL print spacing and skipping specifications.
Spooling
The AS/400 system provides for the use of input and output spooling functions.
Each AS/400 file description contains a spool attribute that determines whether
spooling is used for the file at run time. The COBOL program is not aware that
spooling is being used. The actual physical device from which a file is read or to
which a file is written is determined by the spool reader or the spool writer. See
the Data Management Guide for more detailed information on spooling.
Output Spool
Output spooling is valid for batch and interactive jobs. The description of the file
that is specified in COBOL by the system-name contains the specification for
spooling as shown in the following example:
Run Time
Print Writer
Printer Device
File override commands can be used at run time to override the spooling options
that are specified in the file description, such as the number of copies to be printed.
In addition, AS/400 spooling support allows you to redirect a file after the program
has run. For example, you can direct the printer output to a different device, such
as a diskette.
Diskette
*YES
Spooled
File
See the Data Management Guide for more information on inline data files.
The simplest form of overriding a file is to override some attributes of the file. For
example, FILE(OUTPUT) with COPIES(2) is specified when a printer file is created.
Then, before the COBOL program is run, the number of printed copies of output
can be changed to 3. The override command is as follows:
OVRPRTF FILE(OUTPUT) COPIES(3)
Another form of file overriding is to redirect the COBOL program to access a dif-
ferent file. When the override redirects the program to a file of the same type (such
as a printer file to another printer file), the file is processed in the same manner as
the original file.
When the override redirects the program to a file of a different type, the overriding
file is processed in the same manner as the original file would have been proc-
essed. Device-dependent specifications in the COBOL program are ignored, and
the defaults are taken by the system.
Not all file redirections are valid. For example, an indexed file for a COBOL
program can only be overridden to another indexed file with a keyed access path.
The COBOL programmer must ensure that file overrides are applied properly. For
more information on valid file redirections, the device dependent characteristics
ignored, and the defaults assumed, see the Data Management Guide.
By default, the operating system places the following lock states on database files
when the files are opened by COBOL programs:
EXTEND mode is a method of adding records to the end of a sequential file when
the file is opened.
The shared-for-read lock state allows another user to open the file with a lock state
of shared-for-read, shared-for-update, shared-no-update, or exclusive-allow-read,
but the user cannot specify the exclusive use of the file. The shared-for-update
lock state allows another user to open the file with a shared-for-read or shared-for-
update lock state.
The operating system places the shared-for-read lock on the device file and an
exclusive-allow-read lock state on the device. Another user can open the file but
cannot use the same device.
Note: When a COBOL program opens a physical file for OUTPUT, that file will be
subject to an exclusive lock for the period of time necessary to clear the
member.
For more information on allocating resources and the lock states, see the Data
Management Guide.
For information about the duration of record lock with and without commitment
control, refer to Table 2 on page 96.
For a logical file based on one physical file, the lock is placed on the record in the
physical file. If a logical file is based on more than one physical file, a lock is
placed on one record in each physical file.
This lock applies not only to other programs, but also to the original program if it
attempts to update the same underlying physical record through a second file.
Note: When a file with indexed or relative organization is opened for I/O, using
random or dynamic access, a failed I/O operation on any of the I/O verbs
except WRITE also unlocks the record. A WRITE operation is not consid-
ered an update operation; therefore, the record lock is not released.
For more information about releasing database records read for update, see the
Data Management Guide.
When commitment control is used for database files, records in those files are
subject to either a high lock level LCKLVL (*ALL) or a low lock level
LCKLVL(*CHG). With a low lock level (*CHG), all records that are changed
(rewritten, deleted, or added) in files under commitment control are locked until a
COMMIT or ROLLBACK statement is successfully processed. With a high lock
level (*ALL), all records accessed, whether for input or output, are locked until a
COMMIT or ROLLBACK is successfully processed. For both record locking levels,
no other job can modify data in locked records until the COMMIT or ROLLBACK
has been successfully completed. (A locked record can only be modified within the
same job and through the same physical or logical file.)
The lock level also governs whether locked records can be read. With a high lock
level (*ALL), you cannot read locked records in a database file. With a low lock
level (*CHG), you can read locked records in a database file, provided the file is
opened as INPUT in your job, or opened as I/O and READ WITH NO LOCK is
used.
Other jobs, where files are not under commitment control, can always read locked
records, regardless of the lock level used, provided the files are opened as INPUT.
Because it is possible in some cases for other jobs to read locked records, data
can be accessed before it is permanently committed to a database. If a
ROLLBACK statement is processed after another job has read locked records, the
data accessed will not reflect the contents of the database.
Table 2 shows record locking considerations for files with and without commitment
control.
*ALL
READ INPUT READ │
.
Without Commitment Control │
.
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
*ALL
READ I-O READ │
.
WITH Without Commitment Control │
NO .
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
LOCK
*ALL
READ I-O READ │
───────────────────────────5
Without Commitment Control │
───────────────────────────5
With Commitment Control *CHG ────────────────────────────┼─────────────────────────────5
*ALL
REWRITE I-O REWRITE │
.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
*ALL
START INPUT START │
.
Without Commitment Control │
.
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
*ALL
START I-O START │
───────────────────────────5
Without Commitment Control │
───────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
*ALL
WRITE I-O WRITE │
.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
*ALL
WRITE OUTPUT WRITE │
.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
*ALL
A file under commitment control can be closed or opened without affecting the
status of changes made since the last commitment boundary. A COMMIT must still
be issued to make the changes permanent, or a ROLLBACK issued to cancel the
changes. A COMMIT statement, when processed, leaves files in the same open or
closed state as before processing.
All files under commitment control within the same job must be journaled to the
same journal. For more information about journal management and its related
functions, and for more information about commitment control, refer to the
Advanced Backup and Recovery Guide.
Commitment control must also be specified outside the COBOL language through
the OS/400 control language (CL). The Start Commitment Control (STRCMTCTL)
command establishes the capability for commitment control and sets the level of
record locking at the high level (*ALL), or the low level (*CHG). The STRCMTCTL
command does not automatically initiate commitment control for a file. That file
must also be specified in the COMMITMENT CONTROL clause of the
I-O-CONTROL paragraph within the COBOL program. The commitment control
environment is normally ended by using the End Commitment Control
For more information about commitment control, see the Advanced Backup and
Recovery Guide.
Note: The ability to prevent reading of uncommitted data that has been changed
is a function of commitment control and is only available if you are running
under commitment control. Normal (noncommitted) database support is not
changed by the commitment control extension, and allows reading of locked
records when a file that is opened only for input is read. Try to use files
consistently. Typically, files should always be run under commitment
control or never be run under commitment control.
Location
Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indicator
Reserved
Indicator
Indicator
Decimal
Not (N)
Not (N)
Not (N)
Line Pos
1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 19 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0
Even when all of the above conditions are met, certain OS/400 restrictions can
cause blocking and unblocking to not be processed. In these cases, performance
improvements will not be realized.
If you are using dynamically accessed and indexed organization files, you can use
READ PRIOR and READ NEXT to perform blocking. When using READ PRIOR
and READ NEXT to perform blocking, you cannot change direction while there are
records remaining in the block. To clear the records from a block, specify a
random operation, such as a random READ or a random START, or use a sequen-
tial READ FIRST or READ LAST.
If an illegal change of direction takes place, file status 9U results. No further I/O is
possible until the file is closed and reopened.
You can override blocking at run time by specifying SEQONLY(\NO) for the OVRDBF
command.
There are certain instances in which the blocking factor you specify may be
changed. See the Database Guide for more information about these situations.
Where a block of records is written or read, the I/O feedback area contains the
number of records in that block. The I/O-FEEDBACK area is not updated after
each read or write for files where multiple records are blocked and unblocked by
COBOL. It is updated when the next block is read or written. See “I/O
FEEDBACK” in the COBOL/400 Reference for more information.
For database files, you may not see all changes as they occur, if the changes are
made in different programs. For a description of the effect of blocking on changes
to database files, see the discussion on sequential-only processing in the Database
Guide.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───ACCEPT──identifier──FROM──mnemonic-name──┬─────────────────┬────────────5% ║
║ └──FOR──file-name─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
See the “ACCEPT Statement” section of the COBOL/400 Reference for more infor-
mation on specifying this statement. See the “Attribute Data Formats” section of
the COBOL/400 Reference for information on the OPEN-FEEDBACK and the
I-O-FEEDBACK areas.
When the FILE STATUS clause is specified, the system moves a value into the
status key data item after each input/output request that explicitly or implicitly refers
to this file. This 2-character value indicates the run status of the statement. When
the compiler generates code to block output records or unblock input records, file
status values that are caused by OS/400 exceptions are set only when a block is
processed. For more information about blocking records, refer to “Unblocking Input
Records and Blocking Output Records” on page 102.
The I-O-FEEDBACK area is not updated after each read or write for files in which
multiple records are blocked and unblocked by COBOL.
File Descriptions
All files on the AS/400 system are defined to the OS/400 operating system. The
extent to which files can be defined differs:
A program-described file is described at the field level within the COBOL
program in the Data Division. The description of the file to the operating
system includes information about the type of file and the length of the records
in the file.
An externally described file is described at the field level to the operating
system through IDDU, SQL/400* commands, or DDS. If you create a file (for
instance, by using the CRTPF command) without specifying DDS for it, the file
still has a field description. The single field has the same name as the file, and
has the record length you specified in the create command.
The description includes information about the type of file, such as database or
a device, and a description of each field and its attributes. The file must be
created before you compile the program.
Both externally described files and program-described files must be defined in the
COBOL program within the INPUT-OUTPUT SECTION and the FILE SECTION.
Record descriptions in the FILE SECTION for externally described files can be
defined with the Format 2 COPY statement.
Device-dependent functions such as forms control are not extracted by the Format
2 COPY operation. Only field-level descriptions are extracted.
Program-Described Files
Records and fields for a program-described file are described by coding record
descriptions in the File Section of the COBOL program instead of using the Format
2 COPY statement.
The file must exist on the system before the program can run, except when you
use dynamic file creation, by specifying GENOPT(*CRTF) on the CRTCBLPGM
command. For more information, refer to the description of the GENOPT param-
eter on page 22, or the OPEN statement in the COBOL/400 Reference. To create
a file, use one of the Create File commands, which can be found in the CL
Reference.
These specifications come from the external file description and from the OS/400
command you use to create the file.
You can use an externally described file within a program by making it a program-
described file (by coding the record description in the source). In this case, the
compiler does not copy the external field-level description of the file at compilation
time. You may find this useful during conversions, since an existing program can
use a program-described file while a new program uses an externally described file
to refer to the same file.
Figure 31 on page 106 shows how COBOL programs can relate to files on the
AS/400 system, making use of external file descriptions from DDS.
Figure 31. Example showing how COBOL can relate to AS/400 files
.1/ The COBOL program uses the field level description of a file that is defined to
the operating system. The COBOL user coded a Format 2 COPY statement
for the record description. At compilation time, the compiler copies in the
external field-level description and translates it into a syntactically correct
COBOL record description. The file must exist at compilation time.
.2/ An externally described file is used as a program-described file in the COBOL
program. The entire record description for the file is coded in the COBOL
program. This file does not have to exist at compilation time.
.3/ A file is described to the operating system as far as the record level only.
The entire record description must be coded in the COBOL program. This file
does not have to exist at compilation time.
.4/ A file name can be specified for compilation time, and a different file name
can be specified for run time. A COBOL Format 2 COPY statement gener-
ates the record description for the file at compilation time. At run time, a dif-
ferent library list or a file override command can be used so that a different
file is accessed by the program. The file description copied in at compilation
time is used to describe the input records used at run time.
Note: For externally described files, the two file formats must be the same. Other-
wise, a level check error will occur.
The record format specifications describe the fields in a record and the location of
the fields in a record. The fields are located in the record in the order specified in
DDS. The field description generally includes the field name, the field type (char-
acter, binary, external decimal, or internal decimal), and the field length (including
the number of decimal positions in a numeric field). Instead of being specified in
the record format for a physical or logical file, the field attributes can be defined in a
field reference file. (See Figure 32 on page 107.)
The keys for a record format are specified in DDS. When you use a Format 2
COPY statement, a table of comments is generated in the source program listing
showing how the keys for the format are defined in DDS.
See the DDS Reference for a complete list of the DDS keywords that are valid for a
database file.
Conditioning
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A * * F L DR E F DS TRE F D I S T R I B U T I ON A P P L I C A T I ON F I E L D R E F E R E NC E
A R DS TRE F T E X T ( ' D I S T R I B U T I ON F I E L D R E F ' )
A * COMMON F I E L D S U S E D A S R E F E R E NC E
A B A S DA T 6 0 E D T CD E ( Y )
A T E X T ( ' B A S E DA T A F I E L D ' )
A * F I E L D S U S E D B Y C U S T OME R MA S T E R F I L E
A CU S T 5 CH E CK ( MF )
A CO L H DG ( ' C U S T OME R ' ' N UMB E R ' )
A N AME 20 CO L H DG ( ' C U S T OME R N AME ' )
A AD D R R R E F F L D ( N AME )
A CO L H DG ( ' C U S T OME R AD D R E S S ' )
A CI TY R R E F F L D ( N AME )
A CO L H DG ( ' C U S T OME R C I T Y ' )
A S TAT E 2 CH E CK ( MF )
A CO L H DG ( ' S T A T E ' )
A S R H COD 6 CH E CK ( MF )
A CO L H DG ( ' S E A R C H ' ' COD E ' )
A T E X T ( ' C U S T OME R N UMB E R S E A R C H COD E ' )
A Z I P 5 0 CH E CK ( MF )
A CO L H DG ( ' Z I P ' ' COD E ' )
A CU S T Y P 1 0 R A NG E ( 1 5 )
A CO L H DG ( ' C U S T ' ' T Y P E ' )
A T E X T ( ' C U S T OME R T Y P E 1 = GOV 2 = S C H 3 = B +
A U S 4 = P T 5 =O T H ' )
A AR B A L 8 2 CO L H DG ( ' ACC T S R E C ' ' B A L A NC E ' )
A E D T CD E ( J )
A OR D B A L R R E F F L D ( AR B A L )
A CO L H DG ( ' A / R AM T I N ' ' OR D E R F I L E ' )
A L S T AM T R R E F F L D ( AR B A L )
A CO L H DG ( ' L A S T ' ' AMOU N T ' ' P A I D ' )
A T E X T ( ' L A S T AMOU N T P A I D I N A / R ' )
A
A
A
A
This example of a field reference file shows the definitions of the fields that are
used by the CUSMSTL (customer master logical) file, which is shown in Figure 33
on page 109. The field reference file normally contains the definitions of fields that
The following pages provide examples of DDS usage and the COBOL code that
would result from the use of a Format 2 COPY statement. (See “Format 2 COPY
Statement (DD, DDR, DDS, or DDSR Option)” on page 112 for a detailed
description of the Format 2 COPY statement.)
Figure 33 on page 109 shows the DDS for a logical file and Figure 34 on
page 110 shows the COBOL code generated.
Figure 35 on page 111 describes the same file but includes the ALIAS
keyword, and Figure 36 on page 112 shows the COBOL code generated.
Actual file processing within the Procedure Division is the same for both program-
described and externally described files.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* * L OG I CA L CU S MS T L C U S T OME R MA S T E R F I LE
A U N I QU E
A* R CU S R E C P F I L E ( CU S MS T P )
A T E X T ( ' C U S T OME R MA S T E R R E COR D ' )
A CU S T
A N AME
A AD D R
A CI TY
A S TAT E
A Z I P
A S R H COD
A CU S T Y P
A AR B A L
A OR D B A L
A L S T AM T
A L S T DA T
A CR D L M T
A S L S YR
A S L S L YR
A K CU S T
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
.1/ A logical file for processing the customer master physical file (CUSMSTP) is
defined and named CUSMSTL.
.2/ The UNIQUE keyword indicates that duplicate key values for this file are not
allowed.
.3/ One record format (CUSREC) is defined for the CUSMSTL file, which is to
be based upon the physical file CUSMSTP.
.4/ The CUST field is identified as the key field for this file.
.5/ If field attributes (such as length, data type, and decimal positions) are not
specified in the DDS for a logical file, the attributes are obtained from the
corresponding field in the physical file. Any field attributes specified in the
DDS for the logical file override the attributes for the corresponding field in
Figure 32 on page 107 shows an example of a field reference file that defines the
attributes of the fields used in the database file. See the Database Guide for more
information regarding field reference files.
ð1 CUS-MASTER.
COPY DDS-CUSREC OF CUSLIB-CUSTMAST.
\I-O FORMAT: CUSREC FROM FILE CUSTMAST OF LIBRARY CUSLIB CUSREC
\ CUSTOMER MASTER RECORD CUSREC
\THE KEY DEFINITIONS FOR THE RECORD FORMAT CUSREC CUSREC
\NUMBER NAME RETRIEVAL TYPE ALTSEQ CUSREC
\ððð1 CUST ASCENDING AN NO CUSREC
ð5 CUSREC. CUSREC
ð6 CUST PIC X(5). CUSREC
\ CUSTOMER NUMBER CUSREC
ð6 NAME PIC X(2ð). CUSREC
\ CUSTOMER NAME CUSREC
ð6 ADDR PIC X(2ð). CUSREC
\ CUSTOMER ADDRESS CUSREC
ð6 CITY PIC X(2ð). CUSREC
\ CUSTOMER CITY CUSREC
ð6 STATE PIC X(2). CUSREC
\ STATE ABBREVIATION CUSREC
ð6 ZIP PIC S9(5) COMP-3. CUSREC
\ ZIP CODE CUSREC
ð6 SHRCOD PIC X(6). CUSREC
\ CUSTOMER NAME SEARCH CODE CUSREC
ð6 CUSTYP PIC 9(1). CUSREC
\ CUSTOMER TYPE CUSREC
ð6 ARBAL PIC S9(6)V9(2) COMP-3. CUSREC
\ ACCT/REC BALANCE CUSREC
Figure 34. Example of the Results of the Format 2 COPY Statement (DDS)
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* * L OG I CA L CU S MS T L C U S T OME R MA S T E R F I LE
A U N I QU E
A* R CU S R E C P F I L E ( CU S MS T P )
A T E X T ( ' C U S T OME R MA S T E R R E COR D ' )
A CU S T A L I A S ( C U S T OME R _N UMB E R )
A N AME A L I A S ( C U S T OME R _N AME )
A AD D R A L I A S ( AD D R E S S )
A CI TY
A S TAT E
A Z I P
A S R H COD A L I A S ( S E A R C H _COD E )
A CU S T Y P A L I A S ( C U S T OME R _ T Y P E )
A AR B A L A L I A S ( ACC T _R E C _B A L A NC E )
A OR D B A L
A L S T AM T
A L S T DA T
A CR D L M T
A S L S YR
A S L S L YR
A K CU S T
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
.1/ This is the name associated with the ALIAS keyword, which will be included
in the program. Available through the DDS ALIAS option, an alias is an
alternative name that allows a data name of up to 30 characters to be
included in a COBOL/400 program.
Figure 36. Example of the Results of the Format 2 COPY Statement (DD) with the ALIAS
Keyword
IBM Extension
╔═══════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───COPY──┬──DD-format-name───┬──┬────────┬──┬───────────────┬───────────────5 ║
║ ├──DD-ALL-FORMATS───┤ ├─ -I───┤ ├─ -INDICATOR──┤ ║
║ ├──DDR-format-name──┤ ├─ -O───┤ ├─ -INDICATORS─┤ ║
║ ├──DDR-ALL-FORMATS──┤ └─ -I-O─┘ └─ -INDIC──────┘ ║
║ ├──DDS-format-name──┤ ║
║ ├──DDS-ALL-FORMATS──┤ ║
║ ├──DDSR-format-name─┤ ║
║ └──DDSR-ALL-FORMATS─┘ ║
║ ║
║ ║
║ 5────┬─OF─┬──┬───────────────────┬──file-name──┬────────────┬─────────────────5 ║
║ └─IN─┘ └──library-name- ──┘ └──SUPPRESS──┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────────────────────────┬────5% ║
║ │ ┌──────────────────────────────────────────────────┐ │ ║
║ │ 6 │ │ ║
║ └──REPLACING──┬─ ==pseudo-text-1== ─┬─BY─┬─ ==pseudo-text-2== ─┬─┴──┘ ║
║ ├────identifier-1─────┤ ├────identifier-2─────┤ ║
║ ├────literal-1────────┤ ├────literal-2────────┤ ║
║ └────word-1───────────┘ └────word-2───────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝
The Format 2 COPY statement can be used only in the Data Division. You should
ensure that a group level item that has a level-number less than 05 precedes the
statement.
When the DD option is used, any ALIAS names present replace the corresponding
DDS field names. All underscores in the ALIAS names are translated into hyphens
before any replacing occurs.
The DDR option does everything that the DD option does. It also copies the
internal DDS format field names, replacing the invalid COBOL characters @, #, $,
and _ with the valid COBOL characters A, N, D, and - accordingly. This option also
removes any underscores from the ends of the field names.
The DDS option copies in the internal DDS format field names. For examples of
keys and key names that can be generated when you use the DDS option of the
Format 2 COPY statement, see pages 121 through 127.
The DDSR option does everything that the DDS option does. It also copies the
internal DDS format field names, replacing the invalid COBOL characters @, #, $,
and _ with the valid COBOL characters A, N, D, and - accordingly. This option also
removes any underscores from the ends of the field names.
The following shows the effect of the DDR or DDSR option on invalid COBOL field
names:
The format-name is the name of the DDS record format definition that is to be
translated into COBOL data description entries. The format-name must follow the
rules for formation of any COBOL/400 name.
More information can be found about the Indicator attribute in the section, “Indicator
Attribute of the Format 2 COPY Statement” on page 118.
Library-name is optional. If it is not specified, the current job library list is used as
the default value.
File-name is the name of an AS/400 system file. The generated DDS entries repre-
sent the record format defined in the file. The file must be created before the
program is compiled.
For all other file types, the description generated varies as follows:
If -I is specified, the generated data description entries contain either:
– The input and input/output fields for a nonsubfile format
– The input, output, and input/output fields for a subfile format.
If -O is specified, the generated data description entries contain either:
– The output and input/output fields for a nonsubfile format
– The input, output, and input/output fields for a subfile format.
Note: Subfile records with only output or input/output fields, and no field indicators
specified, generate I/O formats.
SELECT FILE-X
ASSIGN TO DATABASE-CUSTMASTER.
..
.
FD FILE-X
LABEL RECORDS ARE STANDARD.
01 FILE-X-RECS.
COPY DDS-ALL-FORMATS OF
CUSTMASTER-QGPL. (See Note 1.)
..
.
WORKING-STORAGE SECTION.
01 ADR-REC.
COPY DDS-CUSTADR OF
CUSTMASTER. (See Note 2.)
01 DETAIL-REC.
COPY DDS-CUSTDETL OF
CUSTMASTER. (See Note 2.)
Notes:
1. This COPY statement generates only one storage area for all formats.
2. These COPY statements generate separate storage areas.
Indicators
Indicators are Boolean data items that can have the values B"0" or B"1".
When you define a record format for a file using DDS, you can condition the
options using indicators; indicators can also be used to reflect particular responses.
These indicators are known as OPTION and RESPONSE, respectively. Option
indicators provide options such as spacing, underlining, and allowing or requesting
data transfer from a program to a printer or display device. Response indicators
provide response information to a program from a device, such as function keys
pressed by a work station user, and whether data has been entered.
Indicators can be used with TRANSACTION files and FORMATFILE files, but never
with database files.
05 file-name-RECORD
PIC X(size of largest record).
06 field-name PIC
Note: See Figure 38 on page 117 for the appropriate COBOL PICTURE defi-
nition.
DISPLAY FILES
␣(Blank) Default PIC X(n) PIC S9(n-m)V9(m)
X Alphabetic Only PIC X(n) —
N Numeric Shift PIC X(n) PIC S9(n-m)V9(m)
Y Numeric Only — PIC S9(n-m)V9(m)
I Inhibit Keyboard entry PIC X(n) PIC S9(n-m)V9(m)
W Katakana PIC X(n) —
A Alphanumeric Shift PIC X(n) —
D Digits only PIC X(n) PIC S9(n)
F Floating point ñ
single precision PIC 9(5) COMP-4 PIC 9(5) COMP-4
double precision PIC 9(10) COMP-4 PIC 9(10) COMP-4
M Numeric-only character PIC X(n) —
S Signed-numeric shift — PIC S9(n-m)V9(m)
E DBCS-either PIC X(n) —
J DBCS-only PIC X(n) —
O DBCS-open PIC X(n) —
G DBCS-graphic PIC X(2n) —
ñ COBOL treats floating point fields as FILLER. See 'Floating Point Fields'.
ò In DDS, if the field has an attribute of VARLEN, the result is two additional bytes at the beginning of the field.
ó FILLER items by default. See 'Date, Time, and Timestamp Fields'.
Indicator Structures
If indicators are requested, and exist in the format, an additional group name (06
level) is generated at the beginning of the structure, followed by entries (07 level)
for the relevant individual indicators.
06 format-name(-I or -O)-INDIC.
07 INxx PIC 1 INDIC xx.
06 SAMPLE1-I-INDIC.
07 IN01 PIC 1 INDIC 01.
07 IN04 PIC 1 INDIC 04.
07 IN05 PIC 1 INDIC 05.
07 IN07 PIC 1 INDIC 07.
06 FLD1 PIC ... .
06 FLD2 PIC ... .
If the Indicator attribute is specified, data description entries are generated for indi-
cators, but not for data fields. A 05 group level entry is generated as follows:
If the COPY is for a single structure (for example, COPY
DDS-format-name-INDIC)
05 format-name-I. (or -O as appropriate)
If the COPY is for multiple structures
(for example, COPY DDS-ALL-FORMATS-INDIC)
05 file-name-RECORD.
The data description entries that are generated are determined by which one of the
usage attributes (I, O, or I-O) is specified or assumed in the COPY statement.
If ...I-INDICATOR... is specified, data description entries for input (response)
indicators are generated for indicators used in the input record area.
If ...O-INDICATOR... is specified, data description entries for output (option)
indicators are generated for indicators used in the output record area.
If ...I-O-INDICATOR... is specified or assumed, separate data description
entries for both input and output (response and option) indicators are generated
for indicators used in the input and output record areas.
If the Indicator attribute is not specified, generation of data description entries for
indicators depends on if the file had the keyword INDARA specified in the DDS at
the time it was created.
If INDARA was not specified, data description entries are generated for both
data fields and indicators.
If INDARA was specified, data description entries are generated for data fields
only, not for indicators.
ð1 RCUSREC.
COPY DDS-CUSREC-I OF CUSFILE.
\ I-O FORMAT: CUSREC FROM FILE CUSFILE OF LIBRARY CUSLIB CUSREC
\ THE KEY DEFINITIONS FOR RECORD FORMAT CUSREC
\ NUMBER NAME RETRIEVAL TYPE ALTSEQ
\ ððð1 ARBAL ASCENDING SIGNED NO
\ ððð2 AREACD DESCENDING ABSVAL NO
ð5 CUSREC.
ð6 ARBAL PIC S9(7)V9(2) COMP-3 CUSREC
ð6 AREACD PIC S9(3) COMP-3. CUSREC
ð6 BOSTAZ PIC X(1). CUSREC
ð6 CNTCT PIC X(15). CUSREC
ð6 CRCHKZ PIC S9(2). CUSREC
ð6 CSTAT PIC X(1). CUSREC
ð6 CUSTNZ PIC S9(6). CUSREC
ð6 DLORD PIC S9(6). CUSREC
ð6 DSCPCZ PIC S9(2)V9(3) COMP-3. CUSREC
ð6 INDUS PIC S9(2). CUSREC
ð6 NAME1 PIC X(25). CUSREC
ð6 NAME2 PIC X(25). CUSREC
ð6 NAME3 PIC X(25). CUSREC
ð6 NAME4 PIC X(25). CUSREC
ð6 PHONE PIC S9(7) COMP-3. CUSREC
ð6 PRICIZ PIC S9(2). CUSREC
ð6 SHPINZ PIC X(25). CUSREC
ð6 SLSMAZ PIC X(3). CUSREC
ð6 TAXCDZ PIC S9(2). CUSREC
ð6 TERMSZ PIC S9(2). CUSREC
Redefinition of Formats
Pay particular attention to the REDEFINES clause that may be generated for the
ALL-FORMATS or -I-O phrases. Because all formats are redefined on the same
area (generally a buffer area), several field names can describe the same area of
storage, and unpredictable results can occur if the entire format area is not reinitial-
ized prior to each output operation.
Data items that are subordinate to the data item specified in a MOVE CORRE-
SPONDING statement do not correspond and are not moved when they contain a
REDEFINES clause or are subordinate to a redefining item.
FD ORDER-ENTRY-SCREEN ...
ð1 ORDER-ENTRY-RECORD ...
..
.
WORKING-STORAGE SECTION.
ð1 ORDSFL-I-FORMAT.
COPY DDS-ORDSFL-I OF DOESCR.
ð1 ORDSFL-O-FORMAT.
COPY DDS-ORDSFL-O OF DOESCR.
..
.
PROCEDURE DIVISION.
..
.
READ SUBFILE ORDER-ENTRY-SCREEN NEXT MODIFIED RECORD
INTO ORDSFL-I-FORMAT FORMAT IS "ORDSFL"
AT END SET NO-MODIFIED-SUBFILE-RCD TO TRUE.
..
.
MOVE CORR ORDSFL-I TO ORDSFL-O.
REWRITE SUBFILE ORDER-ENTRY-RECORD FROM ORDSFL-O-FORMAT
FORMAT IS "ORDSFL" ...
..
.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
The physical file described by Figure 40 forms a basis for the examples that follow.
Each example refers to a logical file (derived from the physical file) that specifies
EXTERNALLY-DESCRIBED-KEY in its SELECT clause.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* L OG I C A L F I L E L F1 F OR CON C A T K E Y WO R D E X AMP L E S
A*
A R R E CO R D 1 PF I L E (PF 1)
A*
A DA T E CON C A T ( M T H D A Y Y E AR )
A*
A K MT H
A K DAY
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
For the logical file described by Figure 41, COPY DDS generates keys and key
names derived from the physical file:
The COPY statement adds the suffix -DDS to the field names MTH and DATE
because MTH is a key that originates from the physical file, and DATE is a COBOL
reserved word. The COPY statement adds the suffix -DDS twice to the field name
DAY because DAY is both a key that originates from the physical file and a COBOL
reserved word.
Note that if you move your COPY statement from the File Section to the Working-
Storage Section or to the Linkage Section, the fields subordinate to DATE-DDS are
no longer available:
WORKING-STORAGE SECTION.
ð1 WRK-RECORD.
COPY DDS-ALL-FORMATS OF LF1.
ð5 LF1-RECORD PIC X(8).
\ I-O FORMAT:RECORD1 FROM FILE LF1 OF LIBRARY COPYDDS
\
ð5 RECORD1 REDEFINES LF1-RECORD.
ð6 DATE-DDS PIC X(8).
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* L OG I C A L F I L E L F2 F OR R E N AM E K E Y WO R D E X AMP L E S
A*
A R R E CO R D 2 PF I L E (PF 1)
A*
A MON T H R E N AM E ( M T H )
A*
A K MT H
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
For the logical file described by Figure 44, COPY DDS generates a key and key
name derived from the physical file:
The COPY statement adds the suffix -DDS to the field name MTH because MTH is
a key that originates from the physical file.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* L OG I C A L F I L E L F3 F OR SS T K E Y WO R D E X AMP L E S
A*
A R R E CO R D 3 PF I L E (PF 1)
A*
A YY I S S T ( Y E AR 2 2 )
A*
A K YY
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
The COPY statement does not add a suffix to the field name YY because YY is
neither a key that originates from the physical file nor a COBOL reserved word.
The REPLACING phrase cannot be used to change the name of a key field when
EXTERNALLY-DESCRIBED-KEY is used.
Floating-Point Fields
COBOL treats floating-point fields as FILLER. The fields can contain floating-point
values set outside of COBOL. A COMP-4 definition is generated to maintain proper
alignment in the record, but the data is not in binary format. No attempt must be
made to use floating-point data for processing in the COBOL program.
Floating-point key fields are not allowed. In cases where some formats exist with a
floating-point key field and other formats do not, use one or more Format 2 COPY
statements with specific format names, rather than the ALL-FORMATS option.
Note: If you have not specified your own program collating sequence, you can
create a record containing floating-point fields in your COBOL program by
moving LOW-VALUES to the entire record before moving in the values of
the non-floating-point fields. This will give the floating-point fields in the
record a value of zero. Note that the above method is only recommended if
valid floating-point fields with a value of zero are desirable for your partic-
ular application.
Access Path
The description of an externally described file contains the access path that
describes how records are to be retrieved from the file. Records can be retrieved
based on an arrival sequence (nonkeyed) access path or on a keyed sequence
access path.
For the keyed sequence access path, the sequence in which records are retrieved
from the file is based on the contents of the key fields defined in the DDS for the
file. For example, in the DDS shown in Figure 33 on page 109, CUST is defined
as the key field. The keyed sequence access path is updated whenever records
are added, deleted, or when the contents of a key field change.
See the Database Guide for a complete description of the access paths for an
externally described database file.
The key for a file is determined by the valid keys for the record types in that file.
The file’s key is determined in the following manner:
If all record types in a file have the same number of key fields defined in DDS
that are identical in attributes, the key for the file consists of all fields in the key
for the record types. (The corresponding fields do not have to have the same
name.) For example, if the file has three record types and the key for each
record type consists of fields A, B, and C, the file’s key consists of fields A, B,
and C. That is, the file’s key is the same as the records’ key.
If all record types in the file do not have the same key fields, the key for the file
consists of the key fields common to all record types. For example, a file has
three record types and the key fields are defined as follows:
– REC1 contains key field A.
– REC2 contains key fields A and B.
– REC3 contains key fields A, B, and C.
Then the file’s key is field A, the key field common to all record types.
If no key field is common to all record types, any keyed reference to the file will
always return the first record in the file.
In COBOL, you must specify a RECORD KEY for an indexed file to identify the
record you want to process. COBOL compares the key value with the key of the
file or record, and processes the specified operation on the record whose key
matches the RECORD KEY value.
Level Checking
When a COBOL/400 program uses an externally described file, the operating
system provides a level check function (LVLCHK). This function ensures that the
format has not changed since compilation time.
The compiler always provides the information required by level checking when an
externally described file is used (that is, when a record description was defined for
the file by using the Format 2 COPY statement). Only those formats that were
copied by the Format 2 COPY statement under the FD for a file are level checked.
The level check function will be initiated at run time based on the selection made
on the create, change, or override file commands. The default on the create file
command is to request level checking. If level checking was requested, level
checking occurs on a record format basis when the file is opened. If a level check
error occurs, COBOL sets a file status of 39 at OPEN time.
When no level checking was requested, and the file is re-created using an existing
format, existing COBOL programs that use that format may not work without recom-
pilation, depending on the changes to the format. For instance,
A change of keys will certainly cause a failure of the program on any I/O state-
ment
A change in the record length will cause any REWRITE to fail
A change in the record layout can cause various errors in the processing of
such a record.
You should use extreme caution when using COBOL programs without level
checking or recompiling the programs.
Note: The compiler does not provide level checking for program-described files.
For more information on level checking, see the Data Management Guide.
Since the maximum value that ITEM1-LENGTH can hold is 9 999, this is the length
of the longest variable-length field you can write from a COBOL program.
When *VARCHAR is not specified, variable-length fields are ignored and declared
as FILLER fields in COBOL/400 programs. If *NOVARCHAR is specified, the item
is declared as follows:
ð6 FILLER PIC x(n+2).
Your program can perform any valid character operations on the generated data
portion; however, because of the structure of the field, the length portion must be
valid binary data. This data is not valid if it is negative, or greater than the
maximum field length.
If the first two bytes of the field do not contain a valid binary number, an error will
occur if you try to WRITE or REWRITE a record containing the field (or UPDATE or
PUT the field in a database), and file status 90 is returned.
Your COBOL/400 program can perform any valid character calculation oper-
ations on the declared fixed-length field. However, because of the structure of
the field, the first two bytes of the field must contain valid binary data (invalid
current field-length data is non-numeric, less than 0, or greater than the DDS
field length.) An error occurs for an input or output operation if the first two
bytes of the field contain invalid field-length data; file status 90 is returned.
If you do not specify *VARCHAR, you can encounter problems performing
WRITE operations on variable-length fields, because you cannot assign a value
to FILLER. The two-byte field may have a value (for example X'4ð4ð') which
gives a length beyond the range allowed for the field. This causes an I/O error.
Date, time or timestamp fields are brought into a COBOL/400 program as fixed-
length character fields. Your COBOL/400 program can perform any valid character
operations on the fixed-length fields. These operations will follow the standard
COBOL rules for alphanumeric data items.
The date, time, and timestamp data types each have their own format.
If you try to WRITE a record before moving an appropriate value to a date, time, or
timestamp field, the WRITE operation will fail, and file status 90 will be returned.
Null-capable Fields
Although your program can process null-capable fields, null values are not sup-
ported. READ, SORT, and MERGE operations can be performed on null-capable
fields, but if the fields actually contain null values, errors occur.
DBCS-Graphic Fields
The DBCS-graphic data type is a character string in which each character is
represented by 2 bytes. The DBCS-graphic data type does not contain shift-out
(SO) or shift-in (SI) characters. The difference between single-byte and
DBCS-graphic data is shown in the following figure:
┌────────┬────────┬────────┬────────┐
│ 1 byte │ 1 byte │ 1 byte │ 1 byte │ Single-byte
└────────┴────────┴────────┴────────┘ data
│ │ │ │ │
└────────┴────────┴────────┴────────┘
1 char 1 char 1 char 1 char
┌────────┬────────┬────────┬────────┐
│ 1 byte │ 1 byte │ 1 byte │ 1 byte │ DBCS-graphic
└────────┴────────┴────────┴────────┘ data
│ │ │
└─────────────────┴─────────────────┘
1 character 1 character
Figure 51. Comparing Single-byte and Graphic Data
DBCS-graphic data is brought into your COBOL/400 program only if you specify the
*GRAPHIC value on the CVTOPT parameter of the CRTCBLPGM command, or the
CVTGRAPHIC option of the PROCESS statement. If you do not specify
DBCS-graphic data, graphic data is ignored and declared as FILLER fields in your
COBOL/400 program. For a description and the syntax of the CVTOPT parameter,
see page 23.
Examples
Figure 52 on page 135 shows an example of a DDS file that defines a variable-
length DBCS-graphic data item. Figure 53 on page 136 shows the COBOL/400
program using a COPY DDS statement, and the resulting listing when the program
is compiled.
For more information about CCSIDs and CDRA, see System Operation, SC41-3203
and the Data Management Guide.
IBM Extension
This chapter describes the COBOL/400 language extensions that support work
stations and program-to-program communication.
The AS/400 system permits you to communicate with a program or device (such as
Asynchronous communication types) on a remote system. For a detailed dis-
cussion of these devices, see the ICF Programmer’s Guide.
See the Data Management Guide for more information about using program-
described display files.
For more information about the Format 2 COPY statement, see “Format 2 COPY
Statement (DD, DDR, DDS, or DDSR Option)” on page 112.
In addition to the field descriptions (such as field names and attributes), the data
description specifications (DDS) for a display device file:
Specify the line number and position number entries for each field and constant
to format the placement of the record on the display.
Specify attention functions such as underlining and highlighting fields, reverse
image, or a blinking cursor.
Specify validity checking for data entered at the display work station. Validity
checking functions include:
– Detecting fields where data is required
– Detecting mandatory fill fields
– Detecting incorrect data types
– Detecting data for a specific range
– Checking data for a valid entry
– Performing modules 10 or 11 check digit verification.
Control display management functions such as when fields are to be erased,
overlaid, or retained when new data is displayed.
Associate indicators 01 through 99 with function keys designated as type CA or
CF. If a function key is designated as CF, both the modified data record and the
response indicator are returned to the program. If a function key is designated
as CA, the response indicator is returned to the program, but the data record
usually contains default values for input-only fields and values written to the
format for hidden output/input fields. For more information about type CF and
CA function keys, see the DDS Reference.
Assign an edit code (EDTCDE keyword) or edit word (EDTWRD keyword) to a
field to specify how the field’s values are to be displayed.
Specify subfiles.
Conditioning
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 2 2 23 2 4 25 2 6 27 28 29 30 3 1 3 2 33 3 4 35 3 6 37 38 39 40 4 1 4 2 43 4 4 45 4 6 47 48 49 50 5 1 5 2 5 3 5 4 55 5 6 57 5 8 5 9 60 6 1 6 2 6 3 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80
A * C U S T OME R MA S T E R I NQU I R Y F I LE - - C U S M I NQ
A*
A R E F ( CU SMS T P )
A R CU S PMT T E X T ( ' C U S T OME R P R OMP T ' )
A C A 0 3 ( 1 5 ' E ND O F P R OGR AM )
A 1 3 ' C U S T OME R MA S T E R I NQU I R Y '
A 3 3 ' C U S T OME R N UMB E R '
A CU S T R I 3 2 /0
A 99 E R R M S G ( ' C U S T OME R N UMB E R NO T F OU ND +
A P R E S S R E S E T , T H E N E N T E R V A L I D N UMB E +
A R ' 99 )
A 5 3 ' U S E F 3 T O E ND P R OG R AM , U S E E N T E R +
A T O R E T U R N T O P R OMP T S C R E E N '
A R CU S F L D S T E X T ( ' C U S T OME R D I S P L A Y ' )
A C A 0 3 ( 1 5 ' E ND O F P R OGR AM ' )
A OV E R L A Y
A 8 3 ' N AME '
A N AME R 8 11
A 9 3 ' AD D R E S S '
A AD D R R 9 11
A 1 /0 3 'CI TY '
A CI TY R 1 /0 11
A 11 3 ' S TAT E '
A S TAT E R 11 11
A 11 2 1 ' Z I P COD E '
A Z I P R 11 31
A 12 3 ' A / R B A L A NC E '
A AR B A L R 12 17
A
A
Figure 54. Example of the Data Description Specifications for a Display Device File
This display device file contains two record formats: CUSPMT and CUSFLDS.
.1/ The attributes for the fields in this file are defined in the CUSMSTP field refer-
ence file. For example, EDTCDE(J) is defined in CUSMSTP for the field
ARBAL.
.2/ The F3 key is associated with indicator 15, with which the user ends the
program.
.3/ The ERRMSG keyword identifies the error message that is displayed if indi-
cator 99 is set on in the program that uses this record format.
When the program requests an output operation, it passes the output record to the
operating system. The operating system provides the necessary device control
information to display the record. It also adds any constant information specified
for the record format when the record is displayed.
When a record passes to a program, the fields are arranged in the order in which
they are specified in the DDS. The order in which the fields are displayed is based
on the display positions (line numbers and positions) assigned to the fields in the
DDS. Therefore, the order in which the fields are specified in the DDS and the
order in which they appear on the display need not be the same.
When you define a record format for a file using DDS, you can condition the
options using indicators; indicators can also be used to reflect particular responses.
These indicators are known as OPTION and RESPONSE, respectively.
Indicators can be passed with data records in a record area, or outside the record
area in a separate indicator area.
The file control entry for a file that has INDARA specified in its DDS must have the
separate indicator area attribute, SI, as part of the assignment-name.
The number and order of indicators defined in the DDS for a record format for a file
determines the number and order in which the data description entries for the indi-
cators in the record format must be coded in the program.
The file control entry for a file that does not have the INDARA keyword specified in
the DDS associated with it must not have the separate indicator area attribute, SI,
as part of the assignment-name.
55───ASSIGN──┬────┬─────WORKSTATION───── -file-name──┬───────┬───────────────5%
└─TO─┘ └─ -SI─┘
For more information about the ASSIGN clause, see “ASSIGN Clause” on
page 172.
╔═══════════════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───level-number──┬───────────────┬──┬──────────────────────────┬──────────────────────5 ║
║ ├──data-name-1──┤ ├──REDEFINES──data-name-2──┤ ║
║ └──FILLER───────┘ └──LIKE───data-name-3──────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────┬──────────────────────────────────────────────────────5 ║
║ └──┬──PICTURE──┬─┬────┬──1──┘ ║
║ └──PIC──────┘ └─IS─┘ ║
║ ║
║ ║
║ 5────┬──────────────────────────────┬───────────────────────────────────────────────────5 ║
║ └──┬───────────────┬──DISPLAY──┘ ║
║ └──USAGE─┬────┬─┘ ║
║ └─IS─┘ ║
║ ║
║ ║
║ 5──┬────────────────────────────────────────────────────────────────────────────────────5 ± ║
║ └─OCCURS─┬─integer-1─TO─integer-2─┬───────┬─DEPENDING─┬────┬─data-name-4─┬───────────5 ² ║
║ │ └─TIMES─┘ └─ON─┘ │ ║
║ └─integer-2─┬───────┬───────────────────────────────────────────┘ ║
║ └─TIMES─┘ ║
║ ║
║ ║
║ ± 5──────────────────────────────────────────────┬────────────────────────────────────────5 ║
║ ² 5────┬──────────────────────────────────────┬──┘ ║
║ │ ┌─────────────┐ │ ║
║ │ 6 │ │ ║
║ └──INDEXED──┬────┬────index-name-1──┴──┘ ║
║ └─BY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────┬──────────────────────────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──integer-3─┘ ║
║ ├─INDICATORS─┤ ║
║ └─INDIC──────┘ ║
║ ║
║ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ 5────┬───────────────────────────────────┬──┬────────────────────────────┬──────────────5 ║
║ \ └──┬──SYNCHRONIZED──┬──┬─────────┬──┘ └──┬─JUSTIFIED─┬──┬───────┬──┘ \ ║
║ \ └──SYNC──────────┘ ├──LEFT───┤ └─JUST──────┘ └─RIGHT─┘ \ ║
║ \ └──RIGHT──┘ \ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────┬──.────────────────────────────────────────────5% ║
║ └──VALUE─┬────┬──Boolean-literal──┘ ║
║ └─IS─┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════════════════╝
Special Considerations
The special considerations for the clauses used with the Boolean data follow. All
other rules for clauses are the same as those for other data as described in the
“COBOL Program Structure” section of the COBOL/400 Reference.
For example, if the following is coded, SWITCHES (1) corresponds to indicator 16,
SWITCHES (2) corresponds to indicator 17,..., and SWITCHES (10) corresponds to
indicator 25:
ð7 SWITCHES PIC 1
OCCURS 1ð TIMES
INDICATOR 16.
VALUE Clause: The VALUE clause specifies the initial content of a Boolean data
item. The allowable values for Boolean literals are B"0", B"1", and ZERO.
LIKE Clause: You cannot use this clause to change the length of the data item.
INDICATORS Phrase
When the INDICATORS phrase is used in READ, REWRITE, and WRITE state-
ments (see Figure 57 on page 150), it specifies which indicators are to be read,
rewritten, and written.
The identifier specified in the INDICATORS phrase can be either of the following:
An elementary Boolean data item
A group item with elementary Boolean data items subordinate to it. (The
Boolean data items can be anywhere in the group, but they are the only items
you can read, write, or rewrite.)
The identifier cannot be subordinate to an item that is subject to an OCCURS
clause.
The contents of the identifier are not checked, but are copied to or from the begin-
ning of the record, on a byte-by-byte basis; indicator numbers are ignored.
If the INDICATORS phrase is omitted, the data in the indicator fields in the record
are still passed in the record area. The INDICATORS phrase is only used to copy
indicators into the record area before a WRITE or REWRITE statement, or out of
the record area after a READ statement.
Figure 56 on page 148 shows a program that uses indicators in the record area
but does not use the INDICATORS phrase in any I/O statement. Figure 55 on
page 147 shows the associated DDS for the file.
Figure 57 on page 150 shows a program that uses indicators in the record area
and the INDICATORS phrase in the I/O statements. The associated DDS for
Figure 57 is Figure 55 on page 147.
Figure 59 on page 153 shows a program that uses indicators in a separate indi-
cator area, defined in WORKING-STORAGE by using the Format 2 COPY state-
ment. Figure 58 on page 152 shows the associated DDS for the file.
Conditioning
Location
U s ag e ( b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 2 2 23 2 4 25 2 6 27 28 29 30 3 1 3 2 33 3 4 35 3 6 37 38 39 40 4 1 4 2 43 4 4 45 4 6 47 48 49 50 5 1 5 2 5 3 5 4 55 5 6 57 5 8 5 9 60 6 1 6 2 6 3 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80
A* D I S P L AY F I LE DD S F OR I ND I CA T OR E X AMP L E S
A*
A R F OR MA T 1 CF /0 3 ( 9 9 ' E ND O F P R OGR AM ' )
A CF /0 5 ( 5 1 ' D A I L Y R E P OR T ' )
A CF /0 9 ( 5 2 ' MON T H L Y R E P OR T ' )
A*
A 10 1 0 ' D E P A R T ME N T N UMB E R : '
A D E P T NO 5 I 10 32
A 01 20 2 6 ' P R OD U C E MON T H L Y R E P OR T S '
A DSPAT R ( B L )
A*
A 24 01 ' F5 = D A I L Y R E P OR T '
A 24 26 ' F9 = MON T H L Y R E P OR T '
A 24 53 ' F3 = T E RM I NA T E '
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
Figure 55. Example of a Program Using Indicators in the Record Area without Using the INDICATORS Phrase in the
I/O Statement–Data Description Specifications
.1/ The INDARA keyword is not used; indicators are stored in the record area
with the data fields.
.2/ One record format, FORMAT1, is specified.
.3/ Three indicators are associated with three function keys. Indicator 99 will be
set on when you press F3, and so on.
.4/ One field is defined for input.
.5/ Indicator 01 is defined to cause the associated constant field to blink if the
indicator is on.
.6/ The function (F) key definitions are documented on the work station display.
Figure 56 (Part 1 of 2). Example of a Program Using Indicators in the Record Area without Using the INDICATORS
Phrase in the I/O Statement–COBOL Source Program
Figure 56 (Part 2 of 2). Example of a Program Using Indicators in the Record Area without Using the INDICATORS
Phrase in the I/O Statement–COBOL Source Program
.1/ The separate indicator area attribute, SI, is not coded in the ASSIGN clause.
.2/ The Format 2 COPY statement defines data fields and indicators in the record
area.
.3/ Because the file does not have a separate indicator area, response and
option indicators are defined in the order in which they are used in the DDS,
and the indicator numbers are treated as documentation.
.4/ All indicators used by the program are defined with meaningful names in data
description entries in WORKING-STORAGE. Indicator numbers are omitted
here because they have no effect.
.5/ For each indicator, a meaningful level-88 condition-name is associated with a
value for that indicator.
.6/ Initialize group level to zeros.
.7/ IN01 in WORKING-STORAGE is set on if it is the first day of the month.
.8/ Indicators appropriate to the output of FORMAT1 are copied to the record
area.
.9/ FORMAT1 is written to the work station display with both data and indicator
values in the record area.
The INDICATORS phrase is not necessary because there is no separate indi-
cator area and indicator values have been set in the record area through the
previous MOVE CORRESPONDING statement.
.1ð/ FORMAT1, including both data and indicators, is read from the display.
.11/ The response indicators for FORMAT1 are copied from the record area to the
data description entries in WORKING-STORAGE.
.12/ If F5 has been pressed, a program call is processed.
Figure 57 (Part 1 of 2). Example of a Program Using Indicators in the Record Area and the INDICATORS phrase in
the I/O Statements–COBOL Source Program
Figure 57 (Part 2 of 2). Example of a Program Using Indicators in the Record Area and the INDICATORS phrase in
the I/O Statements–COBOL Source Program
.1/ The separate indicator area attribute, SI, is not coded in the ASSIGN clause.
.2/ The Format 2 COPY statement defines data fields and indicators in the
record area.
.3/ Because the file does not have a separate indicator area, response and
option indicators are defined in the order in which they are used in the DDS,
and the indicator numbers are treated as documentation.
.4/ All indicators used by the program are defined with meaningful names in
data description entries in WORKING-STORAGE. Indicator numbers are
omitted here because they have no effect. Indicators should be defined in
the order needed by the display file.
.5/ IN01 in WORKING-STORAGE is set on if it is the first day of the month.
.6/ FORMAT1 is written to the work station display:
The INDICATORS phrase causes the contents of the variable
OPTION-INDICS to be copied to the beginning of the record area.
Data and indicator values are written to the work station display.
.7/ FORMAT1, including both data and indicators, is read from the work station
display.
.8/ The INDICATORS phrase causes bytes to be copied from the beginning of
the record area to RESPONSE-INDICS.
.9/ If F5 has been pressed, a program call is processed.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
A* D I S P L AY F I LE DD S F OR I ND I CA T OR E X AMP L E S
A*
A I ND A R A
A R F OR MA T 1 CF 0 3 ( 9 9 ' E ND O F P R OGR AM ' )
A CF 0 5 ( 5 1 ' D A I L Y R E P OR T ' )
A CF 0 9 ( 5 2 ' MON T H L Y R E P OR T ' )
A*
A 10 1 0 ' D E P A R T ME N T N UMB E R : '
A D E P T NO 5 I 10 32
A 01 20 2 6 ' P R OD U C E MON T H L Y R E P OR T S '
A DSPAT R ( B L )
A*
A 24 01 ' F5 = D A I L Y R E P OR T '
A 24 26 ' F9 = MON T H L Y R E P OR T '
A 24 53 ' F3 = T E RM I NA T E '
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
Figure 58. Example of a Program Using Indicators in a Separate Indicator Area, Defined in WORKING-STORAGE by
Using the COPY Statement, DDS Format
.1/ The INDARA keyword is specified; indicators are stored in a separate indi-
cator area, not in the record area. Except for this specification, the DDS for
this file is the same as that shown in Figure 55 on page 147.
Figure 59 (Part 1 of 2). COBOL Listing Using Indicators in a Separate Indicator Area
Figure 59 (Part 2 of 2). COBOL Listing Using Indicators in a Separate Indicator Area
.1/ The separate indicator area attribute, SI, is specified in the ASSIGN clause.
.2/ The Format 2 COPY statement generates data descriptions in the record area
for data fields only. The data description entries for the indicators are not
generated because a separate indicator area has been specified for the file.
.3/ The Format 2 COPY statement, with the INDICATOR attribute, INDIC, defines
data description entries in WORKING-STORAGE for all indicators used in the
DDS for the record format for the file.
.4/ Because the file has a separate indicator area, the indicator numbers used in
the data description entries are not treated as documentation.
.5/ IN01 in the separate indicator area for FORMAT1 is set on if it is the first day
of the month.
.6/ The INDICATORS phrase is required to send indicator values to the work
station display.
.7/ The INDICATORS phrase is required to receive indicator values from the
work station display. If you have pressed F5, IN51 is set on.
.8/ If IN51 has been set on, a program call is processed.
Figure 60 (Part 1 of 2). Example of a Program Using Indicators in a Separate Indicator Area, Defined in a Table in
WORKING-STORAGE
Figure 60 (Part 2 of 2). Example of a Program Using Indicators in a Separate Indicator Area, Defined in a Table in
WORKING-STORAGE
.1/ The separate indicator area attribute, SI, is specified in the ASSIGN clause.
.2/ The Format 2 COPY statement generates fields in the record area for data
fields only.
.3/ A table of 99 Boolean data items is defined in WORKING-STORAGE. The
INDICATOR clause for this data description entry causes these data items to
be associated with indicators 1 through 99 respectively. The use of such a
table may result in improved performance as compared to the use of a group
item with multiple subordinate entries for individual indicators.
.4/ A series of data items is defined in WORKING-STORAGE to provide mean-
ingful subscript names with which to refer to the table of indicators. The use
of such data items is not required.
.5/ INDIC-TABLE (01) in the separate indicator area for FORMAT1 is set on if it
is the first day of the month.
.6/ The INDICATOR phrase is required to send indicator values to the work
station display.
.7/ The INDICATOR phrase is required to receive indicator values from the work
station display. If F5 has been pressed, INDIC-TABLE (51) will be set on.
.8/ If INDIC-TABLE (51) has been set on, program DAILY is called.
Subfiles
Subfiles can be specified in the DDS for a display file to allow you to handle mul-
tiple records of the same type on a display. See Figure 61 on page 157 for an
example of a subfile display. A subfile is a group of records that are read from or
written to a display device. The program processes one record at a time, but the
operating system and the work station send and receive blocks of records. If more
records are transmitted than can be shown on the display at one time, the work
station operator can page through the block of records without returning control to
the program.
The DDS for a subfile consists of two record formats: a subfile record format and a
subfile control record format.
The subfile record format contains the field descriptions for the records in the
subfile. Specifications of the subfile record format on a READ, WRITE, or
REWRITE causes the specified subfile record to be processed, but does not
directly affect the displayed data.
Specification of the subfile control record format on the READ or WRITE statement
causes the physical read, write, or setup operations of a subfile to take place.
Figure 62 on page 159 shows an example of the DDS for a subfile record format,
and Figure 63 on page 161 shows an example of the DDS for a subfile control
record format.
For a description of how the records in a subfile can be displayed and for a
description of the keywords that can be specified for a subfile, see the Data Man-
agement Guide and also the DDS Reference.
á ñ
Figure 61. Subfile Display
To use a subfile for a display file in a COBOL program, you must specify the
SUBFILE phrase with the input/output operation. Valid subfile operations are:
READ SUBFILE file-name RECORD
WRITE SUBFILE record-name
REWRITE SUBFILE record-name.
The TRANSACTION file must be an externally defined file. In COBOL, all access
to the subfile is done with a relative record number. If the SUBFILE phrases are
used with a TRANSACTION file, the SELECT statement in the Environment Divi-
sion must state that ACCESS MODE IS DYNAMIC and must specify the RELATIVE
KEY to be used.
If more than one display device is acquired by a display file, there is a separate
subfile for each individual display device. If a subfile has been created for a partic-
ular display device acquired by a TRANSACTION file, all input operations that refer
to a record format for the subfile are performed against the subfile belonging to that
device. See the discussion on the TERMINAL phrase on page 182 of this chapter
for information about how to determine which device is used. Any operations that
reference a record format name that is not designated as a subfile are processed
as an input/output operation directly to the display device.
Use of Subfiles
Some typical uses of subfiles include:
Use Meaning
Display Only The work station user reviews the display.
Display With Selection The user requests more information about one of the items on
display.
Modification The user modifies one or more of the records.
Input Only (with no validity checking) A subfile is used for a data-entry function.
Input Only (with validity checking) A subfile is used for a data-entry function, and the records are
checked as well.
Combination of Tasks A subfile can be used as a display with modification.
Location
Us ag e (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 23 2 4 25 2 6 27 2 8 29 30 3 1 32 33 3 4 35 3 6 37 38 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* DD S F OR T H E D I S P L A Y D E V I C E F I L E P A Y U P D T D
A* ACCOU N T S R E C E I V A B L E I N T E R AC T I V E P A Y ME N T UP DA T E
A*
A R S UB F I L E 1 SFL
A T E X T ( ' S UB F I L E F OR C U S T OME R P A Y ME N T ' )
A*
A AC P P M T 4A I 5 4 T E X T ( ' ACC E P T P A Y ME N T ' )
A V A L U E S ( ' * Y E S ' ' * NO ' )
A 51 D S P A T R ( R I MD T )
A N5 1 D S P A T R ( ND P R )
A*
A CU S T 5 B 5 15TEXT ( ' C U S T OME R N UMB E R ' )
A 52 DSPAT R(R I )
A 53 DSPAT R ( ND )
A 54 DSPAT R ( PR )
A*
A AMP A I D 8 02B 5 2 4 T E X T ( ' AMOU N T PA I D ' )
A CH E CK ( F E )
A AU T O( R AB )
A CMP ( G T 0 )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A E CP MS G 3 1A O 5 37TEXT ( ' E X C E P T I ON ME S S AG E ' )
A 52 DSPAT R(R I )
A 53 DSPAT R ( ND )
A 54 DSPAT R(BL )
A*
A OV R P M T 8Y 2O 5 7 0 T E X T ( ' OV E R P A Y ME N T ' )
A E D T CD E ( 1 )
A 55 DSPAT R ( B L )
A N5 6 D S P A T R ( ND )
A*
A S T S CD E 1A H T E X T ( ' S T A T U S COD E ' )
The data description specifications (DDS) for a subfile record format describe the
records in the subfile:
.1/ The SFL keyword identifies the record format as a subfile.
.2/ The line and position entries define the location of the fields on the display.
.3/ The VALUES keyword specifies that the user can only specify *YES or *NO
as values for the ACPPMT field.
.4/ The usage entries define whether the named field is to be an output (O), input
(I), output/input (B), or hidden (H) field.
.5/ The entry CHECK(FE) specifies that the user cannot skip to the next input
field without pressing one of the field exit keys.
Location
Us ag e (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 23 2 4 25 2 6 27 2 8 29 30 3 1 32 33 3 4 35 3 6 37 38 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
Figure 63. Data Description Specifications for a Subfile Control Record Format
The subfile control record format defines the attributes of the subfile, the search
input field, constants, and command keys. The keywords used indicate the fol-
lowing:
.1/ SFLCTL identifies this record as a subfile control record and names the
associated subfile record (SUBFILE1).
.2/ SFLSIZ indicates the total number of records to be included in the subfile
(17).
.3/ SFLPAG indicates the total number of records in a page (17).
.4/ SFLCLR indicates when the subfile should be cleared (when indicator 61 is
on).
.5/ SFLDSP indicates when to display the subfile (when indicator 62 is on).
.6/ SFLDSPCTL indicates when to display the subfile control record (when indi-
cator 62 is on).
In addition to the control information, the subfile control record format defines the
constants to be used as column headings for the subfile record format. Refer to
Figure 63 on page 161 for an example of the subfile control record format.
A single device file is a device file created with only one program device defined
for it. Printer files, diskette files and tape files are single device files. Display files
and intersystem communication function (ICF) files created with a maximum
number of one program device are also single device files.
A display file can have multiple program devices when the MAXDEV parameter of
the CRTDSPF command is greater than 1. If you specify *NONE for the DEV
parameter of this command, you must supply the name of a display device before
you use any fields that are related to the file.
For more information about how to create and use a display file, see the Data Man-
agement Guide.
ICF files can have multiple program devices when the MAXPGMDEV parameter of
the CRTICFF command is greater than 1. For more information about how to
create and use ICF files, see the ICF Programmer’s Guide.
COBOL determines at run time whether a file is a single device file or a multiple
device file, based on whether the file is capable of having multiple devices. The
actual number of devices acquired does not affect whether a file is considered a
single or multiple device file. Whether a file is a single or a multiple device file is
not determined at compilation time; this determination is based on the current
description of the display or ICF file.
For multiple device files, if a particular program device is to be used in an I/O state-
ment, that device is specified by the TERMINAL phrase. The TERMINAL phrase
can also be specified for a single device file.
The following pages contain an example illustrating the use of multiple device files.
The program uses a display file, and is intended to be run in batch mode. The
program acquires terminals and invites those terminals using a sign-on display.
After the terminals are invited, they are polled. If nobody signs on before the wait
time expires, the program ends. If you enter a valid password, you are allowed to
update an employee file by calling another COBOL program. Once the update is
complete, the device is invited again and the terminals are polled again.
Location
U s a g e (/ b / O / I / B / H / M / N / P )
And/Or /Comment (A/O/* )
Reference (R)
Sequence
Number
For m Type
Po s i t i o n s
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 1 4 15 16 17 18 19 2 0 2 1 22 2 3 24 2 5 26 27 2 8 29 3 0 3 1 32 3 3 34 3 5 36 37 38 39 4 0 4 1 4 2 4 3 44 4 5 46 4 7 48 49 50 5 1 5 2 53 5 4 55 5 6 5 7 58 5 9 60 6 1 6 2 63 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80
A*
A * DD S F OR T H E MU L T I P L E D E V I C E D I S P L A Y F I L E
A*
A R S I GNON I NV I T E
A O 5 20 / 'b /b /b/ /b /b/b/b/b/b/b/b/b/b/b/b/b/ b/ b/ b/ b/ '
A DSPAT R ( R I )
A O 6 20 / ' b/ b/ '
A DSPAT R ( R I )
A O 6 3 8 ' b/ b/ '
A
The f or mat SI GNON has DSPAT R ( R I )
A O 7 20 / ' b/ b/ '
the
A keyword INVI TE DSPAT R ( R I )
as s oc A i a t e d wi t h i t . T h i s O 7 27 'M D F '
means A that, i f f ormat SI GNON DSPAT R ( H I B L )
A O 7 3 8 ' b/ b/ '
i s usAed i n a WRI T E s t at ement , DSPAT R ( R I )
the Adevi ce to whi ch i t i s O 8 20 / ' b/ b/ '
wr i t iAng wi l l be i nvi t ed. DSPAT R ( R I )
A O 8 3 8 ' b/ b/ '
A DSPAT R ( R I )
A O 9 20 / ' /b /b/b/b/b/b/b/b/b/b/b/b/ b/ b/ b/ b/ b/ b
/b/b/ '
A DSPAT R ( R I )
A O 2 0/ 2 0 / ' P L E A S E L OGON '
A DSPAT R ( H I )
A P A S SWOR D 1 /0 A I 2 0/ 4 3 D S P A T R ( P C ND )
A WR ONG 2 /0 A O 21 43
A R U P DA T E
A O 3 5 ' U P DA T E OF P E R S ONN E L F I L E '
A DSPAT R ( B L )
A O 7 5 ' T Y P E I N E MP L OY E E NUMB E R +
A T O B E U P DA T E D '
A NUM 7A I 7 4 4D S P A T R ( R I PC )
A R E MP L OY E E
A O 3 5 ' E MP L OY E E NUMB E R '
A NUM 7A B 3 2 5D S P A T R ( PC )
A O 5 5 ' E MP L OY E E NAME '
A NAME 3 /0 A B 5 2 5D S P A T R ( PC )
A O 7 5 ' E MP L OY E E ADD R E S S '
A O 9 5 ' S TREE T '
A S TREE T 3 /0 A B 9 2 5D S P A T R ( PC )
A O 11 5 ' AP AR T ME N T NUMB E R '
A AP T NO 5A B 1 1 2 5 ' D S P A T R ( PC )
A O 13 5 'CI TY '
A CI TY 2 /0 A B 1 3 2 5D S P A T R ( PC )
A O 15 5 ' P R OV I NC E '
A P R OV 2 /0 A B 1 5 2 5D S P A T R ( PC )
A R R E COV E R Y
A O 3 5 ' T H E E MP L OY E E NUMB E R YOU +
A HAV E G I V E N I S I NVA L I D '
A O 6 5 ' T YP E Y TO R E T R Y '
A O 8 5 ' T YP E N TO E X I T '
A AN SWE R 1X I 1 0/ 5D S P A T R ( R I PC )
A VA L U E S ( ' Y ' ' N ' )
A
A
A
A
A
A
Location
U s ag e ( b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80
A*
A* DD S F OR T HE P H Y S I CA L F I LE P A S S WOR D
A*
A U N I QU E
A R PAS S WOR D S
A PAS SKEY 1 0/
A PAS S WOR D 10 /
A K PAS SKEY
A
A
A
A
A
A
A
A
A
A
A
A
Location
U s ag e ( b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 1 4 15 16 17 18 19 20 2 1 22 2 3 24 2 5 26 27 2 8 29 3 0 3 1 32 3 3 34 3 5 36 37 38 39 4 0 4 1 4 2 4 3 44 4 5 46 4 7 48 49 50 5 1 5 2 5 3 5 4 55 5 6 5 7 58 5 9 60 6 1 6 2 63 6 4 65 6 6 6 7 68 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80
A*
A * D D S F OR T H E P H Y S I CA L F I L E T E R M
A * WH I C H CON T A I N S T H E L I S T O F T E R M I N A L S
A*
A R T E RM
A T E RM 1 0/
A
A
A
A
A
A
A
A
A
A
A
A
A
A
Figure 65 (Part 1 of 4). COBOL Source Listing for Multiple Device File Support
Figure 65 (Part 2 of 4). COBOL Source Listing for Multiple Device File Support
Figure 65 (Part 3 of 4). COBOL Source Listing for Multiple Device File Support
Figure 65 (Part 4 of 4). COBOL Source Listing for Multiple Device File Support
File-Control Entry
The TRANSACTION file must be named by a file-control entry in the
FILE-CONTROL paragraph. This entry also specifies other information related to
the file.
Format
╔═══════════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ \ ┌───────────────────┐ \ ║
║ \ │ │ \ ║
║ \\6\\\\\\\\\\\\\\\\\\\│\\ ║
║ 55───SELECT──file-name────ASSIGN──┬────┬────┬─assignment-name-1─┼───────────────────────5 ║
║ └─TO─┘ └─literal-1─────────┘ ║
║ ║
║ ║
║ ║
║ ║
║ 5────┬───────────────────────┬──TRANSACTION─────────────────────────────────────────────5 ║
║ └──ORGANIZATION─┬────┬──┘ ║
║ └─IS─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────────────────────────────────────┬──5 ║
║ └──ACCESS──┬──────┬──┬────┬──┬─SEQUENTIAL───────────────────────────────────────┤ ║
║ └─MODE─┘ └─IS─┘ └─DYNAMIC───RELATIVE──┬─────┬──┬────┬──data-name-3─┘ ║
║ └─KEY─┘ └─IS─┘ ║
║ ║
║ 5────┬──────────────────────────────────────────────────────────┬───────────────────────5 ║
║ └─┬──────┬──STATUS─┬────┬──data-name-1──┬───────────────┬──┘ ║
║ └─FILE─┘ └─IS─┘ └──data-name-5──┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬────.──────────────────────────────────────5% ║
║ └──CONTROL-AREA──┬────┬──data-name-6──┘ ║
║ └─IS─┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════════════╝
Format
55───ASSIGN──┬────┬─────WORKSTATION───── -file-name──┬───────┬───────────────5%
└─TO─┘ └─ ─SI─┘
Device specifies the type of device associated with the file. The value must be
WORKSTATION.
The AS/400 file name is a one-to-ten character external name of the display file or
ICF file specified on the create device file commands, CRTDSPF or CRTICFF.
The attribute -SI is used to specify the file level option for a separate indicator area.
See “Using Indicators with Transaction Files” on page 142 for further details.
ORGANIZATION Clause
The ORGANIZATION clause specifies the logical structure of a file. TRANS-
ACTION organization signifies interaction between the program and either a work
station user or another system.
In some cases, all records are homogeneous; that is, a logical transaction is com-
pleted with one exchange of records. In other situations, a series of records is
passed back and forth in a logical progression with various record types either
being selected by the initiator or as part of the processing based on input data
values.
For more information about the FILE STATUS clause, refer to “File Status and
Feedback Areas” on page 103. General considerations about the FILE STATUS
clause and data-name-1 are described in Part 2 of the COBOL/400 Reference in
the section, “FILE STATUS Clause.”
For information about the role of file status in error handling, refer to Chapter 6,
“COBOL/400 Exception and Error Handling” on page 69.
01 data-name-6.
02 function-key PIC X(2).
(Function key feedback field)
02 device-name PIC X(10).
(Program device name)
02 record-format PIC X(10).
(Record format)
Information is moved into data-name-6 for each READ operation from a file that
has been assigned to a WORKSTATION device type. The information is valid only
if the READ operation is successfully completed (provided the wait time has not
expired). The information is in the fixed format as shown in the following example:
FILE-CONTROL.
SELECT SCREEN-FILE
ASSIGN TO WORKSTATION-MYFMTS
ORGANIZATION IS TRANSACTION
CONTROL-AREA IS
TRANSACTION-CONTROL-AREA.
..
.
WORKING-STORAGE SECTION.
ð1 TRANSACTION-CONTROL-AREA.
\ FEEDBACK ITEM
ð2 FUNCTION-KEY PIC XX.
ð2 TERMINAL-ID PIC X(1ð).
ð2 FORMAT-NAME PIC X(1ð).
00 Enter key
01-24 Function keys 1 through 24
90 Roll Up/Page Down key
91 Roll Down/Page Up key
92 Print key
93 Help key
94 Clear key
95 Home key
99 Undefined
Any function keys for which feedback information is desired must be defined for
the display file using DDS.
TERMINAL-ID: The program device name.
FORMAT-NAME: The DDS record format name that was referenced by the last
I/O statement run.
Data Division
╔═══════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───FD────file-name──────────────────────────────────────────────────────────5 ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────────────────────────────────────┬──5 ║
║ └──RECORD─┬──────────┬──┬─────────────────┬─integer-4──┬────────────┬─┘ ║
║ └─CONTAINS─┘ └──integer-3 TO───┘ └─CHARACTERS─┘ ║
║ ║
║ ║
║ 5────┬────────────────────────────────────────────────────┬───────────────────5 ║
║ │ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ │ ║
║ └────LABEL──┬──RECORD──┬────┬───┬──┬──STANDARD──┬────┘ ║
║ \ │ └─IS─┘ │ └──OMITTED───┘ \ ║
║ \ └──RECORDS─┬─────┬──┘ \ ║
║ \ └─ARE─┘ \ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────────────────┬──.──────────────────5% ║
║ │ ┌───────────┐ │ ║
║ │ 6 │ │ ║
║ └──DATA──┬──RECORD──┬────┬───┬─────data-name-2─┴──┘ ║
║ │ └─IS─┘ │ ║
║ └──RECORDS─┬─────┬──┘ ║
║ └─ARE─┘ ║
║ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝
The LABEL RECORDS clause specifies whether or not labels are present. This
clause is required in every file description entry. This clause is syntax-checked, but
is treated as documentation.
Procedure Division
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───ACCEPT────identifier-1────FROM────mnemonic-name──────────────────────────5 ║
║ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────────┬───────────────────5% ║
║ └──FOR──┬──identifier-2──┬──┬────────────────────┬──┘ ║
║ └──literal-1─────┘ └──FOR──file-name-1──┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
This format of the ACCEPT statement can only be used for files with an organiza-
tion of TRANSACTION. Mnemonic-name must be associated with the function-
name ATTRIBUTE-DATA in the SPECIAL-NAMES paragraph.
If file-name is not specified, the default file for the ACCEPT statement is the first
TRANSACTION file specified in a SELECT clause of the FILE-CONTROL para-
graph.
If both FOR phrases are omitted (indicating the default TRANSACTION file is being
used), the ACCEPT statement uses the program device from which a READ,
WRITE, REWRITE, or ACCEPT (Attribute Data) operation on the default file was
most recently performed. If the only prior operation on the file was an OPEN, the
ACCEPT statement uses the program device implicitly acquired by the file when the
file was opened. When both FOR phrases are omitted, a program device must
have been acquired to use this particular format of the ACCEPT statement.
Program device attributes are moved into identifier-1 from the appropriate attribute
data format, according to the rules for a group MOVE without the CORRE-
SPONDING phrase.
ACQUIRE Statement
The ACQUIRE statement acquires a program device for a TRANSACTION file.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───ACQUIRE──┬──identifier──┬──FOR──file-name──────────────────────────────5% ║
║ └──literal─────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
Successful completion of the ACQUIRE operation makes the program device avail-
able for input and output operations.
If the ACQUIRE operation is unsuccessful, the file status value is set to 9H and the
USE AFTER EXCEPTION/ERROR procedure is called (if specified). For more
information, refer to Chapter 6, “COBOL/400 Exception and Error Handling.”
Only one program device can be implicitly acquired when a file is opened. If a file
is an ICF file, the single implicitly acquired program device is determined by the
ACQPGMDEV parameter of the CRTICFF command. If the file is a display file, the
The ACQUIRE statement can also be used as an aid in recovering from I/O errors.
For more information, see the “ACQUIRE Statement” section of the COBOL/400
Reference.
CLOSE Statement
The CLOSE statement terminates the processing of volumes and files, with optional
lock where applicable.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ┌──────────────────────────────┐ ║
║ 6 │ ║
║ 55───CLOSE──file-name-1──┬─────────────────┼─────────────────────────────────5% ║
║ └──┬──────┬─LOCK──┘ ║
║ └─WITH─┘ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
For a detailed discussion of the CLOSE statement, see the “CLOSE Statement”
section of the COBOL/400 Reference.
DROP Statement
The DROP statement releases a program device that has been acquired by a
TRANSACTION file.
DROP Statement
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───DROP──┬─identifier─┬──FROM──file-name───────────────────────────────────5% ║
║ └─literal────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
File-name must refer to a file with an organization of TRANSACTION, and the file
must be open to be used in the DROP statement. If no DROP statement is issued,
program devices attached to a TRANSACTION file are implicitly released when that
file is finally closed.
Program devices specified in a DROP statement must have been acquired by the
TRANSACTION file, either through an explicit ACQUIRE or through an implicit
ACQUIRE at OPEN time.
After successful running of the DROP statement, the program device is no longer
available for input or output operations through the TRANSACTION file. The
device can be reacquired if necessary. The contents of the record area associated
with a released program device are no longer available, even if the device is reac-
quired.
The DROP statement can also be used as an aid in recovering from I/O errors.
For more information, see the “DROP Statement” section of the COBOL/400
Reference.
OPEN Statement
The OPEN statement initiates the processing of files.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ┌─────────┐ ║
║ 6 │ ║
║ 55───OPEN I-O──file-name─┴───────────────────────────────────────────────────5% ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
A TRANSACTION file must be opened in the I/O mode. For a further discussion of
the OPEN statement, see the COBOL/400 Reference.
The OPEN statement can cause a program device to be implicitly acquired for a
TRANSACTION file. For a further discussion about the acquiring of program
devices, see the “ACQUIRE Statement” on page 178.
FORMAT Phrase
The literal or identifier specified must be a character string of 10 characters or
fewer in length.
Multiple data records, each with a different format, can be concurrently active for a
TRANSACTION file. If the FORMAT phrase is specified, it must specify a valid
format name that is defined to the system, and the I/O operation must be per-
formed on a data record of the same format. If the format is an invalid name or if it
does not exist, the FILE STATUS data item, if specified, is set to a value of 9K and
the contents of the record area are undefined.
When the FORMAT phrase is not specified, DB-FORMAT-NAME can be used if the
file contains a default record format name. The default value is always moved to
the DB-FORMAT-NAME special register.
INDICATORS Phrase
The identifier specified in the INDICATORS phrase must be either an elementary
Boolean data item specified without the OCCURS clause or a group item that has
elementary Boolean data items subordinate to it.
When a data record is read, indicators can be read with it. The indicators can be
used to pass information about the data record and how it was entered into your
program.
By defining a format using DDS, you determine what functions are to be controlled
by indicators, and which indicators control a particular function.
For detailed information on the INDICATORS phrase, refer to “Using Indicators with
Transaction Files” on page 142.
When SUBFILE is not specified, the RELATIVE KEY data item associated with the
file, if specified, is not referenced or changed by the I/O operation.
When SUBFILE is specified, a RELATIVE KEY data item must be defined for the
file. Its value is referenced, and sometimes changed, by the I/O operation. See
each of the statements associated with SUBFILE operations for a detailed
description of when and how the RELATIVE KEY data item is changed.
TERMINAL Phrase
When the TERMINAL phrase is specified, it indicates a specific program device is
to be used for a READ, WRITE, or REWRITE operation on a TRANSACTION file.
The TERMINAL phrase can be omitted for I/O operations on single device files,
because that device is always used.
For a READ statement with both the TERMINAL phrase and the NO DATA phrase
specified, the imperative-statement in the NO DATA phrase is run only if data is not
immediately available from the program device specified by the TERMINAL phrase.
If the TERMINAL phrase is specified and the data-item or literal has a value of
blanks, the phrase is treated at run time as if it were not specified.
READ Statement
The READ statement makes available a record from a device, using a named
format. If the format is a subfile, the READ statement makes available a specified
record from that subfile.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───READ──file-name──┬────────┬──────────────────────────────────────────────5 ║
║ └─RECORD─┘ ║
║ ║
║ 5────┬──────────────────────┬─────────────────────────────────────────────────5 ║
║ └──INTO──identifier-1──┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────┬────────────────────────────────────5 ║
║ └──FORMAT─┬────┬──┬─identifier-2─┬──┘ ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬──────────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────┬────────────────────────────────────5 ║
║ └──NO DATA──imperative-statement-1──┘ ║
║ ║
║ ║
║ 5────┬────────────────────────────────────┬───────────────────────────────────5 ║
║ └─┬────┬─END──imperative-statement-2─┘ ║
║ └─AT─┘ ║
║ ║
║ ║
║ 5────┬──────────────────────────────────────────┬──┬──────────┬──────────────5% ║
║ └──NOT─┬────┬─END──imperative-statement-3──┘ └─END-READ─┘ ║
║ └─AT─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
Format 4 is used only to read a format that is not a subfile. The RELATIVE KEY
data item, if specified in the FILE-CONTROL entry, is not used. The Format 4
READ statement is not valid for a subfile record. However, a Format 4 READ
statement for the subfile control record format must be used to place those subfile
records that were updated on a display into the subfile.
If the requested data is available, it is returned in the record area. The names of
the record format and the program device are returned in the I-O-FEEDBACK area
in the CONTROL-AREA.
The READ statement is valid only when there are acquired devices for the file. If a
READ is processed and there are no acquired devices, the file status is set to 92
(logic error).
In the following sections, references to data available or returned include the situ-
ation where only the response indicators are set. This also applies even when a
separate indicator area is used and the indicators are not returned in the record
area for the file.
The following chart shows the possible combinations of phrases and the function
performed for a single device file or a multiple device file. For example, if
TERMINAL is N, FORMAT is N, and NO DATA is N, the single device is D and
multiple device is A.
Code A–Read From Invited Program Device (Multiple Device Files only)
This type of READ receives data from the first invited program device that has data
available. Invited program devices are work stations or other communication
devices that are invited to send input. The inviting is done by writing to the
program device with a format specifying the DDS keyword INVITE. Once an invited
program device is actually read from, it is no longer invited. That program device
will not be used for input by another READ statement unless reinvited, or unless a
READ is directed to it specifying the TERMINAL phrase or FORMAT phrase.
The record format returned from the program device is determined by the system.
See the chapter on display device support in the Data Management Guide for infor-
mation on how record format is determined for work stations. See the ICF
Programmer’s Guide for information on the FMTSLT parameter on the
ADDICFDEVE and OVRICFDEVE commands.
This READ can be completed without returning any data in the following cases:
If there are no invited devices.
If a controlled cancelation of the job occurs. This results in a file status value
of 9A and a major/minor return code value of 0309.
2 If the phrase is specified and the data item or literal is blank, the phrase is treated at run time as if it were not specified.
If data is available, it is returned in the record area. The record format is returned
in the I-O-FEEDBACK area and in the CONTROL-AREA. For more information
about “Reading from Invited Program Devices,” see the ICF Programmer’s Guide.
This function of the READ statement never causes program processing to stop and
wait until data is available. Either the data is immediately available or the NO
DATA imperative-statement is processed.
This READ function can be used to periodically check if data is available from a
particular program device (either the default program device or one specified by the
TERMINAL phrase). This checking for data is done in the following manner:
1. The program device is determined as follows:
a. If the TERMINAL phrase was omitted or contains blanks, the default
program device is used. The default program device is the one used by
the last attempted READ, WRITE, REWRITE, ACQUIRE, or DROP state-
ment. If none of the above I/O operations were previously issued, the
default program device is the first program device acquired.
b. If the TERMINAL phrase was specified, the indicated program device is
used.
2. A check is done to determine if data is available and if the program device is
invited.
3. If data is available, that data is returned in the record area and the program
device is no longer invited. If no data is immediately available, the NO DATA
imperative-statement is run and the program device remains invited.
4. If the program device is not invited, the AT END condition exists and the file
status is set to 10.
This READ always waits for data to be made available. Even if the job receives a
controlled cancellation, or a WAITRCD time is specified for the file, the program will
never regain control from the READ statement. This READ operation is performed
in the following manner:
INTO Phrase
The INTO phrase can be specified if:
Only one record description is subordinate to the file description entry,
OR
All record names associated with file-name and the data item referenced by
identifier-1 describe a group item or an elementary alphanumeric item.
FORMAT Phrase
Literal-1 or identifier-2 specifies the name of the record format to be read. Literal-1,
if specified, must be nonnumeric and 10 characters or fewer in length. Identifier-2,
if specified, must refer to an alphanumeric data item, 10 characters or fewer in
length. If identifier-2 contains blanks, the READ statement is run as if the FORMAT
phrase were omitted.
NO DATA Phrase
When the NO DATA phrase is specified, the READ statement determines if data is
immediately available. If data is available, the data is returned in the record area.
If no data is immediately available, imperative-statement-1 is processed. The NO
DATA phrase prevents the READ statement from waiting for data to become avail-
able.
If the TERMINAL phrase is omitted for a READ of a TRANSACTION file that has
acquired multiple program devices, the default program device is used. See the
discussion of the TERMINAL phrase on page 182, to see how the default program
device is determined.
AT END Phrase
Imperative-statement-2 is performed when the AT END condition is detected.
Note: An AT END condition occurs at the following times:
During a READ statement for a sequentially accessed file when no next logical
record exists in the file, or when the number of significant digits in the relative
record number is larger than the size of the relative key data item, or when an
optional input file is not present.
During a RETURN statement when no logical record exists for the associated
sort or merge file.
During a SEARCH statement when the search operation ends without satisfying
the condition specified in any of the associated WHEN phrases.
END-READ Phrase
The END-READ phrase serves to explicitly delimit the scope of the statement.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───READ SUBFILE──file-name──────────────────────────────────────────────────5 ║
║ ║
║ ║
║ 5────┬────────────────────┬──┬────────┬───────────────────────────────────────5 ║
║ └─┬──────┬─MODIFIED──┘ └─RECORD─┘ ║
║ └─NEXT─┘ ║
║ ║
║ 5────┬──────────────────────┬─────────────────────────────────────────────────5 ║
║ └──INTO──identifier-1──┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────┬────────────────────────────────────5 ║
║ └──FORMAT─┬────┬──┬─identifier-2─┬──┘ ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────TERMINAL─┬────┬──┬─identifier-3─┬────────────────────────────────────────5 ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────┬────────────────────────────5 ║
║ └──INVALID─┬─────┬──imperative-statement-1──┘ ║
║ └─KEY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬────────────────────────5 ║
║ └──NOT INVALID─┬─────┬──imperative-statement-2──┘ ║
║ └─KEY─┘ ║
║ ║
║ 5────┬────────────────────────────────────┬───────────────────────────────────5 ║
║ └─┬────┬─END──imperative-statement-3─┘ ║
║ └─AT─┘ ║
║ ║
║ ║
║ 5────┬──────────────────────────────────────────┬──┬──────────┬──────────────5% ║
║ └──NOT─┬────┬─END──imperative-statement-4──┘ └─END-READ─┘ ║
║ └─AT─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
Format 5 is used only to read a format that is a subfile record. The AT END
phrase can only be used when the NEXT MODIFIED phrase is specified. The
INVALID KEY phrase must not be used when the NEXT MODIFIED phrase is spec-
ified.
Random Access of Subfile Records: The NEXT MODIFIED phrase must not be
used to randomly access records in a subfile. The INVALID KEY phrase can only
be used for random access of subfile records.
When the NEXT MODIFIED phrase is not specified, and if the RELATIVE KEY data
item contains a value other than the relative record number of a record in the
subfile, the INVALID KEY condition exists and the running of the READ statement
is unsuccessful.
When the NEXT MODIFIED phrase is specified, the record made available is the
next modified record following the current pointer position in the file. For informa-
tion about turning on the Modified Data Tag, see the Data Management Guide.
The value of the RELATIVE KEY data item is updated to reflect the relative record
number of the record made available to the program.
FORMAT Phrase
When a format-name is not specified, the format used is the last record format
written to the display device that contains input fields, input/output fields, or hidden
fields. If no such format exists for the display file, the format used is the record
format of the last WRITE operation to the display device.
Note: An input field is a field specified in a display file or database file that is
reserved for information supplied by a user.
TERMINAL Phrase
See Format 4 of the READ Statement for general considerations concerning the
TERMINAL phrase.
For a Format 5 READ, if the TERMINAL phrase is omitted for a file that has mul-
tiple devices acquired for it, a record is read from the subfile associated with the
default program device. See the discussion of the TERMINAL phrase on page 182,
to see how the default program device is determined.
| For a Format 5 READ, you should specify the INVALID KEY phrase if the NEXT
MODIFIED phrase is not specified and there is no applicable USE procedure speci-
fied for the file name.
AT END Phrase
If the NEXT MODIFIED phrase is specified and there is no user-modified record in
the subfile, the AT END condition exists, and the READ operation is unsuccessful.
Specify the AT END phrase when the NEXT MODIFIED phrase is used, and no
applicable USE procedure is specified for the file name. If the AT END phrase and
a USE procedure are both specified for a file, and the AT END condition arises,
control transfers to the AT END imperative statement and the USE procedure is not
run.
END-READ Phrase
The END-READ phrase serves to explicitly delimit the scope of the statement.
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───REWRITE SUBFILE──record-name-1─┬──────────────────────┬────────────────5 ║
║ └──FROM──identifier-1──┘ ║
║ ║
║ ║
║ 5───FORMAT─┬────┬──┬─identifier-2─┬───────────────────────────────────────────5 ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬──────────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────┬────────────────────────────5 ║
║ └──INVALID─┬─────┬──imperative-statement-1──┘ ║
║ └─KEY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬─┬─────────────┬───────5% ║
║ └──NOT INVALID─┬─────┬──imperative-statement-2──┘ └─END-REWRITE─┘ ║
║ └─KEY─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
FORMAT Phrase
The record format specified in the FORMAT phrase must be the record format
accessed on the previous READ operation. Literal-1 or the contents of identifier-2
must be the name of the subfile format accessed on the previous READ. For more
information on the FORMAT phrase, see “Common Processing Facilities” on
page 181.
If the TERMINAL phrase is omitted from a TRANSACTION file that has acquired
multiple program devices, the subfile used is the subfile associated with the last
program device from which a READ of the TRANSACTION file was attempted.
END-REWRITE Phrase
The END-REWRITE phrase serves to explicitly delimit the scope of the statement.
╔═════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───WRITE──record-name-1──┬────────────────────┬─────────────────────────────5 ║
║ └─FROM──identifier-1─┘ ║
║ ║
║ ║
║ 5────FORMAT─┬────┬──┬─identifier-2─┬──────────────────────────────────────────5 ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ 5────┬─────────────────────────────────────┬──────────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬────────────────────────5 ║
║ └──STARTING─┬────┬──┬──────┬──┬─identifier-4─┬──┘ ║
║ └─AT─┘ └─LINE─┘ └─literal-3────┘ ║
║ ║
║ ║
║ 5────┬────────────────────────────────────────────────────────────────────────5 ± ║
║ └──┬─BEFORE─┬──ROLLING──┬───────┬──┬─identifier-5─┬──────────────────────5 ² ║
║ └─AFTER──┘ ├─LINES─┤ └─literal-4────┘ ║
║ └─LINE──┘ ║
║ ║
║ ║
║ ± 5──────────────────────────────────────────────────────────────────────────┬──5 ║
║ ² 5────┬─────────┬──┬─identifier-6─┬──┬─UP───┬──┬─identifier-7─┬──┬───────┬──┘ ║
║ ├─THROUGH─┤ └─literal-5────┘ └─DOWN─┘ └─literal-6────┘ ├─LINES─┤ ║
║ └─THRU────┘ └─LINE──┘ ║
║ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬──┬───────────┬────────────────5% ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-8─┘ └─END-WRITE─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════════╝
TERMINAL Phrase
The TERMINAL phrase specifies the program devices to which the output record is
to be sent.
The contents of literal-2 or identifier-3 must be the name of a program device previ-
ously acquired, either implicitly or explicitly, by the file. Literal-2, if specified, must
be nonnumeric and 10 characters or fewer in length. Identifier-3, if specified, must
refer to an alphanumeric data item, 10 characters or fewer in length. A value of
blanks is treated as if the TERMINAL phrase were omitted.
If only a single program device was acquired by the TRANSACTION file, the
STARTING Phrase
The STARTING phrase specifies the starting line number for the record formats
that use the variable start line keyword. This phrase is only valid for display
devices.
The actual line number on which a field begins can be determined from the fol-
lowing equation:
Where:
Actual-line is the actual line number
Start-line is the starting line number specified in the program
DDS Start-line is the line number specified in positions 39 through 41 of the
Data Description Specifications form.
If the value specified for the STARTING phrase is within the screen area, any fields
outside of the screen area are ignored.
To use the STARTING phrase, the DDS record level keyword SLNO(*VAR) must
be specified for the format being written. If the record format does not specify this
keyword, the STARTING phrase is ignored at run time.
The DDS keyword CLRL also affects the STARTING phrase. CLRL controls how
much of the display is cleared when the WRITE statement is processed.
ROLLING Phrase
The ROLLING phrase allows you to move lines displayed on the work station
screen. All or some of the lines on the screen can be rolled up or down. The lines
vacated by the rolled lines are cleared, and can have another screen format written
into them. This phrase is only valid for display devices.
ROLLING is specified in the WRITE statement that is writing a new format to the
display You must specify whether the write is before or after the roll, the range of
lines you want to roll, how many lines you want to roll these lines, and whether the
roll operation is up or down.
After lines are rolled, the fields on these lines retain their DDS display attributes, for
example, underlining, but lose their DDS usage attributes, for example, input-
capability. Fields on lines that are written and then rolled (BEFORE ROLLING
phrase) also lose their usage attributes.
If any part of a format is rolled, the entire format loses its usage attributes. If more
than one format exists, only the rolled formats lose their usage attributes.
When you specify the ROLLING phrase, the following general rules apply.
The DDS record level keyword ALWROL must be specified for every record
format written in a WRITE statement containing the ROLLING phrase.
Other DDS keywords mutually exclusive with the ALWROL keyword must not
be used.
Either of the DDS keywords, CLRL or OVERLAY, must be specified for a
record format that is to be written and rolled to prevent the display from being
cleared when that record format is written. See the DDS Reference manual for
more information on DDS keywords.
All the identifiers and literals must represent positive integer values.
The roll starting line number (identifier-5 or literal-4) must not exceed the
ending line number (identifier-6 or literal-5).
The contents of lines that are rolled outside of the window specified by the
starting and ending line numbers disappear.
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ UPDATE CUSTOMER ORDER RECORD │ Line 3
│ │
│ │
│ TO END THIS JOB, PRESS F7 │ Line 8
│ │
│ │
│ ENTER YOUR OPERATOR NUMBER: ___ │ Line 13
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┐
│ │ Line 14 │
│ ENTER CUSTOMER NUMBER: _____ │ Line 15 │
│ │ │
│ PRESS F3 TO DISPLAY OPTION MENU │ Line 17 ├───┐
│ │ │ │
│ │ │ │
│ │ Line 2ð │ │
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┘ │
│ │ │
│ │ ┌─────────┘
└─────────────────────────────────────────────────────────────────────┘ │
│
│ These seven lines
DISPLAY AFTER PROCESSING THE WRITE STATEMENT └5of FMT1 will be
rolled down 2
┌─────────────────────────────────────────────────────────────────────┐ lines.
│ │
│ UPDATE CUSTOMER ORDER RECORD │ Line 3
│ │
│ │
│ TO END THIS JOB, PRESS F7 │ Line 8
│ │
│ │
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┐
│ ITEM NUMBER ORDERED: _____ │ Line 12 │
│ │ ├─┐
│ QUANTITY ORDERED: ______ │ Line 14 │ │
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┘ │
│ │ │
│ ENTER CUSTOMER NUMBER: XXXXX │ Line 17 │
│ │ │
│ PRESS F3 TO DISPLAY OPTION MENU │ Line 19 │
│ │ │
│ │ ┌───────┘
│ │ │
└─────────────────────────────────────────────────────────────────────┘ │
│ These three lines
└5of FMT2 have been
written over the
previous lines.
╔════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───WRITE SUBFILE──record-name-1──┬──────────────────────┬─────────────5 ║
║ └──FROM──identifier-1──┘ ║
║ ║
║ ║
║ 5────FORMAT─┬────┬──┬─identifier-2─┬────────────────────────────────────5 ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬──────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────┬──────────────────────5 ║
║ └──INVALID─┬─────┬──imperative-statement-1──┘ ║
║ └─KEY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬─┬───────────┬────5% ║
║ └──NOT INVALID─┬─────┬──imperative-statement-2──┘ └─END-WRITE─┘ ║
║ └─KEY─┘ ║
║ ║
╚════════════════════════════════════════════════════════════════════════════╝
Format 5 can only be used for display devices. If the subfile form of the WRITE
statement is used for any other type of device, the WRITE operation fails and a file
status of 90 is set.
If the format is a subfile record, and SUBFILE is specified, the RELATIVE KEY
clause must have been specified on the SELECT clause for the file being written.
The record written to the subfile is the record in the subfile identified by the format
name that has a relative record number equal to the value of the RELATIVE KEY
data item. See the Data Management Guide for more information on subfiles.
TERMINAL Phrase
See the explanation following Format 4 for general considerations concerning the
TERMINAL phrase.
The TERMINAL phrase specifies which program device’s subfile is to have a record
written to it. If the TERMINAL phrase is specified, literal-2 or identifier-3 must refer
to a work station associated with the TRANSACTION file. If literal-2 or identifier-3
contains a value of blanks, the TERMINAL phrase is treated as if it were not speci-
fied. The work station specified by the TERMINAL phrase must have been
acquired, either explicitly or implicitly.
For information about what happens when the INVALID KEY condition arises, refer
to the diagrams on pages 76 through 78.
END-WRITE Phrase
The END-WRITE phrase serves to explicitly delimit the scope of the statement.
For a further discussion of the WRITE statement, the FROM phrase, and the
INVALID KEY phrase, see the COBOL/400 Reference. For information on the
FORMAT phrase, see the Procedure Division, “Common Processing Facilities” on
page 181.
USE Statement
The USE statement specifies procedures for input/output error handling that are in
addition to the standard procedures provided by the input/output control system.
Format
╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───USE AFTER──┬──────────┬──┬─EXCEPTION─┬───────────────────────────────────5 ║
║ └─STANDARD─┘ └─ERROR─────┘ ║
║ ║
║ ║
║ ║
║ ┌───────────┐ ║
║ 6 │ ║
║ 5────PROCEDURE──┬────┬────┬────file-name-1─┴──┬──────────────────────────────5% ║
║ └─ON─┘ └────I-O────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
See the “USE Statement” section of the COBOL/400 Reference for a further dis-
cussion of the USE statement.
Conditioning
Location
/B/ H/M/N/P)
And/Or/Comment (A/O/*)
Condition Name
Sequence
Reference (R)
Number
Form Type
Posi t i ons
Indicator
Reserved
Indicator
Indicator
/
Decimal
Not (N)
Not (N)
Not (N)
Line Pos
1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 16 1 7 1 8 1 9 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0
Figure 68. Example of a TRANSACTION Inquiry Program Using a Single Display Device
The data description specifications (DDS) for the display device file (CUSMINQ) to
be used by this program describe two record formats: CUSPMT and CUSFLDS.
The CUSPMT record format contains the constant ‘Customer Master Inquiry’, which
identifies the display. It also contains the prompt ‘Customer Number’ and the input
In addition to describing the constants, fields, and attributes for the display, the
record formats also define the line numbers and horizontal positions where the con-
stants and fields are to be displayed.
Note: The field attributes are defined in a physical file (CUSMSTP) used for field
reference purposes, instead of in the DDS for the display file. For example,
EDTCDE(J) is defined in CUSMSTP for the field ARBAL.
Location
Reference (R)
Sequence
Number
Form Type
Posi t i ons
Indicator
Reserved
Indicator
Indicator
Decimal
Not (N)
Not (N)
Not (N)
Line Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 1 4 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 34 35 36 37 3 8 39 4 0 4 1 42 4 3 44 4 5 46 47 4 8 49 5 0 5 1 5 2 5 3 54 5 5 56 5 7 58 59 6 0 6 1 6 2 6 3 6 4 6 5 66 6 7 68 6 9 7 0 7 1 7 2 7 3 7 4 7 5 76 7 7 78 7 9 8 0
Figure 69. Data Description Specification for the Record Format CUSMST.
The data description specifications (DDS) for the database file that is used by this
program describe one record format: CUSMST. Each field in the record format is
described, and the CUST field is identified as the key field for the record format.
Figure 70 (Part 1 of 2). Source Listing of a TRANSACTION Inquiry Program Using a Single Display Device.
Figure 70 (Part 2 of 2). Source Listing of a TRANSACTION Inquiry Program Using a Single Display Device.
The complete source listing for this program example is shown here. In particular,
note the FILE-CONTROL and FD entries and the data structures generated by the
Format 2 COPY statements.
The READ operation in statement 82 uses the customer number (CUST) field to
retrieve the corresponding CUSMST record from the CUSMSTP file. If no record is
found in the CUSMSTP file, indicator 99 is set on. The GO TO operation in state-
ment 84, which is run when indicator 99 is set on, causes the program to branch
back to the beginning. The message:
Customer number not found
is displayed when the format is written, because it is conditioned by indicator 99 in
the DDS for the file. When you receive this message, the keyboard locks. You
must press the Reset key in response to this message to unlock the keyboard.
You can then enter another customer number.
If the READ operation retrieves a record from the CUSMSTP file, the WRITE oper-
ation writes the CUSFLDS record to the display work station. This record contains
the customer’s name, address, and accounts receivable balance.
You then press Enter, and the program branches back to the beginning. You can
enter another customer number or end the program. To end the program, press
F3, which sets on indicator 15 in the program.
When indicator 15 is on, the program closes all files and processes the EXIT
PROGRAM statement. The program then returns control to the individual who
called the COBOL program.
This is the initial display written by the WRITE operation in statement 77:
à@ ð
Customer Master Inquiry
This display appears if a record is found in the CUSMSTP file for the customer
number entered in response to the first display:
This display appears if the CUSMSTP file does not contain a record for the cus-
tomer number entered in response to the first display:
à@ ð
Customer Master Inquiry
Customer Number
Customer number not found, press reset, then enter valid number
XMPLE773 displays all the detail order records for the requested order number.
The program prompts you to enter the order number that is to be reviewed. The
order number is checked against the order header file, ORDHDRP. If the order
number exists, the customer number accessed from the order header file is
checked against the customer master file, CUSMSTP. All order detail records in
ORDDTLP for the requested order are read and written to the subfile. A write for
the subfile control record format is processed, and the detail order records in the
subfile are displayed for you to review. You end the program by pressing F12.
Location
Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80
Figure 71 (Part 1 of 3). Data Description Specifications for an Order Inquiry Program
Location
U s age (/ b / O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Condition Name
Reference (R)
Sequence
Number
Form Type
Pos i t i on s
Indicator
Indicator
Indicator
Reserved
Decimal
Not (N)
Not (N)
Not (N)
Line Pos
1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 14 1 5 16 1 7 18 1 9 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0
/
A * * OR D I NQD E X I S T I NG OR D E R R E V I EW
A R S UB 1 SFL
A I T EM 5 /0 1 /0 2 T E X T ( ' I T E M NUMB E R ' )
A Q T YOR D 3 /0 1 /0 9 T E X T ( ' QUAN T I T Y OR D E R E D ' )
A D E S CR P 3 /0 1 /0 1 4 T E X T ( ' I T E M D E S CR I P T I ON ' )
A P R I CE 6 2 1 /0 4 6 T E X T ( ' S E L L I NG P R I CE ' )
A E X T ENS 8 2 1 /0 5 6 E D T CD E ( J )
A T E X T ( ' E X T E N S I ON AMOUN T OF +
A Q T YOR D X P R I CE ' )
A R S UBCT L 1 S F L C T L ( S UB 1 )
A 58 S F L CL R
A 57 S F LDSP
A N5 8 S F L D S PC T L
A SFL S I Z ( 57 )
A S F L P AG ( 1 4 )
A 57 S F L E ND
A OV E R L AY
A L OCK
A N4 5
AON 4 7 R OL L U P ( 9 7 ' CON T I NU E D I S P L AY ' )
A CA 1 2 ( 9 8 ' E ND OF P ROGR AM ' )
A S E T OF F ( 5 7 ' D I S P L A Y S U B F I L E ' )
A S E T OF F ( 5 8 ' OF F =D I S P L AY S U B C T L 1 ON= +
A CL E AR S U B F I L E ' )
A 1 2 ' E X I S T I NG OR D E R I NQU I R Y '
A 3 2 ' OR D E R '
A OR D E R N 5 Y /0 B 3 8 T E X T ( ' OR D E R NUMB E R ' )
A 61 E R RMS G ( ' OR D E R NUMB E R NO T F OUND ' 6 1 )
A 47 E R RMS G ( ' NO L I NE S F OR T H I S OR D E R ' 4 7 )
A 62 E R RMS G ( ' NO CU S T OME R R E COR D F OUND F O+
A R T H I S OR D E R ' 6 2 )
A 4 2 ' DA T E '
A OR DDA T 6 /0 4 7 T E X T ( ' DA T E OR D E R WA S E N T E R E D ' )
A 5 2 ' CU S T # '
A CU S T 5 5 9 T E X T ( ' CU S T OME R NUMB E R ' )
A NAME 25 3 1 6 T E X T ( ' CU S T OME R NAME ' )
A ADDR 20 4 1 6 T E X T ( ' CU S T OME R ADDR E S S ' )
A CI TY 20 5 1 6 T E X T ( ' CU S T OME R C I T Y ' )
A S TAT E 2 6 1 6 T E X T ( ' CU S T OME R S T A T E ' )
A ZIP 5 /0 6 3 1 T E X T ( ' Z I P COD E ' )
A 1 4 4 ' T OT AL '
A OR DAMT 8 2 1 5 1 T E X T ( ' T O T A L DOL L AR AMOUN T OF T H E +
A OR D E R ' )
A 2 44 ' S TAT US '
A S T S OR D 12 2 51
A 3 4 4 ' OP E N '
A S T S OP N 12 3 51
A 4 4 4 ' CU S T OME R OR D E R '
A CU S OR D 15 4 5 9 T E X T ( ' CU S T OME R P U R CHA S E OR D E R +
A NUMB E R ' )
A 5 44 ' SH I P V I A '
A S HP V I A 15 5 5 9 T E X T ( ' S H I P P I NG I N S T R UC T I ON S ' )
A 6 4 4 ' P R I N T E D DA T E '
A P R T DA T 6 /0 6 5 7 T E X T ( ' DA T E OR D E R WA S P R I N T E D ' )
A 7 2 9 ' I NVO I CE '
A I NVNUM 5 /0 7 3 8 T E X T ( ' I NVO I CE NUMB E R ' )
A 7 6 4 ' MT H '
A AC T MT H 2 /0 7 6 8 T E X T ( ' ACCOUN T I NG MON T H OF S A L E ' )
A 7 7 2 ' Y E AR '
A AC T Y R 2 /0 7 7 7 T E X T ( ' ACCOUN T I NG Y E AR OF S A L E ' )
A 8 2 ' I T EM '
A 8 8 ' QT Y '
A 8 1 4 ' I T E M D E S CR I P T I ON '
A 8 4 6 ' P R I CE '
A 8 5 5 ' E X T E N S I ON '
Figure 71 (Part 2 of 3). Data Description Specifications for an Order Inquiry Program
Location
Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 19 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0
Figure 71 (Part 3 of 3). Data Description Specifications for an Order Inquiry Program
This is the initial order-entry prompt display written to the work station:
This display appears if there are detail order records for the customer whose order
number was entered in the first display:
This display appears if the ORDHDRP file does not contain a record for the order
number entered on the first display:
á ñ
In this example, payments from customers are registered. The clerk is prompted to
enter one or more customer numbers and the amount of money to be credited to
each customer’s account. The program checks the customer number and uncondi-
tionally accepts any payment for an existing customer who has invoices out-
standing. If an overpayment will result from the amount of the payment from a
customer, the clerk is given the option to accept or reject the payment. If no cus-
tomer record exists for a customer number, an error message is issued. Payments
can be entered until the clerk ends the program by pressing F12.
Location
Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80
Figure 73 (Part 1 of 3). Example of a Data Description Specification for a Payment Update Program
Location
Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80
A* DD S F OR T H E D I S P L AY D E V I CE F I L E P AY /UP D
/ TD
A* ACCOUN T S R E CE I VAB L E I N T E R AC T I V E P AYME N T UP DA T E
A*
A R S UB F I L E 1 SFL
A T E X T ( ' S U B F I L E F OR CU S T OME R P AYME N T ' )
A*
A ACP PMT 4A I 5 4 T E X T ( ' ACCE P T P AYME N T ' )
A VAL U E S ( ' * Y E S ' ' * NO ' )
A 51 D S P A T R ( R I MD T )
A N5 1 D S P A T R ( ND P R )
A*
A CU S T 5 B 5 1 5 T E X T ( ' CU S T OME R NUMB E R ' )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A AMP A I D 8 /0 2 B 5 2 4 T E X T ( ' AMOUN T P A I D ' )
A CH E CK ( F E )
A AU T O( R AB )
A CMP ( G T /0 )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A E CPMSG 3 1A O 5 3 7 T E X T ( ' E XCE P T I ON ME S S AGE ' )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A OVR PMT 8 Y 2O 5 7 /0 T E X T ( ' OVE R P AYME N T ' )
A E D T CD E ( 1 )
A 55 DSPAT R ( B L )
A N5 6 D S P A T R ( ND )
A*
A S T S CD E 1A H T E X T ( ' S T A T U S COD E ' )
Figure 73 (Part 2 of 3). Example of a Data Description Specification for a Payment Update Program
Location
Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne P os
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80
Figure 73 (Part 3 of 3). Example of a Data Description Specification for a Payment Update Program
This is the initial display that is written to the work station to prompt you to enter
the customer number and payment:
Customer Payment
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
á ñ
Enter the customer numbers and payments:
à@ ð
Customer Payment Update Prompt Date ð5/24/94
Customer Payment
345ðð 2ððð
4ð5ðð 3ðððð
36ððð 25ðð
125ðð 2ðð
22799 45ðð
419ðð 75ðð
1ððð1 5ððð
495ðð 25ðð
133ðð 35ðð
569ðð 4ððð
á ñ
Payments that would result in overpayments or that have incorrect customer
numbers are left on the display and appropriate messages are added:
á ñ
Indicate which payments to accept:
á ñ
The accepted payments are processed, and overpayment information is displayed:
á ñ
End of IBM Extension
You can obtain printed output from a COBOL program by issuing WRITE state-
ments to one or more printer files. Each printer file must have a unique name and
be assigned to a device of PRINTER or FORMATFILE in the ASSIGN clause of
that file’s FILE-CONTROL entry.
The file operations that are valid for a printer file are WRITE, OPEN, and CLOSE.
For a complete description of these operations, see the COBOL/400 Reference.
See the DDS Reference for information on the DDS for externally described printer
files. For more information on FORMATFILE files, see “FORMATFILE Files” on
page 234.
LINAGE Clause
When the LINAGE clause is specified for a file assigned to PRINTER, all spacing
and paging controls are handled internally by compiler generated code.
Paper positioning is done only when the first WRITE statement is run. The paper
in the printer is positioned to a new physical page, and the LINAGE-COUNTER is
set to 1. When the printer file is shared and other programs have written records to
the file, the COBOL WRITE statement is still considered to be the first WRITE
statement. Paper positioning is handled by the COBOL/400 compiler even though
it is not the first WRITE statement for that file.
All spacing and paging for WRITE statements is controlled internally. The physical
size of the page is ignored when paper positioning is not properly defined for the
COBOL/400 compiler. For a file that has a LINAGE clause and is assigned to
PRINTER, paging consists of spacing to the end of the logical page (page body)
and then spacing past the bottom and top margins.
The LINAGE clause should not be used for files assigned to FORMATFILE.
FORMATFILE Files
Externally described printer files must be assigned to a device of FORMATFILE.
The term FORMATFILE is used because the FORMAT phrase is valid in WRITE
statements for the file, and the data formatting is specified in the DDS for the file.
When you have specified a device of FORMATFILE, you can obtain formatting of
printed output in two ways:
1. Choose the formats to print and their order by using appropriate values in the
FORMAT phrases specified for WRITE statements. For example, use one
format once per page to produce a heading, and use another format to produce
the detail lines on the page.
2. Choose the appropriate options to be taken when each format is printed by
setting indicator values and passing these indicators through the INDICATOR
phrase for the WRITE statement. For example, fields may be underlined, blank
lines may be produced before or after the format is printed, or the printing of
certain fields may be skipped.
The use of external descriptions for printer files has the following advantages over
program descriptions:
Multiple lines can be printed by one WRITE statement. When multiple lines are
written by one WRITE statement and the END-OF-PAGE condition is reached,
the END-OF-PAGE imperative statement is processed after all of the lines are
printed. It is possible to print lines in the overflow area, and onto the next page
before the END-OF-PAGE imperative statement is processed.
Figure 75 on page 235 shows an example of an occurrence of the
END-OF-PAGE condition through FORMATFILE.
Optional printing of fields based on indicator values is possible.
Editing of field values is easily defined.
Maintenance of print formats, especially those used by multiple programs, is
easier.
Use of the ADVANCING phrase for FORMATFILE files causes a compilation error
to be issued. Advancing of lines is controlled in a FORMATFILE file through DDS
keywords, such as SKIPA and SKIPB, and through the use of line numbers.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 2 2 23 2 4 25 2 6 27 28 29 30 3 1 3 2 33 3 4 35 3 6 37 38 39 40 4 1 4 2 43 4 4 45 4 6 47 48 49 50 5 1 5 2 5 3 5 4 55 5 6 57 5 8 5 9 60 6 1 6 2 6 3 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80
A* P H Y S I CA L F I LE DD S F OR P E R S ON N E L F I LE IN F OR MA T F I L E E X AMP L E
A
A* R P E R S R EC
A E MP L NO 6S
A N AME 30
A AD D R E S S 1 35
A AD D R E S S 2 20
A B I R T HD A T E 6
A MA R S T A T 1
A S P OU S E N AME 30
A N UMC H I L D 2S
A K E MP L NO
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
Figure 76 (Part 1 of 2). DDS Example of the Use of Externally Described Printer Files Assigned to a Device of
FORMATFILE
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A* PR I NT ER F I LE DD S F OR F OR MA T F I L E E X AMP L E
A*
A I ND A R A R E F ( P E R S F I L E )
A R H E AD I NG S K I P B ( 1 ) S P AC E A ( 3 )
A 1 5 ' P E R S ON N E L L I S T I NG '
A U ND E R L I N E
A 3 3 ' - OR D E R E D B Y '
A OR D E R T Y P E 15 46
A 8 0 D A T E E D T CD E ( Y )
A 9 3 T I ME
A 1 1 5 ' P AG E : '
A + 1 P AGN B R E D T CD E ( 3 )
A*
A R DE T A I L S P AC E A ( 3 )
A* L I NE 1
A 1 ' N AME : '
A N AME R 1 1 U ND E R L I N E
A 5 5 ' E MP L O Y E E N UMB E R : '
A E MP L NO R 73
A 8 7 ' DA T E OF B I R T H : '
A B I R T HD A T E R 1 0 3 S P AC E A ( 1 )
A* L I NE 2
A 1 ' AD D R E S S : '
A AD D R E S S 1 R 11
A 5 5 ' MA R I T A L S T A T U S : '
A MA R S T A T R 73
A 01 8 7 ' S P OU S E ' ' S N AME : '
A 01 S P OU S E N AME R 103
A* L I NE 3
A AD D R E S S 2 R 1 1 S P AC E B ( 1 )
A 5 5 ' CH I L D R E N : '
A N UMC H I L D R 7 3 E D T CD E ( 3 )
A
A
A
Figure 76 (Part 2 of 2). DDS Example of the Use of Externally Described Printer Files Assigned to a Device of
FORMATFILE
.1/ INDARA specifies that a separate indicator area is to be used for the file.
.2/ HEADING is the format name that provides headings for each page.
.3/ SKIPB(1) and SPACEA(3) are used to:
1. Skip to line 1 of the next page before format HEADING is printed.
2. Leave 3 blank lines after format HEADING is printed.
.4/ DATE, TIME, and PAGNBR are used to have the current date, time and
page number printed automatically when format HEADING is printed.
.5/ DETAIL is the format name used to print the detail line for each employee in
the personnel file.
All database files are created by OS/400 Create File commands. See the
Database Guide for a description of the Create File commands for database files.
To write standard ANSI X3.23-1985 COBOL programs that access an indexed file,
you must create the file with certain characteristics. The following table lists these
characteristics and what controls them:
Characteristic Control
The file must be a physical file. The CL command CRTPF
The file cannot have records with duplicate The DDS keyword UNIQUE
key values.
The file cannot be a shared file. The CL command CRTPF
A key must be defined for the file. DDS
Keys must be in ascending sequence. DDS
Keys must be contiguous within the record. DDS
Key fields must be alphanumeric. They DDS
cannot be numeric only.
The value of the key used for sequencing DDS
must include all 8 bits of every byte.
A starting position for retrieving records cannot The CL command OVRDBF
be specified.
Select/omit level keywords cannot be used for DDS
the file.
When the DDS specifies only one key field for the file, the RECORD KEY must be
a single field of the same length as the key field defined in the DDS.
If a Format 2 COPY statement is specified for the file, the RECORD KEY clause
must specify one of the following:
The name used in the DDS for the key field if the name is not a COBOL
reserved word.
The name used in the DDS for the key field with -DDS added to the end if the
name is a COBOL reserved word.
The data name defined with the proper length and at the proper location in a
program-described record description for the file.
EXTERNALLY-DESCRIBED-KEY. This keyword specifies that the keys defined
in DDS for each record format are to be used for accessing the file. These
keys can be noncontiguous. They can be defined at different positions within
the record format.
When the DDS specifies multiple contiguous key fields, the RECORD KEY data
name must be a single field with its length equal to the sum of the lengths of the
multiple key fields in the DDS. If a Format 2 COPY statement is specified for the
file, there must also be a program-described record description for the file that
defines the RECORD KEY data name with the proper length and at the proper
position in the record.
Contiguous items are consecutive elementary or group items in the Data Division
that are contained in a single data hierarchy.
Refer to the “START Statement” in the COBOL/400 Reference for information about
the rules for specifying a search argument that refers to a partial key.
Figure 78. Generic START Statements Using an Externally Described File -- DDS
Figure 80 on page 247 and Figure 81 on page 248 show examples of how to use
DDS to describe the access path for indexed files.
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Reference (R)
Sequence
Number
Form Type
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A R F OR MA T A P F I L E ( OR D D T L P )
A T E X T ( ' ACC E S S P A T H F OR I ND E X E D F I LE ' )
A F L DA 14
A OR D E R N 5S 0
A F L DB 101
A K OR D E R N
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
Figure 80. Using Data Description Specifications to Define the Access Path for an Indexed File
Data description specifications must be used to create the access path for a
program-described indexed file.
In the DDS for the record format FORMATA for the logical file ORDDTLL, the field
ORDERN, which is five digits long, is defined as the key field. The definition of
ORDERN as the key field establishes the keyed access for this file. Two other
fields, FLDA and FLDB, describe the remaining positions in this record as character
fields.
Conditioning
Location
U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)
Pos i t i ons
Indi cator
Reserved
Indi cator
Indi cator
Decimal
Not (N)
Not (N)
Not (N)
Li ne Pos
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0
A R F OR MA T P F I L E ( OR D D T L P )
A T E X T ( ' ACC E S S P A T H F OR I ND E X E D F I LE ' )
A F L DA 14
A OR D E R N 5S 0
A I T EM 5
A F L DB 96
A K OR D E R N
A K I T EM
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
Figure 81. Data Description Specifications for Defining the Access Path (a Composite Key) of an Indexed File
In this example, the data description specifications define two key fields for the
record format FORMAT in the logical file ORDDTLL. For the two fields to be used
as a composite key for a program-described indexed file, the key fields must be
contiguous in the record.
The COBOL description of each field must agree with the corresponding description
in the DDS file. A 10-character item beginning in position 15 of the record must be
defined in the RECORD KEY clause of the file-control entry. The COBOL
To write standard ANSI X3.23-1985 COBOL programs that access a relative file,
you must create the file with certain characteristics. The following table lists these
characteristics and what controls them.
Characteristic Control
The file must be a physical file. The CL command CRTPF
The file cannot be a shared file. The CL command CRTPF
No key can be specified for the file. DDS
A starting position for retrieving records cannot The CL command OVRDBF
be specified.
Select/omit level keywords cannot be used for DDS
the file.
Records in the file cannot be reused. The CL command CRTPF
For a COBOL file with an organization of RELATIVE, the Reorganize Physical File
Member (RGZPFM) CL command can:
Remove all deleted records from the file. Because COBOL initializes all rela-
tive file records to deleted records, any record that has not been explicitly
written will be removed from the file. The relative record numbers of all records
after the first deleted record in the file will change.
Change the relative record numbers if the file has a key and the arrival
sequence is changed to match a key sequence (with the KEYFILE parameter).
To write standard ANSI X3.23-1985 COBOL programs that access a sequential file,
you must create the file with certain characteristics. The following table lists these
characteristics and what controls them.
To preserve the sequence of records in a file that you open in I/O (update) mode,
do not change the file so that you can reuse the records in it. That is, do not use a
Change Physical File (CHGPF) CL command bearing the REUSEDLT option.
Note: The COBOL/400 compiler does not check that the device associated with
the external file is of the type specified in the device portion of assignment-
name. The device specified in the assignment-name must match the actual
device to which the file is assigned. See the “ASSIGN Clause” section of
the COBOL/400 Reference for more information.
A file with an arrival sequence access path can be processed in COBOL as a file
with RELATIVE or SEQUENTIAL organization. The file must be a physical file or a
logical file where each member of the logical file is based on only one physical file
member.
When sequential access is specified for a logical file, records in the file are
accessed through the access path created with create file options.
All physical database files that are opened for OUTPUT are cleared. Database
files with RELATIVE organization, and with dynamic or random access mode, are
also initialized with deleted records.
New relative files opened for OUTPUT in sequential access mode are treated differ-
ently. Table 4 summarizes conditions affecting them.
To extend a file boundary beyond the current number of records, but remaining
within the file size, use the INZPFM command to add deleted records before proc-
essing the file. You need to do this if you receive a file status of 0Q, and you still
want to add more records to the file.
Any attempt to extend a relative file beyond its current size results in a boundary
violation.
To recover from a file status of 9Q, use the CHGPF command as described in the
associated run-time message text.
Lengthy delays are normal when there remains an extremely large number of
records (over 1 000 000) to be initialized to deleted records when the CLOSE state-
ment runs.
When the first OPEN statement for the file is not OPEN OUTPUT, relative files
should be cleared and initialized with deleted records before they are used. See
the discussion of the CLRPFM and INZPFM commands in the CL Reference for
more information.
Lengthy delays in OPEN OUTPUT processing are normal for extremely large rela-
tive files (over 1 000 000 records) that you access in dynamic or random mode.
┌─────┬─────┬──────┬────────┬──────┬───────┬───────┬─────────┬────────┬───────┬────────┬────────┐
│ │ │ │ │ │ │ │ │ │ │ │ SELECT │
│ │ │ │ │ │ │ │ │ │ │ │ CLAUSE │
│ ORG │ ACC │ DEV │ OPEN │ READ │ WRITE │ START │ REWRITE │ DELETE │ CLOSE │ FORMAT │ KEY IS │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ S │ S │ ANY │ INPUT │ X │ │ │ │ │ X │ │ │
│ S │ S │ ANY │ OUTPUT │ │ X(F1) │ │ │ │ X │ A1 │ │
│ S │ S │ ANY │ I-O │ X │ │ │ X │ │ X │ │ │
│ S │ S │ ANY │ EXTEND │ │ X │ │ │ │ X │ │ │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ I │ S │ D/DB │ INPUT │ X │ │ X │ │ │ X │ B1 │ C1 │
│ I │ S │ D/DB │ OUTPUT │ │ X(F1) │ │ │ │ X │ B1 │ C1 │
│ I │ S │ D/DB │ I-O │ X │ │ X │ X │ X │ X │ B1 │ C1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ I │ R │ D/DB │ INPUT │ X │ │ │ │ │ X │ B1 │ D1 │
│ I │ R │ D/DB │ OUTPUT │ │ X(F1) │ │ │ │ X │ B1 │ D1 │
│ I │ R │ D/DB │ I-O │ X │ X │ │ X │ X │ X │ B1 │ D1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ I │ D │ D/DB │ INPUT │ X │ │ X │ │ │ X │ B1 │ D1 │
│ I │ D │ D/DB │ OUTPUT │ │ X(F1) │ │ │ │ X │ B1 │ D1 │
│ I │ D │ D/DB │ I-O │ X │ X │ X │ X │ X │ X │ B1 │ D1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ R │ S │ D/DB │ INPUT │ X │ │ X │ │ │ X │ │ C1 │
│ R │ S │ D/DB │ OUTPUT │ │ X(G1) │ │ │ │ X │ │ C1 │
│ R │ S │ D/DB │ I-O │ X │ │ X │ X │ X │ X │ │ C1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ R │ R │ D/DB │ INPUT │ X │ │ │ │ │ X │ │ E1 │
│ R │ R │ D/DB │ OUTPUT │ │ X(G1) │ │ │ │ X │ │ E1 │
│ R │ R │ D/DB │ I-O │ X │ X │ │ X │ X │ X │ │ E1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ R │ D │ D/DB │ INPUT │ X │ │ X │ │ │ X │ │ E1 │
│ R │ D │ D/DB │ OUTPUT │ │ X(G1) │ │ │ │ X │ │ E1 │
│ R │ D │ D/DB │ I-O │ X │ X │ X │ X │ X │ X │ │ E1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ T │ S │ W │ I-O │ X │ X │ │ │ │ X │ H1 │ │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ T │ D │ W │ I-O │ X(K1)│ X(K1) │ │ X │ │ X │ I1 │ J1 │
├─────┴─────┴──────┴────────┼──────┴───────┴───────┴─────────┼────────┴───────┴────────┴────────┤
│ORG: │ ACC: │ DEV: │
│ │ │ │
│ S = Sequential │ S = Sequential │ ANY = Any Device │
│ R = Relative │ R = Random │ D = DISK │
│ I = Indexed │ D = Dynamic │ DB = DATABASE │
│ T = TRANSACTION │ │ W = WORKSTATION │
└───────────────────────────┴────────────────────────────────┴──────────────────────────────────┘
For example, READ FIRST retrieves the record with the highest key value, and
READ LAST retrieves the record with the lowest key value. Files with a
descending key sequence also cause the START qualifiers to work in the opposite
manner. For example, START GREATER THAN positions the current record
pointer to a record with a key less than the current key.
In the following example program, the CALL to QCMDEXC (at sequence number
001600) results in the processing of the Add Library List Entry (ADDLIBLE) CL
command (at sequence number 001100). The successful completion of the CL
command results in the addition of the library, COBOLTEST, to the library list.
-A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..
ððð1ðð IDENTIFICATION DIVISION.
ððð2ðð PROGRAM-ID. CMDXMPLE.
ððð3ðð ENVIRONMENT DIVISION.
ððð4ðð CONFIGURATION SECTION.
ððð5ðð SOURCE-COMPUTER. IBM-AS4ðð.
ððð6ðð OBJECT-COMPUTER. IBM-AS4ðð.
ððð7ðð DATA DIVISION.
ððð8ðð WORKING-STORAGE SECTION.
ððð9ðð ð1 PROGRAM-VARIABLES.
ðð1ððð ð5 CL-CMD PIC X(33)
ðð11ðð VALUE "ADDLIBLE COBOLTEST".
ðð12ðð ð5 PACK-VAL PIC 9(1ð)V9(5) COMP-3
ðð13ðð VALUE 18.
ðð14ðð PROCEDURE DIVISION.
ðð15ðð MAINLINE.
ðð16ðð CALL "QCMDEXC" USING CL-CMD PACK-VAL.
ðð17ðð STOP RUN.
Note: Do not use the Reclaim Resource (RCLRSC) Command in this situation. It
cancels all programs higher in the program stack so that the STOP RUN
statement in the program will cause a run-time exception.
Figure 83 on page 257 was produced with the PRTCORR option in effect.
LIKE Clause
The LIKE clause allows you to define the PICTURE, USAGE, SIGN, and BLANK
WHEN ZERO characteristics of a data name by copying them from a previously
defined data name. LIKE can only refer to a data name or index name, and such
names must be uniquely qualified if they have been previously defined. It also
allows you to change the length of the data name you define.
This clause is particularly helpful because you can use it to define identifiers in the
Working-Storage Section of your program that have the same attributes as vari-
ables that you define using the COPY statement.
To create data name DEPTH with the same attributes as data name HEIGHT, write:
DEPTH LIKE HEIGHT
To create data name PROVINCE with the same attributes as data name STATE, except
1 byte longer, write:
PROVINCE LIKE STATE (+1)
This example shows how you can create data item WS-KEY3 with the same attri-
butes as data item KEY3 in the Working-Storage Section:
The LIKE clause cannot be used in conjunction with the REDEFINES, SIGN,
USAGE, or PICTURE clauses. If you use any of these clauses with the LIKE
clause, a duplication error occurs. Similarly, BLANK WHEN ZERO can only be
specified in conjunction with the LIKE clause if the BLANK WHEN ZERO attribute
has not been inherited by the LIKE clause.
ð1 RATES.
ð5 MONTHLY-RATE PIC 9(3).
66 GROSS-RATE RENAMES MONTHLY-RATE.
ð1 NET-RATE LIKE GROSS-RATE.
\ PICTURE IS 9(3)
ð1 FASTENINGS.
ð5 NAILS PIC 9V99 BLANK WHEN ZERO.
ð5 RIVETS LIKE NAILS.
\ PICTURE IS 9V9(2)
\ BLANK WHEN ZERO
ð1 MORTGAGE-PAYMENT.
ð5 MORTGAGE-TOTAL PIC S999V99 SIGN IS LEADING SEPARATE.
ð5 MORTGAGE-INTEREST LIKE MORTGAGE-TOTAL.
\ PICTURE IS S9(3)V9(2)
\ SIGN IS LEADING SEPARATE
ð1 PROFIT.
ð5 GROSS-PROFIT PIC 999(3)PP(5).
ð5 NET-PROFIT LIKE GROSS-PROFIT.
\ PICTURE IS 9(5)P(6)
You can use an integer to increase or decrease the length of the field. The fol-
lowing example shows how to increase the field length of WEEKLY-AMOUNT:
Only the integer portion of the field length can be increased or decreased. You
cannot change the number of decimal places in a data item.
The default attributes, SIGN IS TRAILING and USAGE IS DISPLAY, are never
printed as comments following a LIKE operation.
When you use the LIKE clause, the normal data name qualification rules apply to
the parent data name; however, the referenced data name must be uniquely quali-
fied if it has previously been defined more than once. For example:
The use of the LIKE clause can sometimes result in group items that are not valid.
For example, if you define a COMP-4 group item and then use the LIKE clause to
define a COMP-3 item that is subordinate to it, an error will result.
You can use the LIKE clause with the USAGE IS POINTER clause:
ð1 CUSTOMER-RECORD.
ð5 CUST-NAME PIC X(16).
ð5 CUST-ADDR-POINTER POINTER.
ð5 CUST-STATS-POINTER LIKE CUST-ADDR-POINTER.
\ USAGE IS POINTER
ð5 CUST-NUMBER PIC S9(8).
Note: You cannot use the LIKE clause to change the length of a pointer.
For additional information about the LIKE clause, see the COBOL/400 Reference.
You can write both the starting position and the length value as integer literals, data
items, or arithmetic expressions.
The starting position must be at least 1, and cannot be greater than the length of
the referenced data item. The length must be at least 1.
The result of adding the starting position to the length specification, then subtracting
1, must fall between 1 and the total length of the referenced data item, inclusive.
When the length value is greater than the total length of the data item, an error
results.
Suppose you want to retrieve the current time from the system, and display its
value in an expanded format. You can retrieve it with the ACCEPT statement,
which returns the hours, minutes, seconds, and hundredths of seconds in the
format:
HHMMSSss
However, you may want to view the current time in the format:
HH:MM:SS
Without reference modification, you must define the following data items:
ð1 TIME-GROUP.
ð5 INTERESTING-FIELDS.
1ð HOURS PIC XX.
1ð MINUTES PIC XX.
1ð SECONDS PIC XX.
ð5 UNINTERESTING-FIELDS.
1ð HUNDREDTHS-OF-SECONDS PIC XX.
ð1 EXPANDED-TIME-GROUP.
ð5 INTERESTING-FIELDS.
1ð HOURS PIC XX.
1ð FILLER PIC X VALUE ":".
1ð MINUTES PIC XX.
1ð FILLER PIC X VALUE ":".
1ð SECONDS PIC XX.
The following code would retrieve the time value, convert it to its expanded format,
and display the new value:
With reference modification, you do not need to provide names for the subfields
that describe the time elements. The only data definition you must have is:
ð1 REFMOD-TIME-ITEM PIC X(8).
The code to retrieve and expand the time value appears as follows:
ACCEPT REFMOD-TIME-ITEM FROM TIME
DISPLAY "CURRENT TIME IS: "
REFMOD-TIME-ITEM (1:2)
":"
REFMOD-TIME-ITEM (3:2)
":"
REFMOD-TIME-ITEM (5:2)
Suppose you want to change the value in the item NAME-PORTION without
changing the portion of the item that is defined beyond the currently defined length.
You might try coding:
MOVE NEW-NAME-GROUP TO NAME-GROUP
in which the contents of NEW-NAME-GROUP are:
┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
│ð│5│S│M│I│T│H│ │ │ │ │ │M│I│C│H│A│E│L│
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
According to the rules for the MOVE statement, the entire contents of the receiving
field NAME-GROUP would be replaced. This problem can be avoided by using
reference modification in the MOVE statement:
MOVE NEW-NAME-GROUP TO NAME-GROUP ( 1 :LENGTH OF NAME-GROUP )
By specifying the reference modification with the LENGTH OF special register, the
length of NAME-GROUP is now determined by the value in the NAME-LENGTH
variable.
Suppose a field contains some right-justified characters, and you want to move
them to another field, but left-justified instead of right. Using reference modification
and an INSPECT statement, you can do it.
The program then counts the number of leading spaces, and, using arithmetic
expressions in a reference modification expression, moves the right-justified charac-
ters into another (left-justified) field:
MOVE SPACES TO LEFTY
MOVE ZERO TO I
INSPECT RIGHTY
TALLYING I FOR LEADING SPACE
IF I IS LESS THAN 3ð THEN
MOVE RIGHTY ( I + 1 : 3ð - I ) TO LEFTY
END-IF
You can change both the third and fourth bytes of the first element of
TABLE-ELEMENT to the value “??” with the following MOVE statement:
MOVE "??" TO TABLE-ELEMENT ( 1 ) ( 3 : 2 )
This statement will move the value “??” into table element number 1, beginning at
character position 3, for a length of 2.
De-editing
De-editing allows you to move a numeric-edited data item into a numeric or
numeric-edited receiving data item. The compiler accomplishes this by first estab-
lishing the unedited value of the numeric-edited item. It then moves the unedited
value to the receiver.
Suppose that you use a character field to contain a numeric value that displays on
the terminal, and also to contain a value that the computer operator supplies.
Suppose that this field has the following definition:
One character position for a sign (to contain a space if the numeric field is posi-
tive or zero, or a minus sign if the numeric field is negative);
Six digit positions, in which leading zeros are represented by spaces;
The data item that you use to define this field would look like this:
ð1 NUM-EDIT PIC −Z(6).9(2) USAGE IS DISPLAY.
Later, the computer operator might use this field for data entry. If the operator puts
␣␣␣␣123.45 into the field, you can obtain the numeric value of the field by moving it
into a data item defined as:
ð1 NUMERIC-ITEM PIC S9(6)V9(2) USAGE IS PACKED-DECIMAL.
This statement:
MOVE NUM-EDIT TO NUMERIC-ITEM
causes de-editing to take place, whereby the numeric item receives the numeric
value of the numeric-edited field NUM-EDIT. As a result, the numeric item contains
the value +123.45.
De-editing Examples
Table 5 and Table 6 show examples of COBOL/400 de-editing.
The compiler does not perform this checking for source values of zero, and it
ignores simple insertion characters (such as / B 0 , .).
Sign Test
The compiler validates signs in numeric-edited source items according to the fol-
lowing rules.
If these rules are disobeyed, a sign error occurs, and the program stops.
Float Test
If the source has a string of floating characters, this test verifies the correctness of
leading floating characters in the data field.
If these rules are disobeyed, a float error occurs, and the program stops.
Performance Considerations
You can also improve performance by specifying odd numbers of numeric character
positions in the picture clauses for COMP-3 (packed decimal) items. Internally, the
rightmost byte of a packed decimal item contains a digit and a sign, and any other
bytes contain two digits. If you use the more efficient configuration, the compiler
does not need to supply the missing digit.
Segmentation
Use of segmentation increases the compile and run times of the COBOL program.
The segmentation feature is provided only for compatibility with other systems. You
do not have to be concerned with storage management when using COBOL/400
programs.
Notes:
1. The ð1 mgtstruc must be on a 16 byte boundary. If a boundary error occurs,
add 77 aa PIC X. in front of the ð1.
2. Because the call to QLRMAIN changes the main COBOL program to a subpro-
gram, you should use the EXIT PROGRAM command and not STOP RUN,
which may cause errors.
3. RCLRSC will deactivate the main program (now a subprogram)
Debugging
COBOL source language debugging is provided to help the COBOL programmer
debug a program that is not functioning as expected. Use of this facility increases
the compile and run times of a COBOL program.
*NORANGE Option
This GENOPT parameter option of the CRTCBLPGM command removes the run-
time checks for subscript and reference modification ranges.
The *NORANGE option does not generate code to check subscript or reference
modification ranges.
These options do not eliminate the zero subscript checking performed by the oper-
ating system. If zero subscripts occur, the operating system will not permit their
use and issues message MCH0603.
Relative Files
You can experience lengthy delays if you open or close relative files in which very
large volumes of records are being initialized to deleted records.
Indicators
If you use indicators in a separate indicator area (INDARA keyword specified in
DDS) instead of in the record area, the use of the OCCURS clause to specify a
table with up to 99 indicators can improve performance. See Figure 60 on
page 155 for more information.
Commitment Control
Generally, the use of commitment control increases the run time of a COBOL
program. In addition, the record locking that results from the use of commitment
control by a job may cause delays for other users attempting to access the same
file.
Initializing Variables
You can reduce program run time by choosing not to initialize program variables
that have no value clauses associated with them. You can specify no initialization
by specifying \NOSTDINZ for the GENOPT parameter of the CRTCBLPGM
command, or by specifying NOSTDINZ in the PROCESS statement. The compiler
then initializes only those variables that have value clauses declared. An additional
benefit to this option is that you can also compile larger programs with a greater
number of variables.
If you specify \NOSTDINZ, you must ensure that all data items contain valid data
before you attempt to manipulate the items. If an item does not contain valid data,
decimal data errors can occur.
Blocking Records
You can use record blocking to improve your run-time performance. The key bene-
fits for blocking are realized when you read multiple records sequentially, such as a
random read followed by sequential reads.
A possible variation of this case occurs when a conditional statement exists, but the
condition cannot be met or the statement does not branch (through a GO TO state-
ment) to a paragraph outside the range of the loop.
A COBOL run unit is a set of one or more programs that function as a unit at run
time to provide a problem solution. A COBOL run unit starts with the first COBOL
program in the program stack, and includes all programs (of any type) that are
below it. A program stack is a list of programs linked together as a result of pro-
grams calling other programs, or implicitly from some other event within the same
job.
When a run unit consists of several, separately compiled programs that call each
other, the programs must be able to communicate with each other. They need to
transfer control and usually need to have access to common data. This chapter
describes the methods that accomplish this interprogram communication between
separately compiled programs.
The called COBOL program starts running at the top of the Procedure Division.
When the called program processing is completed, the program can either transfer
control back to the calling program or end the run unit.
A called program must not directly or indirectly execute its caller (such as program
X calling program Y; program Y calling program Z; and program Z then calling
program X). This is called a recursive call. COBOL/400 allows recursion in both
main programs and subprograms. However, if you want your programs to conform
to SAA standards, do not use recursive calls.
You can issue a STOP RUN, EXIT PROGRAM, or GOBACK statement to return
control from a called program.
If execution ends in the main program, either STOP RUN or GOBACK is used.
These statements end the run unit, and control is returned to the caller of the main
program.
A subprogram is left in its last-used state when it terminates with EXIT PROGRAM
or GOBACK. The next time it is called in the run unit, its internal values will be as
they were left, except that return values for PERFORM statements will be reset to
their initial values. In contrast, a main program is initialized each time it is called.
The following examples illustrate the use of the EXIT PROGRAM and STOP RUN
statements in different parts of a run unit.
The example in Figure 85 on page 275 shows a single run unit.
The example in Figure 86 on page 276 shows multiple run units that run con-
secutively
The example in Figure 87 on page 277 shows a run unit with a shared
program that is both a subprogram and a main program.
The example in Figure 88 on page 278 shows multiple run units that run con-
currently.
Note: You can substitute a GOBACK statement for an EXIT PROGRAM statement
that appears in a subprogram, or a STOP RUN statement that appears in a
main program.
┌─────────────────┐
│ PGMA │
│ │ n
│ │
│ Non-COBOL │
└────────┬────────┘
│
┌─────────────┴──────────────┐
RUN UNIT B │ │
┌── ── ── ── ── ── ──│── ── ── ── ─┐ │
│ ┌────────┴────────┐ │ ┌────────┴────────┐
│ PGMB │ │ PGMC │
│ │ │ │ │ │ n + 1
│ Main │ │ │
│ │ Program COBOL │ │ │ Non-COBOL│
└────────┬────────┘ └────────┬────────┘
│ │ └─ ── ── ── ─┐ │
│ │ │
│ ┌───────────┴─────────┐ ┌─────────┴────────────┐
│ RUN│ UNIT E │ │ RUN│ UNIT F
│ │ ┌─ ── ┼─ ── ── ┼─ ── ┐ ┌─ ── ── ──│── ── ── ┐
┌──────┴───────┐ │ ┌───┴────────┴───┐ │ │ ┌────────┴───────┐ │
│ │ PGMD │ │ PGME │ │ │ PGMF │
│ │ │ │ │ │ │ │ │ │ n + 2
│ │ │ │ │ │ │Main │
│ Non-COBOL │ │ │ COBOL │ │ │ │Program COBOL │ │
│ └──────────────┘ └────────────────┘ │ └────────────────┘
└─ ── ── ── ── ── ── ┘ │ └─ ── ── ── ── ── ── ┘
└── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ──┘
Figure 87. Example of a Run Unit with a Shared Program that is Both a Subprogram and a
Main Program
Concurrent run units are achieved by using the QLRCHGCM API. Refer to the
System Programmer’s Interface Reference for more information on this API.
Initialization of Storage
The first time a COBOL program in a run unit is called, its storage is initialized.
Storage is initialized again under the following conditions:
The run unit is terminated, then reinitiated.
The program is canceled (using the CANCEL statement for COBOL, the FREE
operation for the RPG/400* programming language, or the Reclaim Resource
(RCLRSC) command), and then called again.
BY CONTENT means that the calling program is passing only the contents of the
literal, or identifier. With a CALL . . . BY CONTENT, the called program cannot
change the value of the literal or identifier in the calling program, even if it modifies
the variable in which it received the literal or identifier.
Data items in a calling program can be described in the Linkage Section of all the
programs it calls directly or indirectly. In this case, storage for these items is allo-
cated in the highest calling program. That is, program A calls program B, which
calls program C. Data items in program A can be described in the Linkage
Sections of programs B and C, so that one set of data can be made available to all
three programs.
The number of data-names in the identifier list of a called program must not be
greater than the number of data-names in the identifier list of the calling program.
There is a one-to-one positional correspondence; that is, the first identifier of the
calling program is passed to the first identifier of the called program, and so forth.
The compiler makes no attempt to match arguments and parameters.
To make the possibility of mismatched records even smaller, put the level-01 record
in a copy member, and copy it in both programs. (That is, copy it in the Working-
Storage Section of the calling program and in the Linkage Section of the called
program.)
If you carry out a call by an identifier to a program that you subsequently delete
or rename, you must use the CANCEL statement to null the system pointer
associated with the identifier. This ensures that when you next use the identi-
fier to call your program, the associated system pointer will be set again.
The following example shows how to apply the CANCEL statement to an identifier:
MOVE "ABCD" TO IDENT-1.
CALL IDENT-1.
CANCEL IDENT-1.
If you apply the CANCEL statement directly to the literal "ABCD", you do not null
the system pointer associated with IDENT-1. Instead, you can continue to call
program ABCD simply by using IDENT-1 in your CALL statement.
The value of the system pointer also changes if you change the value of the identi-
fier and perform a call using this new value.
On the AS/400 system, pointers are 16 bytes long. COBOL pointers are AS/400
space pointers since they point to system space objects. One part of the pointer
describes its attributes, such as which AS/400 space object it is pointing to.
Another part of the pointer contains the offset into the AS/400 system space object.
If pointers are used in a relational condition, the only valid operators are equal to,
or not equal to.
Because pointer data items are not simply binary numbers on the AS/400 system,
manipulating pointers as integers does not work.
If a group item is described with the USAGE IS POINTER clause, the elementary
items within the group item are pointer items. The group itself is not a pointer data
item, and cannot be used in the syntax where a pointer data item is allowed. The
USAGE clause of an elementary item cannot contradict the USAGE clause of a
group to which the item belongs.
Pointer data items can be part of a group that is referred to in a MOVE statement
or an input/output statement; however, if a pointer data item is part of a group,
there is no conversion of pointer values to another form of internal representation
when the statement is executed.
In the File and Working-Storage sections, the compiler ensures that this exception
does not occur by adding implicit FILLER items. Every time an implicit FILLER
item is added by the compiler, a warning is issued. In the Linkage Section, no
implicit FILLER items are added by the compiler; however, warnings are issued
indicating how many bytes of FILLER would have been added had the group item
appeared in the File or Working-Storage sections.
You can define a data item as a pointer by specifying the USAGE IS POINTER
clause as shown in the following example:
WORKING-STORAGE SECTION.
77 APTR USAGE POINTER.
ð1 AB.
ð5 BPTR USAGE POINTER.
ð5 BVAR PIC S9(3) PACKED-DECIMAL.
LINKAGE SECTION.
ð1 AVAR.
ð5 CVAR PIC X(3ð).
PROCEDURE DIVISION.
SET APTR TO ADDRESS OF AVAR.
In the above example, AVAR is an 01-level data item, so the ADDRESS OF AVAR
is the ADDRESS OF special register. Because a special register is an actual
storage area, the SET statement moves the contents of ADDRESS OF AVAR into
pointer data item APTR.
Within a group structure, pointer data items must also occur on a 16-byte boundary.
To ensure this, the COBOL/400 compiler adds FILLER items immediately before
the pointer data item. To avoid these FILLER items, you should place pointer data
items at the beginning of a group item.
If the pointer data item is part of a table, the first item in the table is placed on a
16-byte boundary. To ensure that all subsequent occurrences of the pointer fall on
a 16-byte boundary, a FILLER item is added to the end of the table if necessary.
WORKING-STORAGE SECTION.
77 APTR USAGE POINTER.
ð1 AB.
ð5 ALPHA-NUM PIC X(1ð).
ð5 BPTR USAGE POINTER.
ð1 EF.
ð5 ARRAY-1 OCCURS 3 TIMES.
1ð ALPHA-NUM-TWO PIC X(14).
1ð CPTR USAGE POINTER.
1ð ALPHA-NUM-THREE PIC X(5).
Figure 91. Aligning Pointer Data Items
In the above example, APTR is a pointer data item. The 77-level item, therefore, is
placed on a 16-byte boundary. The group item AB is an 01-level item and is auto-
matically placed on a 16-byte boundary. Within the group item AB, BPTR is not on
a 16-byte boundary. To align it properly, the compiler inserts a 6-byte FILLER item
after ALPHA-NUM. Finally, CPTR requires a FILLER of 2 bytes to align its first
occurrence. Because ALPHA-NUM-THREE is only 5 bytes long, another 11-byte
FILLER must be added to the end of ARRAY-1 to align all subsequent occurrences
of CPTR.
When a pointer is defined in the File Section, and a file does not have blocking in
effect, each 01-level item will be on a 16-byte boundary. If a file has blocking in
effect, only the first record of a block is guaranteed to be on a 16-byte boundary.
Thus pointer data items should not be defined for files with blocking in effect. For
more information on blocking, refer to “Unblocking Input Records and Blocking
Output Records” on page 102.
When a pointer is the subject of a REDEFINES clause, the object data item must
be on a 16-byte boundary.
WORKING-STORAGE SECTION.
ð1 AB.
ð5 ALPHA-NUM PIC X(16).
ð5 APTR REDEFINES ALPHA-NUM USAGE POINTER.
ð5 BPTR USAGE POINTER.
ð5 CPTR REDEFINES BPTR USAGE POINTER.
Figure 92. REDEFINES and Aligned Pointer Data Items
In the above example, both APTR and CPTR are pointer data items that redefine
16-byte aligned items. In the following example, the redefined item would result in
a severe compiler error:
WORKING-STORAGE SECTION.
ð1 EF.
ð5 ALPHA-NUM PIC X(5).
ð5 HI.
1ð ALPHA-NUM-TWO PIC X(11).
1ð APTR USAGE POINTER.
ð5 BPTR REDEFINES HI USAGE POINTER.
Figure 93. REDEFINES and Aligned Pointer Data Items - Incorrect Method
In the above example, APTR is aligned on a 16-byte boundary. That is, the
COBOL/400 compiler did not need to add FILLER items to align APTR. The group
item HI is not on a 16-byte boundary, and so neither is pointer data item BPTR.
Because the COBOL/400 compiler cannot add FILLER items to place BPTR on a
16-byte boundary, a severe error will result. In the following example, similar to the
above, the COBOL/400 compiler is able to place the pointer data item on a 16-byte
boundary:
WORKING-STORAGE SECTION.
ð1 EF.
ð5 ALPHA-NUM PIC X(5).
ð5 HI.
1ð ALPHA-NUM-TWO PIC X(11).
1ð APTR USAGE POINTER.
1ð ALPHA-NUM-THREE PIC X(5).
ð5 KL REDEFINES HI.
1ð BPTR USAGE POINTER.
Figure 94. REDEFINES and Unaligned Pointer Data Items - Correct Method
In the above example, group item KL is not on a 16-byte boundary; however, the
compiler adds an 11-byte FILLER before pointer data item BPTR to ensure that it
falls on a 16-byte boundary.
WORKING-STORAGE SECTION.
77 APTR USAGE POINTER VALUE NULL.
PROCEDURE DIVISION.
IF APTR = NULL THEN
DISPLAY 'APTR IS NULL'
END-IF.
Figure 95. Using NULL to Initialize a Pointer
In the above example, pointer APTR is set to NULL in the Working-Storage section.
The comparison in the procedure division will be true and the display statement is
executed.
On the AS/400 system, the initial value of a pointer data item with or without a
VALUE clause of NULL, equals NULL.
You can use LENGTH OF in the Procedure Division anywhere a numeric data item
having the same definition as the implied definition of the LENGTH OF special reg-
ister is used; however, LENGTH OF cannot be used as a subscript or a receiving
data item. LENGTH OF has the implicit definition:
USAGE IS BINARY, PICTURE 9(9)
The following example shows how you can use LENGTH OF with pointers:
WORKING-STORAGE SECTION.
77 APTR USAGE POINTER.
ð1 AB.
ð5 BPTR USAGE POINTER.
ð5 BVAR PIC S9(3) PACKED-DECIMAL.
ð5 CVAR PIC S9(3) PACKED-DECIMAL.
PROCEDURE DIVISION.
MOVE LENGTH OF AB TO BVAR.
MOVE LENGTH OF BPTR TO CVAR.
Figure 96. Using LENGTH OF with Pointers
In the above example, the length of group item AB is moved to variable BVAR.
BVAR has a value of 20 because BPTR is 16 bytes long, and both variables BVAR
and CVAR are 2 bytes long. CVAR receives a value of 16.
You can also use the LENGTH OF special register to set up data structures within
user spaces, or to increment addresses received from another program. To see an
When using the ADDRESS OF special register, you no longer need to ensure a
one-to-one mapping between the USING phrases of the two programs. For those
data items in the Linkage Section that are not specified in the USING phrase of the
Procedure Division header, you can use a SET statement to specify the starting
address of the data structure. Once the SET statement is run, the data item is then
treated as if it was passed from another program. For an example of a SET state-
ment used in this manner, refer to Figure 100 on page 292. .16/ on page 295
illustrates how the SET statement is used to set the starting address of the data
structures ls-header-record and ls-user-space at the beginning of the user space.
You cannot use the calculated ADDRESS OF where an item can be changed.
Only the ADDRESS OF special register can be changed. For example, in
Figure 100, the SET statement at .18/ on page 295 uses the ADDRESS OF
special register because it is an 01-level item. At .19/ on page 295 ADDRESS OF
is used because, although it is an 01-level item, it is reference-modified.
A pointer MOVE is done when all of the following conditions are met:
1. The source or receiver of a MOVE statement contains a pointer
2. Both of the items are at least 16 bytes long
Of the conditions listed above, determining if two data items are properly aligned
can be the most difficult.
If the items being moved are 01-level items, or are part of an 01-level item, they
must be on the same offset relative to a 16-byte boundary for a pointer MOVE to
occur. (A warning is issued if this is not true.) The following example shows three
data structures, and the results when a MOVE statement is issued:
WORKING-STORAGE SECTION.
ð1 A.
ð5 B PIC X(1ð).
ð5 C.
1ð D PIC X(6).
1ð E POINTER.
ð1 A2.
ð5 B2 PIC X(6).
ð5 C2.
1ð D2 PIC X(1ð).
1ð E2 POINTER.
ð1 A3.
ð5 B3 PIC X(22).
ð5 C3.
1ð D3 PIC X(1ð).
1ð E3 POINTER.
PROCEDURE DIVISION.
MOVE A to A2. .1/
MOVE A to A3. .1/
MOVE C to C2. .2/
MOVE C2 to C3. .3/
.1/ This results in a pointer move because the offset of each group item to
be moved is zero. Pointer integrity is maintained.
.2/ This results in a non-pointer move, because the offsets do not match.
The offset of group item C is 10, and the offset of group item C2 is 6.
Pointer integrity is not maintained.
.3/ This results in a pointer move, because the offset of group item C2 is 6,
and the offset of C3 relative to a 16-byte boundary is also 6. (When the
offset is greater than 16, the offset relative to a 16-byte boundary is cal-
culated by dividing the offset by 16. The remainder is the relative offset.
In this case, the offset was 22, which, when divided by 16, leaves a
remainder, or relative offset, of 6.) Pointer integrity is maintained.
If a group item contains a pointer, and the compiler cannot determine
the offset relative to a 16-byte boundary, the compiler issues a warning
message, and the pointer move is attempted. However, pointer integrity
may not be maintained. The compiler cannot determine the offset if the
item is defined in the Linkage Section, or if the item is reference-
modified with an unknown starting position. You must ensure that
pointer alignment is maintained, or MCH0602 may result.
If one of the items in a MOVE statement is an 01-level item with a pointer, and the
other a 77-level Working-Storage item, the 77-level Working-Storage item is forced
to a 16-byte boundary.
The compiler is not able to determine the offset of an item relative to a 16-byte
boundary when the BY CONTENT item is:
Reference modified with an unknown starting position, or
Defined in the Linkage Section.
WORKING-STORAGE SECTION.
ð1 A. .1/
ð5 B PIC X(3).
ð5 C..2/
1ð FILLER PIC X(13).
1ð D POINTER.
PROCEDURE DIVISION.
ð1 E.
ð5 F PIC X(16).
ð5 G POINTER.
77 K PIC S9(3) VALUE 8.
LINKAGE SECTION.
ð1 A. .3/
ð5 B PIC X(3).
ð5 C.
1ð FILLER PIC X(13).
1ð D POINTER.
ð1 C2..4/
ð5 FILLER PIC X(13).
ð5 D2 POINTER.
In the previous example, Program A passes two group items to Program B. .1/ is
an 01-level group item, with an offset of zero. .2/ is an 05-level group item, and
has an offset of 3. Because the items are passed by reference, pointer integrity is
maintained for both group items A and C.
Program B passes five items to another program, C. The items are passed by
content to Program C. Because they are passed by content, Program C receives a
copy of the items, and pointer integrity is not maintained in all cases.
.3/ Because this item is defined in the Linkage Section, it has an unknown
offset. The compiler assumes it is 16-byte aligned, and in this case, when A is
passed, pointer integrity of D is maintained, but a compiler warning message is
issued on the CALL.
.4/ This item contains a pointer, and a pointer move is accomplished by .5/.
However, because the item is defined in the Linkage Section and the offset is
unknown, pointer integrity is not maintained. The compiler attempts to move
C2 to a 16-byte aligned area, and a compiler warning message is issued.
.6/ Because E contains a pointer, a pointer move is accomplished. The offset
can be calculated because the reference modification start position is a numeric
literal. In this case, pointer integrity is maintained, and the item is placed at an
offset of 4 from the 16-byte boundary.
.7/ Because E contains a pointer, a pointer move is attempted. Because E is
reference-modified with an unknown starting position (K), the compiler cannot
calculate the offset, and assumes it is aligned on a 16-byte boundary. A com-
piler warning message is issued. If the value of K causes E to be aligned on a
16-byte boundary, pointer integrity is maintained. For this to occur, K must be
1 or 17.
.8/ F is an item defined in the Working-Storage Section, and contains no
pointers, so no pointer moves are expected.
POINTA is a program that reads customer names and addresses into a user space,
and then displays the information in a list. The program assumes that the customer
information exists in a file called POINTACU.
The customer address field is a variable-length field, to allow for lengthy addresses.
Figure 100 (Part 1 of 7). Example Using Pointers to Access User Spaces
Figure 100 (Part 2 of 7). Example Using Pointers to Access User Spaces
Figure 100 (Part 3 of 7). Example Using Pointers to Access User Spaces
Figure 100 (Part 4 of 7). Example Using Pointers to Access User Spaces
Figure 100 (Part 5 of 7). Example Using Pointers to Access User Spaces
Figure 100 (Part 6 of 7). Example Using Pointers to Access User Spaces
Figure 100 (Part 7 of 7). Example Using Pointers to Access User Spaces
.1/ The compiler directive TITLE is used to create this title that appears at
the beginning of each page.
.3/ CRT STATUS IS specifies a data name into which a status value is
placed after the termination of an extended ACCEPT statement. In this
example, the STATUS key value is used to determine which function
key was pressed.
.4/ fs-cust-address is a variable-length field. To see meaningful names
here rather than FILLER, specify *VARCHAR for the CVTOPT param-
eter of the CRTCBLPGM command, or VARCHAR in the PROCESS
statement, as shown in .2/. For more information about variable-length
fields, refer to “Declaring Data Items Using CVTOPT Data Types” on
page 130.
.5/ CRT STATUS as mentioned in .3/ is defined here.
.6/ The ws-params structure contains the parameters used when calling the
APIs to access user spaces.
.7/ ws-err-data is the structure for the error parameter for the user space
APIs. Note that the ws-input-l is zero, meaning that any exceptions are
signalled to the program, and not passed in the error code parameter.
For more information on error code parameters, refer to the System
Programmer’s Interface Reference.
.8/ ws-space-ptr defines a pointer data item set by the API QUSPTRUS.
This points to the beginning of the user space, and is used to set the
addresses of items in the Linkage Section.
.9/ The first data structure (ls-header-record) to be defined in the user
space.
.1ð/ FILLER is used to maintain pointer alignment, because it makes Is-
header-record a multiple of 16 bytes long.
.11/ The second data structure (ls-user-space) to be defined in the user
space.
.12/ initial-display shows the Create Customer Information Area display. This
display is shown in Figure 101 on page 300.
.13/ read-initial-display reads the first display, and determines if the user
chooses to continue or end the program. If the user continues the
program by pressing Enter, then the program checks ws-accept-data to
see if the customer information area is to be created.
.14/ QUSCRTUS is an API used to create user spaces.
F3=Exit
á ñ
Figure 101. Create Customer Information Area Display
If you specify Y to create the user space, the program reads the customer records
from the file and puts the information in the user space. The records are chained
together.
When you press enter from the previous display, the Customer Information display
appears:
à@ Customer Information
ð
Cust Customer Name Customer Address
Number
ððððððð1 Bakery Unlimited 3ð Bake Way, North York
ððððððð2 Window World 15ð Eglinton Ave E., North York, Ontario
ððððððð3 Jons Clothes 1ð1 Park St, North Bay, Ontario, Canada
ððððððð4 Pizza World 254 Main Street, Toronto, Ontario +
ððððððð5 Marv's Auto Body 9 George St, Peterborough, Ontario, Cana +
ððððððð6 Jack's Snacks 23 North St, Timmins, Ontario, Canada
ððððððð7 Video World 14 Robson St, Vancouver, B.C, Canada
ððððððð8 Pat's Daycare 8 Kingston Rd, Pickering, Ontario, Canad +
ððððððð9 Mary's Pies 3 Front St, Toronto, Ontario, Canada
ðððððð1ð Carol's Fashions 19 Spark St, Ottawa, Ontario, Canada
ðððððð11 Grey Optical 5 Lundy's Lane, Niagara Falls, Ont. Cana +
ðððððð12 Fred's Forage 33 Dufferin St, Toronto, Ontario, Canada +
ðððððð13 Dave's Trucking 15 Water St, Guelph, Ontario, Canada
ðððððð14 Doug's Music 1ð1 Queen St. Toronto, Ontario, Canada +
ðððððð15 Anytime Copiers 3ðð Warden Ave, Scarborough, Ontario, Ca +
ðððððð16 Rosa's Ribs 44ð Avenue Rd, Toronto, Ontario, Canada
F3=Exit F8=Forward
á ñ
Figure 102. Customer Information Area Display
If there are more than 16 records in the user space (based on the starting line in
ws-start-line), the program enables the F8=Forward key, to allow the user to page
à@ Customer Information
ð
Cust Customer Name Customer Address
Number
ðððððð17 Picture It 33 Kingston Rd, Ajax, Ontario, Canada
ðððððð18 Paula's Flowers 144 Pape Ave, Toronto, Ontario, Canada
ðððððð19 Mom's Diapers 1ð1 Ford St, Toronto, Ontario, Canada
ðððððð2ð Chez Francois 12ð2 Rue Ste Anne, Montreal, PQ, Canada
ðððððð21 Vetements de Louise 892 Rue Sherbrooke, Montreal E, PQ, Cana +
ðððððð22 Good Eats 355 Lake St, Port Hope, Ontario, Canada
F3=Exit F7=Back
á ñ
Figure 103. Customer Information Display (Second Display)
When the user exits from the above display, the option to delete the user space is
presented, as shown in the following display:
F3=Exit
á ñ
Figure 104. Delete Customer Information Display
For this example, picture a chained list of data that is composed of individual salary
records. Figure 105 shows one way to visualize how these records are linked in
storage:
┌─────────┐ ┌───────────┐
│ │ │ │
SALARY RECORD 6 │ 6 │ 6
┌───────────┴─┐ ┌──────────┴─┐ ┌─────────────┐
PTR─NEXT─REC │addr of next │ │ │ │NULL─invalid │
│rec │ │ │ │addr │
NAME ├─────────────┤ ├────────────┤ . . . ├─────────────┤
│ │ │ │ │ │
SALARY ├─────────────┤ ├────────────┤ ├─────────────┤
│ │ │ │ │ │
└─────────────┘ └────────────┘ └─────────────┘
The first item in each record (except for the last record) points to the next record.
The first item in the last record, in order to indicate that it is the last record, con-
tains a null value instead of an address.
The high-level logic of an application that processes these records might look
something like this:
OBTAIN ADDRESS OF FIRST RECORD IN CHAINED LIST FROM ROUTINE
CHECK FOR END OF THE CHAINED LIST
DO UNTIL END OF THE CHAINED LIST
PROCESS RECORD
GO ON TO THE NEXT RECORD
END
Figure 106 on page 303 contains an outline of the processing program, LISTS,
used in this example of processing a chained list.
Upon return from the call to CHAIN-ANCH, PTR-FIRST contains the address of the
first record in the chained list.
The Linkage Section of the calling program contains the description of the records
in the chained list. It also contains the description of the department code that is
passed through the USING phrase of the CALL statement.
LINKAGE SECTION.
ð1 SALARY-REC.
ð2 PTR-NEXT-REC POINTER.
ð2 NAME PIC X(2ð).
ð2 DEPT PIC 9(4).
ð2 SALARY PIC 9(6).
ð1 DEPT-X PIC 9(4).
A pointer data item can be assigned the value NULL in two ways:
A pointer data item can be defined with a VALUE IS NULL clause in its data
definition.
NULL can be the sending field in a SET statement.
The initial value of a pointer data item with or without a VALUE clause of NULL
equals NULL.
In the case of a chained list in which the pointer in the last record contains a null
value, the code to check for the end of the list would be:
IF PTR-NEXT-REC = NULL
..
.
If you have not reached the end of the list, process the record and move on to the
next record.
In the program LISTS, this test for the end of the chained list is accomplished with
a “do while” structure:
PERFORM WITH TEST BEFORE UNTIL ADDRESS OF SALARY-REC = NULL
IF DEPT = DEPT-X
THEN ADD SALARY TO DEPT-TOTAL
ELSE CONTINUE
END-IF
SET ADDRESS OF SALARY-REC TO PTR-NEXT-REC
END-PERFORM
Then repeat the record-processing routine, which will process the next record in the
chained list.
Because pointer data items are not numeric, you cannot directly perform arithmetic
on them. You can, however, use the SET verb to increment the passed address in
order to bypass header information.
Within the Procedure Division, base the address of SALARY-REC on the address
of REAL-SALARY-REC:
SET ADDRESS OF SALARY-REC TO ADDRESS OF REAL-SALARY-REC
Data Areas
A data area is an object used to communicate data such as variable values
between programs within a job and between jobs. A data area can be created and
declared to a program before it is used in that program or job. For information on
how to create and declare a data area, see the CL Programmer’s Guide.
The system automatically creates a local data area for each job. The local data
area is defined outside the COBOL program as an area of 1024 bytes.
A COBOL program can access the local data area for its job with the ACCEPT and
DISPLAY statements, using a mnemonic name associated with the function-name
LOCAL-DATA.
There is only one local data area associated with each job. Even if several work
stations are acquired by a single job, only one local data area exists for that job.
There is not a local data area for each work station.
If you use a prestart job, you do not have to wait for a program that you call to go
through job initiation processing. Job initiation is performed before a program can
actually start. Because job initiation has already taken place, a prestart job allows
your program to start more quickly after the program start request is received.
A COBOL program can access the PIP data area for its job with the ACCEPT
statement, using a mnemonic name associated with the function-name PIP-DATA.
The PIP data area is a 2 000-byte alphanumeric item and contains parameters
received from a calling program. It provides the program initialization parameters
that, in non-prestart jobs, is provided through standard COBOL parameters.
You use a Format 5 ACCEPT statement to access the PIP data area, similar to the
way in which you use a Format 4 ACCEPT statement to read from the local data
area. Note that you cannot update the PIP data area using COBOL. See the
COBOL/400 Reference for detailed syntax information.
For more information regarding prestart jobs and the PIP data area, refer to the
Work Management Guide and the CL Programmer’s Guide.
File Considerations
You can pass a file name as a parameter in a COBOL program, but you cannot
use that file in the called program. If a file is defined in both a calling program and
a called program, it is treated as two separate files. The contents of the record
area and the current record pointer in each program are independent, unless
shared files are specified in CL commands. See the Data Management Guide for
further information on shared files.
A GOBACK statement issued from a main program closes all of the files in a
run unit. A GOBACK statement issued from a subprogram does not change
the status of any of the files in a run unit.
A CANCEL statement does not change the status of any of the files in the
program that is canceled. It does free the storage that contains information
about the file. If the program has files that are open when the CANCEL state-
ment is processed, those files are closed when that program is cancelled. The
program can no longer use the file. If the canceled program is called again,
the program considers the file closed. If the program opens the file, a new
linkage to the file is established. This can cause additional system storage to
be used.
Segmentation Concepts
Although it is not required, the Procedure Division of a source program is often
written as a consecutive group of sections, each of which is made up of a series of
related operations that perform a particular function. Thus, the entire Procedure
Division is made up of a number of logical subdivisions. Segmentation allows the
programmer to physically divide the Procedure Division into segments, each of
which has specific physical and logical attributes.
When Segmentation is used, the entire Procedure Division must be divided into
sections. Each section must then be classified as to its physical and logical attri-
butes. Classification is specified by means of segment numbers. All sections given
the same segment number make up one program segment.
Program Segments
There are three types of program segments; fixed permanent, fixed overlayable,
and independent.
Fixed Segments
Fixed-permanent segments and fixed-overlayable segments make up the fixed
portion, the part of the Procedure Division that is logically treated as if it were
always physically present in main storage. Fixed-portion segment numbers must
be integers from 0 through 49.
Independent Segments
Logically, an independent segment can overlay and be overlaid by other segments
during a program’s run.
An independent segment is made available in its initial state the first time control is
passed to it (explicitly or implicitly) during a program’s run.
Segmentation Logic
In a segmented program, the sections are classified by a system of segment
numbers according to the following criteria:
Frequency of Reference–Much-referenced sections, or those that must be
available for reference at all times, should be placed within fixed permanent
segments. Less frequently used sections can be within either fixed overlayable
or independent segments, depending on the program logic.
Frequency of Use–The more frequently a section is used, the lower its segment
number; the less frequently it is referred to, the higher its segment number.
Logical Relationships–Sections that frequently communicate with each other
should be given identical segment numbers.
Segmentation Control
Except for specific transfers of control, the logical sequence and the physical
sequence of program instructions are the same. The compiler inserts any
instructions necessary to initialize a segment. It is not necessary to transfer control
to the beginning of a segment, or to the beginning of a section within a segment.
Instead, control can be transferred to any paragraph in the Procedure Division.
Segmentation–Environment Division
In the OBJECT-COMPUTER paragraph, the SEGMENT-LIMIT clause allows the
user to reclassify fixed permanent segments while retaining the properties of fixed
portion segments for the reclassified segments.
Format
55───SEGMENT-LIMIT──┬────┬──segment-number───────────── . ───────────────────5%
└─IS─┘
When the SEGMENT-LIMIT clause is omitted, all sections with segment numbers 0
through 49 are fixed-permanent segments.
Segmentation–Procedure Division
In the Procedure Division of a segmented program, section classification is speci-
fied through segment numbers in the section headers. The segment number must
be an integer from 0 through 99.
Format
55───section-name──SECTION──┬────────────────┬──.────────────────────────────5%
└─segment-number─┘
All sections with the same segment number make up one program segment. Such
sections need not be contiguous in the source program.
Segmentation–Special Considerations
When segmentation is used, there are restrictions on the ALTER, PERFORM,
SORT, and MERGE statements. There are also special considerations for calling
and called programs.
ALTER Statement
A GO TO statement in an independent segment must not be referred to by an
ALTER statement in a different segment. All other uses of the ALTER statement
are valid and are performed, even if the GO TO statement referred to is in a fixed-
overlayable segment.
PERFORM Statement
A PERFORM statement in the fixed portion can have in its range, in addition to any
Declarative procedures, the processing of which is caused within that range, only
one of the following:
Sections and/or paragraphs in the fixed portion
Sections and/or paragraphs contained within a single independent segment.
COBOL source language debugging statements are provided. You must decide
what to monitor, and what information you need to retrieve for debugging purposes.
The COBOL debugging features simply provide access to pertinent information.
Compile-Time Switch
In the SOURCE-COMPUTER paragraph of the Configuration Section, the WITH
DEBUGGING MODE clause acts as a compile-time switch.
Format
55───SOURCE-COMPUTER.─┬─────────────────────────────────────────────┬─.──────5%
└─computer name─┬──────────────────────────┬──┘
└─┬──────┬──DEBUGGING MODE─┘
└─WITH─┘
The WITH DEBUGGING MODE clause serves as a compile-time switch for the
debugging statements written in the source program.
When WITH DEBUGGING MODE is specified, all debugging sections and debug-
ging lines are compiled as specified in this appendix. When WITH DEBUGGING
MODE is omitted, all debugging sections and debugging lines are treated as doc-
umentation.
Two commands are provided to control the run-time switch. To set the run-time
switch on, enter the command:
STRCBLDBG
and press F4.
Program . . . . . . . . . . . . Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB
Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
á ñ
55──STRCBLDBG──┬────────────────────────────────────────────┬─────────────────5%
└─PGM──(─┬─────────────────┬──program-name─)─┘
├──\LIBL/─────────┤
├──\CURLIB/───────┤
└──library-name/──┘
┌───────────────────────────────────┐
│Job: B,I Pgm: B,I REXX: B,I Exec│
└───────────────────────────────────┘
Program . . . . . . . . . . . . Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB
Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
á ñ
55──ENDCBLDBG──┬────────────────────────────────────────────┬─────────────────5%
└─PGM──(─┬─────────────────┬──program-name─)─┘
├──\LIBL/─────────┤
├──\CURLIB/───────┤
└──library-name/──┘
┌───────────────────────────────────┐
│Job: B,I Pgm: B,I REXX: B,I Exec│
└───────────────────────────────────┘
When debugging mode is specified through the run-time switch, all the debugging
sections and debugging lines (D in column 7) compiled into the program are acti-
vated.
When debugging mode is suppressed, through the run-time switch, any USE FOR
DEBUGGING Declarative procedures are inhibited. All debugging lines (D in
column 7) remain in effect.
Format
┌────────────────────────────────────────┐
6 │
55───USE─┬─────┬─DEBUGGING─┬────┬─┬─┬───────────────────────┬─identifier-1─┼─5%
└─FOR─┘ └─ON─┘ │ └─ALL─┬───────────────┬─┘ │
│ └─REFERENCES OF─┘ │
├─file-name-1────────────────────────────┤
├─procedure-name-1───────────────────────┤
└─ALL PROCEDURES─────────────────────────┘
When specified, all debugging sections must be written immediately after the
DECLARATIVES header. Except for the USE FOR DEBUGGING sentence there
must be no reference to any non-declarative procedure within the debugging proce-
dure.
Note that the USE FOR DEBUGGING declarative causes all subsequent state-
ments to be ignored up to a valid USE AFTER EXCEPTION/ERROR statement, or
END DECLARATIVES delimiter. Entire programs can be ignored because of this.
Statements appearing outside the debugging sections must not refer to procedure
names defined within the debugging sections.
Except for the USE FOR DEBUGGING sentence itself, statements within a debug-
ging Declarative section can only refer to procedure names defined in a different
USE procedure through the PERFORM statement. Procedure names within debug-
ging Declarative sections must not appear in USE FOR DEBUGGING sentences.
Table 7 defines the points during program run time when the USE FOR DEBUG-
GING procedures are processed. Identifier-n, file-name-n, and procedure-name-n
refer to the first and all subsequent specifications of that type of operand in one
USE FOR DEBUGGING sentence. Any particular identifier, file name, or procedure
name can appear in only one USE FOR DEBUGGING sentence, and only once in
that sentence.
References to the DEBUG-ITEM special register can be made only from within a
debugging Declarative procedure.
Note: Operands acted upon but not explicitly named in such statements as ADD,
MOVE, or SUBTRACT CORRESPONDING never cause activation of a USE
FOR DEBUGGING procedure when such statements are run. If identifier-n
is specified in a phrase that is not processed, the associated debugging
section is not run.
ð1 DEBUG-ITEM.
ð2 DEBUG-LINE PICTURE IS X(6).
ð2 FILLER PICTURE IS X VALUE SPACE.
ð2 DEBUG-NAME PICTURE IS X(3ð).
ð2 FILLER PICTURE IS X VALUE SPACE.
ð2 DEBUG-SUB-1 PICTURE IS S9999 SIGN IS
LEADING SEPARATE CHARACTER.
ð2 FILLER PICTURE IS X VALUE SPACE.
ð2 DEBUG-SUB-2 PICTURE IS S9999 SIGN IS
LEADING SEPARATE CHARACTER.
ð2 FILLER PICTURE IS X VALUE SPACE.
ð2 DEBUG-SUB-3 PICTURE IS S9999 SIGN IS
LEADING SEPARATE CHARACTER.
ð2 FILLER PICTURE IS X VALUE SPACE.
ð2 DEBUG-CONTENTS PICTURE IS X(n).
Each debugging line must be written so that a syntactically correct program results
whether the debugging lines are compiled into the program or syntax-checked, but
are treated as documentation.
When the WITH DEBUGGING MODE clause is omitted, all debugging lines are
syntax-checked, but are treated as documentation.
The seven required modules are: Nucleus, Sequential I-O, Relative I-O, Indexed
I-O, Inter-Program Communication, Sort-Merge, and Source Text Manipulation.
The four optional modules are: Report Writer, Communication, Debug and Seg-
mentation.
Language elements within the modules may be classified as level 1 elements and
level 2 elements. Elements within nine of the modules are divided into level 1 ele-
ments and level 2 elements. Two of the modules (SORT-MERGE and REPORT
WRITER) contain only level 1 elements. For instance, Nucleus level 1 elements
perform basic internal operations. Nucleus level 2 elements provide for more
extensive and sophisticated internal processing.
The three subsets of Standard COBOL are the high subset, the intermediate
subset, and the minimum subset. Each subset is composed of a level of the seven
required modules: Nucleus, Sequential I-O, Relative I-O, Indexed I-O, Inter-
Program Communication, Sort-Merge, and Source Text Manipulation. The four
optional modules (Report Writer, Communication, Debug and Segmentation) are
not required in the three subsets of Standard COBOL.
The high subset is composed of all language elements of the highest level of
all required modules. That is:
Level 2 elements from Nucleus, Sequential I-O, Relative I-O, Indexed I-O,
Inter-Program Communication, and Source Text Manipulation
Level 1 elements from Sort-Merge.
The intermediate subset is composed of all language elements of level 1 of all
required modules. That is:
Level 1 elements from Nucleus, Sequential I-O, Relative I-O, Indexed I-O,
Inter-Program Communication, Sort-Merge, and Source Text Manipulation.
The minimum subset is composed of all language elements of level 1 of the
Nucleus, Sequential I-O, and Inter-Program Communication modules.
The four optional modules are not an integral part of any of the subsets. However,
none, all, or any combination of the optional modules may be associated with any
of the subsets.
If you want to customize any of the specifications, you must copy any members
that you want to change to a source file in one of your libraries. You can use the
Copy File (CPYF) command to do this. For more information about the CPYF
command, refer to the CL Reference.
If you copy these specifications to your library, you must refresh your copies when
a new product release is installed, or when any changes are made using a
Program Temporary Fix (PTF). IBM provides maintenance for these specifications
only in the libraries in which they are distributed.
COBOL/400 Messages
This appendix provides a general description of messages that IBM supplies with
the COBOL/400 licensed program.
Interactive Messages
In an interactive environment, messages are displayed on the work station display.
They can appear on the current display as a result of the running of the program or
in response to your keyed input to prompts, menus, command entry displays, or
Application Development Tools (Appl Dev Tools). The messages can also appear
on request, as a result of a display command or an option on a menu.
The messages for the COBOL/400 licensed program begin with an LSC, LBE, or
LBL prefix.
The LSC messages are issued by the COBOL/400 syntax checker when the
Source Entry Utility (SEU) is used to enter your COBOL/400 source. For example,
you see the following display after incorrectly entering the program name in the
PROGRAM-ID paragraph.
F3=Exit F12=Cancel
á ñ
Figure 110. Run-Time Error Message
If you move the cursor to the line on which message number CPF4101 is indicated
and press either the HELP key or F1, the LBE message information is displayed as
shown:
LBE messages 7900 to 7999 are used as headings for information printed during a
COBOL/400 formatted dump.
Compilation Messages
LBL messages are printed in the program listing when errors are found during
program compilation. The LBL messages include the message issued when
Federal Information Processing Standard (FIPS) flagging is requested; for more
information on the FIPS messages, refer to page 331 in this appendix.
Program Listings
In the compiler output, the COBOL/400 messages listing follows the source listing.
The COBOL/400 messages listing gives the message identifier, severity, text,
usually the location of the error, and the messages summary.
For more information about Program Listings, see “Source Listing” on page 41.
Responding to Messages
In an interactive environment, a message is indicated by one or several of these
conditions:
A brief message (called first-level text) on the message line
Reverse image highlighting of the input field in error
A locked keyboard
The sound of an alarm (if the alarm option is installed).
If the necessary correction is obvious from the initial display, you can press the
Error Reset key (if the keyboard is locked), enter the correct information, and con-
tinue your work.
If the message requires that you choose a reply (such as C to cancel, D to dump
COBOL identifiers, F to dump all variables, or G to resume processing at the next
COBOL statement), the reply options are shown in parentheses in the first-level
message text. For an example, see Figure 110 on page 328.
If the information on the initial information display does not provide sufficient data
for you to handle the error, you can press the HELP key (after positioning the
cursor to the message line, if required) to get a second-level display with additional
information about how to correct this error. To return to the initial display, press the
Enter key; then press the Error Reset key (if the keyboard is locked), and make
your correction or response.
If the error occurs when you are compiling or running a program, you might need to
modify your COBOL/400 source statements or control language (CL) commands.
Refer to the SEU User’s Guide and Reference for information on how to change
the statements.
Severity Levels
The COBOL/400 licensed program provides the following message severity levels:
Severity Meaning
00 Informational: This level is used to convey information to the user.
No error has occurred. Informational messages are listed only when
the FLAG (00) option is specified.
10 Warning: This level indicates that an error was detected but is not
serious enough to interfere with the running of the program.
20 Error: This level indicates that an error was made, but the compiler
is taking a recovery that might yield the desired code.
30 Severe Error: This level indicates that a serious error was detected.
Compilation is completed, but running of the program cannot be
attempted.
40 Unrecoverable: This level usually indicates a user error that forces
termination of processing.
50 Unrecoverable: This level usually indicates a compiler error that
forces termination of processing.
99 Action: Some manual action is required, such as entering a reply,
changing printer forms, or replacing diskettes.
Note: 00, 10, and 20 messages are suppressed when the FLAG(30) option of the
PROCESS statement is used or the CRTCBLPGM command specifies
FLAG(30) and is not overridden by the PROCESS statement. See “Using
the PROCESS Statement to Specify Compiler Options” on page 32 for
further information.
The OS/400 message facility is used to produce all messages. The COBOL/400
compiler messages reside in the message file, QLBLMSG, and the run-time mes-
sages reside in the message file, QLBLMSGE.
Substitution variables and valid reply values are determined by the program
sending the message, not by the message description stored in the message file.
However, certain elements of a message description can be changed: for example,
the text, severity level, default response, or dump list. To effect such changes, you
need to define another message description using an Add Message Description
(ADDMSGD) command, place the modified description in a user-created message
file,1 and specify that file in the Override Message File (OVRMSGF) command.
Using the OVRMSGF command allows the compiler to retrieve messages from the
specified file. See the ADDMSGD and OVRMSGF commands in the CL Reference
for additional information.
The monitoring is an analysis that compares the syntax used in the source program
with the syntax included in the user-selected FIPS subset and optional modules.
Any syntax used in the source program that does not conform to the selected FIPS
COBOL subset and optional modules is identified. Any syntax for an obsolete lan-
guage element used in the source program will also be identified (depending on the
compiler option chosen). See page 25 for more information on the parameters for
FIPS flagging.
1986 FIPS COBOL specifications are the language specifications contained in ANSI
X3.23-1985 COBOL. FIPS COBOL is subdivided into three subsets and four
optional modules. The three subsets are identified as Minimum, Intermediate and
High. The four optional modules are Report Writer, Communication, Debug, and
Segmentation. These four optional modules are not an integral part of any of the
subsets; however, none, all, or any combination of the optional modules may be
associated with any of the subsets. Any program written to conform to the 1986
FIPS standard must conform to one of the subsets of 1986 FIPS COBOL.
1 If an IBM-supplied message must be changed and replaced in its message file, call your service representative.
Table 10. 1985 American National Standard COBOL and 1986 FIPS Levels
1985 ANSI
Module Name High Intermediate Minimum
FIPS FIPS FIPS
Nucleus 2 NUC 1,2 1 NUC 1,2 1 NUC 1,2
Sequential I-O 2 SEQ 1,2 1 SEQ 1,2 1 SEQ 1,2
Relative I-O 2 REL 0,2 1 REL 0,2 0 REL 0,2
Indexed I-O 2 INX 0,2 1 INX 0,2 0 INX 0,2
Source-Text
Manipulation 2 STM 0,2 1 STM 0,2 0 STM 0,2
Sort-Merge 1 SRT 0,1 1 SRT 0,1 0 SRT 0,1
Inter-Program
Communication 2 IPC 1,2 1 IPC 1,2 1 IPC 1,2
Report Writer 0, or 1 RPW 0,1 0, or 1 RPW 0,1 0, or 1 RPW 0,1
Segmentation 0,1 or 2 SEG 0,2 0,1 or 2 SEG 0,2 0,1 or 2 SEG 0,2
Debug 0,1 or 2 DEB 0,2 0,1 or 2 DEB 0,2 0,1 or 2 DEB 0,2
Communications 0,1 or 2 COM 0,2 0,1 or 2 COM 0,2 0,1 or 2 COM 0,2
Note: The COBOL/400 compiler supports the Segmentation and Debug optional
modules.
Elements that are specified in the COBOL/400 source program and that are not
included in 1986 FIPS COBOL are flagged as described in Appendix C, “Level of
Language Support” on page 323.
In this way, you can write programs that conform to the SAA COBOL definition.
For an example of SAA flagging in a compiler listing, see Figure 12 on page 47.
To perform SAA flagging through the CRTCBLPGM CL command, specify
SAAFLAG(*FLAG). To perform SAA flagging through a PROCESS statement,
specify SAAFLAG.
For more information about specifying the option for SAA flagging, see the
SAAFLAG parameter on page 25, and the “Using the PROCESS Statement to
Specify Compiler Options” on page 32.
For information about compiler limits, see the Compiler Limits appendix in the
COBOL/400 Reference.
See “Industry Standards Used in Compiler Design” on page xiii for more informa-
tion on ANSI 85 COBOL.
IBM Extension
This appendix describes only those enhancements made to the COBOL program-
ming language for writing programs that process double-byte characters.
Specifically, this appendix describes where you can use Double-Byte Character Set
(DBCS) characters in each portion of a COBOL program, and considerations for
working with DBCS data in the COBOL/400 language.
You can now use DDS descriptions that define DBCS-graphic data fields with your
COBOL/400 programs. DBCS-graphic pertains to a character string where each
character is represented by two bytes. The character string does not contain
shift-out or shift-in characters. You cannot use source programs containing graphic
data. For information on specifying graphic data items with your COBOL/400 pro-
grams, refer to “DBCS-Graphic Fields” on page 133.
Types of Literals
There are two types of literals in which you can use DBCS characters: the DBCS
literal and the mixed literal. A mixed literal consists of Double-Byte Character Set
(DBCS) and Single-Byte Character Set (SBCS) characters.
How to Specify a DBCS Literal: When you specify a DBCS literal, keep in mind
the following:
The maximum length of a DBCS literal is 80 DBCS characters, including the shift
control characters. (These counted together are equivalent in length to one DBCS
character.) The shift control characters are part of the literal, and take part in all
operations.
See “How to Continue DBCS Literals on a New Line” on page 339 for information
on how to extend DBCS literals.
The shift control characters are part of the literal, and take part in all operations.
Other Considerations
Quotation Marks: Although the preceding discussion uses the term a quotation
mark to describe the character that identifies a literal, the character actually used
can vary depending upon the option specified on the CRTCBLPGM CL command,
or on the PROCESS statement. If you specify the APOST option, an apostrophe
(') is used. Otherwise, a quotation mark (") is used. In this appendix, a quotation
mark refers to both an apostrophe and a quotation mark. The character that you
choose does not affect the rules for specifying a literal.
Shift Characters: The shift-out and shift-in characters separate EBCDIC characters
from DBCS characters. They are part of both the DBCS and the DBCS/SBCS
literal. Therefore, the shift code characters participate in all operations when they
appear in either DBCS or DBCS/SBCS literals.
The following conditions cause the COBOL compiler to diagnose a literal containing
DBCS characters as not valid:
The syntax for the literal is incorrect.
The DBCS literal is longer than one line and does not follow the rules for con-
tinuing nonnumeric literals. (See “How to Continue DBCS Literals on a New
Line” for more information.)
The DBCS/SBCS literal is longer than one line.
When the COBOL compiler finds a DBCS literal that is not valid, it generates an
error message, and then processes the literal as an alphanumeric literal.
For each DBCS or SBCS literal that is not valid, the compiler generates an error
message and accepts or ignores the literal.
For example:
-A 1 B
..
.
ð1 DBCS1 PIC X(12) VALUE "ðEK1K2K3ðF
- "ðEK4K5ðF".
..
.
The shift-in character, quotation mark, and shift-out character used to continue a
line are not counted in the length of the DBCS literal. The first shift-out and final
shift-in characters are counted.
Identification Division
You can put comment entries that contain DBCS characters in any portion of the
Identification Division except the PROGRAM-ID paragraph. The program name
specified in the PROGRAM-ID paragraph must be alphanumeric.
Environment Division
Configuration Section
You can use DBCS characters in comment entries only in the Configuration Section
paragraph. All function-names, mnemonic-names, condition-names, and alphabet-
names must be specified with alphanumeric characters. For the
SOURCE-COMPUTER and the OBJECT-COMPUTER entry, use the alphanumeric
computer name:
IBM-AS400
For indexed files, the data name in the RECORD KEY clause can refer to a DBCS
or DBCS/SBCS data item within a record. The number of fields in the record, plus
the number of positions occupied by the record key, together cannot be greater
than 120.
Note: Each DBCS character occupies two positions, and the shift control charac-
ters each occupy one position. Ensure that both the data description of the
key and the key position within the file match those specified when you
created the file.
You cannot use DBCS and DBCS/SBCS data as the RELATIVE KEY in relative
files.
Data Division
File Section
For the FD (File Description) Entry, you can use DBCS or DBCS/SBCS data items
or literals in the VALUE OF clause. The DATA RECORDS clause can refer to data
items only. Because the COBOL/400 compiler treats both the VALUE OF clause
and the DATA RECORDS clause in the File Section as documentation, neither
clause has any effect when you run the program. However, the COBOL compiler
checks all literals in the VALUE OF clause to make sure they are valid.
For magnetic tapes, the system can only read DBCS characters from, or write
DBCS characters to, the tape in the EBCDIC format. The system cannot perform
tape functions involving a tape in the ASCII format. Define the alphabet-name in
the CODE-SET clause as NATIVE. Use alphanumeric characters to specify the
alphabet-name.
Working-Storage Section
REDEFINES Clause: The existing rules for redefining data also apply to data that
contains DBCS characters. When you determine the length of a redefining or rede-
fined data item, remember that each DBCS character is twice as long as an alpha-
numeric character.
Also, ensure that redefined data items contain the shift control characters when and
where necessary.
OCCURS Clause: Use this clause to define tables for storing DBCS or
DBCS/SBCS data. If you specify the ASCENDING/DESCENDING KEY phrase,
COBOL assumes the contents of the table are in the EBCDIC program collating
sequence. The shift control characters in DBCS and DBCS/SBCS data take part in
the collating sequence.
For more information about handling tables that contain DBCS characters, see
“Table Handling–SEARCH Statement” on page 348.
The JUSTIFIED clause does not affect the initial setting in the VALUE clause.
VALUE Clause: You can use DBCS or DBCS/SBCS literals to specify an initial
value for a data item that is not numeric, or to define values for level-88 condition-
name entries.
Any shift control characters in the literal are considered part of the literal’s picture
string, except when used to continue a new line. When you continue a DBCS
literal, the compiler does not include the shift-in character in column 71 or 72, or
the initial quotation mark (") and shift-out character on the continued line as part of
the DBCS literal. Make certain, however, that the DBCS literal does not exceed the
size of the data item specified in the PICTURE clause, otherwise truncation occurs.
Note: DBCS/SBCS mixed literals cannot be continued to a new line.
When you use literals that contain DBCS characters in the VALUE clause for
level-88 condition-name entries, COBOL treats the DBCS characters as alphanu-
meric. Therefore, follow the rules for specifying alphanumeric data, including
allowing a THROUGH option. This option uses the normal EBCDIC collating
sequence, but remember that shift control characters in DBCS and DBCS/SBCS
data take part in the collating sequence.
PICTURE Clause: Use the PICTURE symbol X to define DBCS and DBCS/SBCS
data items. Because DBCS characters are twice as long as alphanumeric, and are
enclosed within shift control characters, you would define a DBCS data item con-
taining n DBCS characters as
PICTURE X(2n+2)
A DBCS/SBCS data item containing m SBCS characters, and one string of n DBCS
characters would be defined as
PICTURE X(m+2n+2)
You can use all edited alphanumeric PICTURE symbols for DBCS and
DBCS/SBCS data items. The editing symbols have the same effect on the DBCS
data in these items as they do on alphanumeric data items. Check that you have
obtained the desired results.
Declaratives
An identifier in the USE FOR DEBUGGING sentence of the DECLARATIVES
section can refer to a DBCS or a DBCS/SBCS data item.
You cannot use DBCS characters for file names or procedure names in the USE
FOR DEBUGGING sentence.
Conditional Expressions
Because condition-names (level-88 entries) can refer to data items that contain
DBCS characters, you can use the condition-name condition to test this data. (See
“VALUE Clause” on page 342.) Follow the rules listed in the COBOL/400
Reference for using conditional variables and condition-names.
You can use DBCS or DBCS/SBCS data items or literals as the operands in a
relation condition. Because COBOL treats DBCS data as alphanumeric, all com-
parisons occur according to the rules for alphanumeric operands. Keep the fol-
lowing in mind:
The system does not recognize the mixed content.
The system uses the shift codes in comparisons of DBCS and DBCS/SBCS
data.
The system compares the data using either the EBCDIC collating sequence, or
a user-defined sequence.
In a comparison of DBCS or DBCS/SBCS items with similar items of unequal
size, the smaller item is padded on the right with EBCDIC spaces.
You can use class conditions and switch status conditions as described in the
COBOL/400 Reference.
Input/Output Statements
ACCEPT Statement: The input data received from a device by using a Format 1
ACCEPT statement can include DBCS or DBCS/SBCS data. All DBCS and
DBCS/SBCS data must be identified by the proper syntax. The input data,
including shift control characters, replaces the existing contents of the identifier.
COBOL does not perform editing or error checking on the data.
Information received from the local data area by a Format 4 ACCEPT statement
can include DBCS or DBCS/SBCS character strings. Information received replaces
the existing contents. COBOL does not perform any editing or checking for errors.
This also applies to information received from the PIP data area by a Format 5
ACCEPT statement.
Using the Format 6 ACCEPT statement, you can get the attributes of a work station
display and its keyboard. For display stations that can display DBCS characters,
If you use an extended (Format 7) ACCEPT statement for field-level work station
input, you must ensure that DBCS data is not split across lines. COBOL does not
perform any editing or checking for errors.
Because COBOL does not know the characteristics of the device on which data is
being displayed, you must make sure that the DBCS and DBCS/SBCS data is
| correct. It may be necessary to specify the extended display option
| *NOUNDSPCHAR (or the equivalent process statement parameter option) when the
| program is compiled, to ensure that a workstation can handle DBCS data correctly.
Note: ALL is a valid option for mixed literals.
If you use an extended (Format 3) DISPLAY statement for field-level work station
output, you must ensure that DBCS data is not split across lines.
READ Statement: You can use DBCS or DBCS/SBCS data items as the
RECORD KEY for an indexed file. See “Input-Output Section” on page 341 for
more information.
INTO Phrase: You can read a record into a DBCS or a DBCS/SBCS data item
using the INTO phrase. This phrase causes a MOVE statement (without the COR-
RESPONDING option) to be performed. The compiler moves DBCS and
DBCS/SBCS data in the same manner that it moves alphanumeric data. It does
not make sure that this data is valid.
REWRITE Statement: Use the FROM phrase of this statement to transfer DBCS
or DBCS/SBCS data from a DBCS or a DBCS/SBCS data item to an existing
record. The FROM phrase causes both types of data to be moved in the same
manner as the INTO phrase with the READ statement. (See “READ Statement.”)
START Statement: If you use DBCS characters in the key of an indexed file,
specify a corresponding data item in the KEY phrase of the START statement.
You can specify valid operators (such as EQUAL, GREATER THAN, NOT LESS
THAN) in the KEY phrase. The system can follow either the EBCDIC or a user-
defined collating sequence.
You must include the shift control characters when you write the data into a device
file.
INSPECT Statement: You can use any DBCS or DBCS/SBCS data item as an
operand for the INSPECT statement. The system tallies and replaces on each half
of a DBCS character, including the shift control characters in these operations.
Therefore, the data may not be matched properly.
You can use any combination of double-byte character and alphanumeric operands
and double-byte character literals or data items. If you use the REPLACING
phrase, you might cause parts of the inspected item to be replaced by alphanu-
meric data, or vice versa.
You cannot replace a character string with a string of a different length. Consider
this when replacing alphanumeric characters with DBCS characters, or vice versa.
If you want to control the use of the INSPECT statement with items containing
DBCS characters, define data items containing shift control characters. Use the
shift-out and shift-in characters as BEFORE/AFTER operands in the INSPECT
statement.
The following example shows how you can use the INSPECT statement to replace
one DBCS character with another.
ð1 SUBJECT-ITEM PICTURE X(5ð).
ð1 DBCS-CHARACTERS VALUE "ðEK1K2ðF".
ð5 SHIFT-OUT PICTURE X.
ð5 DBCS-CHARACTER-1 PICTURE XX.
ð5 DBCS-CHARACTER-2 PICTURE XX.
ð5 SHIFT-IN PICTURE X.
You can move DBCS/SBCS literals to group items and alphanumeric items.
If the length of the receiving field is different from that of the sending field, COBOL
does one of the following:
Truncates characters from the sending item if it is longer than the receiving
item. This operation can reduce data integrity.
Pads the sending item with blanks if it is shorter than the receiving item.
To understand more about the effect of editing symbols in the PICTURE clause of
the receiving data item, see the COBOL/400 Reference.
SET Statement (Condition-Name Format): When you set the condition name to
TRUE on this statement, COBOL moves the literal from the VALUE clause to the
associated data item. You can move a literal with DBCS characters.
STRING Statement: You can use the STRING statement to construct a data item
that contains DBCS or DBCS/SBCS subfields. All data in the source data items or
literals, including shift control characters, is moved to the receiving data item, one-
half of a DBCS character at a time.
Data items can contain both alphanumeric and DBCS characters within the same
field.
The following example shows how you might set up fields to prepare for the
unstring operation on a character string that contain DBCS/SBCS data:
ð1 SUBJECT-FIELD PICTURE X(4ð)
ð1 FILLER.
ð5 UNSTRING-TABLE OCCURS 4 TIMES.
1ð RECEIVER PICTURE X(4ð).
1ð DELIMTR PICTURE X.
1ð COUNTS PICTURE 99 COMP.
ð1 SHIFTS VALUE "ðEðF".
ð5 SHIFT-OUT PICTURE X.
ð5 SHIFT-IN PICTURE X.
This UNSTRING statement divides a character string into its alphanumeric and
DBCS parts. Assuming that the data in the character string is valid, a delimiter
value of shift-out indicates that the corresponding receiving field contains alphanu-
meric data, while a value of shift-in indicates that corresponding receiving field has
DBCS data. You can check the COUNT data items to determine whether each
receiving field received any characters. The following figure is an example that
shows the results of the UNSTRING operation just described:
SUBJECT-FIELD = ABCðEK1K2K3ðFDðEK4K5K6ðF
RECEIVER (1) = ABC DELIMTR (1) = ðE COUNTS (1) = 3
RECEIVER (2) = K1K2K3 DELIMTR (2) = ðF COUNTS (2) = 6
RECEIVER (3) = D DELIMTR (3) = ðE COUNTS (3) = 1
RECEIVER (4) = K4K5K6 DELIMTR (4) = ðF COUNTS (4) = 6
SUBJECT-FIELD = ðEK1K2K3ðFABCðEK4ðF
RECEIVER (1) = (blanks) DELIMTR (1) = ðE COUNTS (1) = ð
RECEIVER (2) = K1K2K3 DELIMTR (2) = ðF COUNTS (2) = 6
RECEIVER (3) = ABC DELIMTR (3) = ðE COUNTS (3) = 3
RECEIVER (4) = K4 DELIMTR (4) = ðF COUNTS (4) = 2
You can also perform a Format 2 SEARCH statement (SEARCH ALL) against a
DBCS or DBCS/SBCS table as well. Order the table according to the chosen col-
lating sequence.
Note: The shift control characters in DBCS and DBCS/SBCS data participate in
the comparison.
SORT/MERGE
You cannot perform a DBCS alphabet sort using COBOL. However, you can use
DBCS or DBCS/SBCS data items as keys in a SORT or MERGE statement. The
sort operation orders data according to the collating sequence specified in the
SORT, MERGE, or SPECIAL NAMES paragraph. The system orders any shift
control characters contained in DBCS and DBCS/SBCS keys.
Use the RELEASE statement to transfer records containing DBCS characters from
an input/output area to the initial phase of a sort operation. The system performs
the FROM phrase with the RELEASE statement in the same way it performs the
FROM phrase with the WRITE statement. (See “WRITE Statement” on page 345.)
You can also use the RETURN statement to transfer records containing DBCS
characters from the final phase of a sort or merge operation to an input/output area.
The system performs the INTO phrase with the RETURN statement in the same
manner that it performs the INTO phrase with the READ statement. (See “READ
Statement” on page 344.)
Compiler-Directing Statements
COPY Statement
You can use the COPY statement to copy source text that contains DBCS charac-
ters into a COBOL program. When you do, make sure that you specify the
member name, file name, and library name using alphanumeric data, and that you
specify these names according to the rules stated in the COBOL/400 Reference.
Use the Format 2 COPY statement to copy fields defined in the data description
specifications (DDS). DBCS and DBCS/SBCS data items (the value in column 35
of the DDS form is O) are copied into a COBOL program in the PICTURE X(n)
format. The compiler listing does not indicate that these fields contain DBCS char-
acters, unless a field is a key field. In those cases, the system prints an O in the
comment table for keys.
DBCS-graphic data items are copied into a COBOL program in the PICTURE X(N)
format. The compiler listing indicates that these fields contain graphic data. See
You can put DBCS characters in text comments that are copied from DDS if the
associated DDS field has comments.
If you specify the REPLACING phrase of the COPY statement, consider the fol-
lowing:
Pseudo-text can contain any combination of DBCS and alphanumeric charac-
ters.
You can use literals with DBCS or DBCS/SBCS content.
Identifiers can refer to data items that contain DBCS characters.
TITLE Statement
You can use DBCS/SBCS literals as the literal in the TITLE statement.
You can pass DBCS characters from one program to another program by speci-
fying those data items in the USING phrase. You cannot use DBCS characters in
the CALL statement for the program-name of the called program.
You cannot use DBCS characters in the CANCEL statement because they specify
program-names.
FIPS Flagger
Enhancements to the COBOL language that let you use DBCS characters are
flagged (identified) by the FIPS (Federal Information Processing Standard) flagger
provided by the compiler as IBM extensions.
DBCS characters that appear in a program listing originate from the source file,
from source text generated by the COPY statement, or from COBOL compiler mes-
sages.
The compiler may use characters from your source program as substitution param-
eters in compiler and syntax checker messages. The system does not check or
edit the substitution parameters. If you do not specify DBCS characters properly,
the system may print or display parts of messages incorrectly.
Figure 112 (Part 1 of 2). Example of a Sequential File of Employee Salary Records
Figure 112 (Part 2 of 2). Example of a Sequential File of Employee Salary Records
File status values and USE procedures play important roles in error handling. For
more information, see Chapter 6, “COBOL/400 Exception and Error Handling.”
This program creates an indexed file of summary records for bank depositors. The
key within each indexed file record is INDEX-KEY (the depositor’s account
number); the input records are ordered in ascending sequence upon this key.
Records are read from the input file and transferred to the indexed file record area.
The indexed file record is then written.
The input records contain the key for the record, the depositor name, and the
amount of the transaction.
Random access is used for the updating and printing of the transaction records.
Sequential access is used for the retrieval and printing of all records within one
generic class.
Each input record represents the summary sales for one week of one year. The
records for the first week of the last five years (in ascending order) are the first five
input records. The records for the second week of the last five years are the next
five input records, and so on. Thus, five input records fill one output record.
The RELATIVE KEY for the RELATIVE-FILE is not specified because it is not required
for sequential access unless the START statement is used. (For updating,
however, the key is INPUT-WEEK.)
The input record represents the summary sales record for one week of the pre-
ceding year. The RELATIVE KEY for the RELATIVE-FILE is in the input record as
INPUT-WEEK. The RELATIVE KEY is used to check that the record was correctly
written.
The records of the INPUT-FILE contain one required field (INPUT-WEEK), which is
the RELATIVE KEY for RELATIVE-FILE, and one optional field (END-WEEK). An
input record containing data in INPUT-WEEK and spaces in END-WEEK requests a
printout for that one specific RELATIVE-RECORD; the record is retrieved through
random access. (Random processing is a method of processing in which records
can be read from, written to, or removed from a file in an order requested by the
program that is using them.) An input record containing data in both INPUT-WEEK
and END-WEEK requests a printout of all the RELATIVE-FILE records within the RELA-
TIVE KEY range of INPUT-WEEK through END-WEEK inclusive. These records are
retrieved through sequential access.
First, the SORT statement for current sales is executed. The input procedure for
this sorting operation is SCREEN-DEPT. The records are sorted in ascending
order of department, and within each department, in descending order of net sales.
The output for this sort is then printed.
After the sorting operation is completed, the current sales records are merged with
the year-to-date sales records. The records in this file are merged in ascending
order of department number and, within each department, in ascending order of
employee numbers, and, for each employee, in ascending order of months to
create an updated year-to-date master file.
When the merging process finishes, the updated year-to-date master file is printed.
1 File is open
2 File is locked
3 End of file
4 (Reserved)
5 Optional file
6 Check indexed file for duplicates at open
7 End of page
8 (Reserved).
.F/ Previous status code.
.G/ Beginning of Module Global Table (MGT).3
.H/ Last exception code.
.I/ Invocation number of current program.
.J/ Qualified program name and library.
.K/ Beginning of the Program Global Table (PGT).4
.L/ Invocation number of the main COBOL program.
.M/ Job date (YYMMDD).
.N/ Beginning of user fields.
.O/ Invalid zoned field printed in hexadecimal.
3 The Module Global Table (MGT) defines a common area for the module. The table is used to pass information to run-time
subroutines.
4 The Program Global Table (PGT) is a communication area for the entire COBOL run unit. There is only one PGT for the run unit.
MCH12ð2 exception in program XMPLDUMP in QTEMP at MI instruction number ðð5C COBOL statement number 51..A/
Last I-O operation was at statement 48..B/
LBE79ð3-Information pertaining to file FILE-1..C/
LBE79ð5-File is open.
LBE79ð6-Last I-O operation completed for file was READ.
LBE79ð7-Last file status for file was ð4.
LBE791ð-Last extended file status for file was.
Index 391
compiler options (continued) compiler options (continued)
*DUPKEYCHK 22 *NORANGE 22
*EXCLUDE 27 *NOSECLVL 20
*EXTACCDSP 23 *NOSEG 25
file-name option 24 *NOSEQUENCE 19
*FLAG 25, 37 *NOSOURCE 19
*FS21DUPKY 23 *NOSRCDBG 20
*GEN 19 *NOSTDERR 22
*GRAPHIC option 24 *NOSTDINZ 23
*HIGH 25 *NOSYNC 22
include attributes for the IRP 21 *NOUNDSPCHR 25
*INTERMEDIATE 25 *NOUNREF 22
*INZDLT 23 *NOVARCHAR 23
*LIBCRTAUT 27 *NOVBSUM 19
*LIBL 18, 24 *NOXREF 19, 21
library-name option 18, 25 *NUMBER 19
*LINENUMBER 20 *OBSOLETE 25
*LIST 21 *OPTIMIZE 22
list compiler options in effect 37, 41 optimizing source code 22
*LSTDBG 21 *OPTIONS 20, 37
*MAP 20, 37 overview 6
maximum-severity-level option 24 *OWNER 26
message-limit option parameters of the CRTCBLPGM
*MINIMUM 25 command 18—31
*NOATR 21 *PATCH 21
*NOBLK 23 *PGM 18
*NOCRTF 22 *PGMID 18
*NODATETIME option 24 *PRINT 21
*NODDSFILLER 22 PROCESS statement, using to specify 32
*NODEB 25 program listings, DBCS characters in 349
*NODFRWRT 25 program-name 18
*NODUMP 21 *PRTCORR 20
*NODUPKEYCHK 22 *PRV 26, 31
*NOEXTACCDSP 23 QLBLSRC (default source file) 18
*NOFIPS 25 QSYSPRT (default printer file) option 24
*NOFLAG 25 *QUOTE 20
*NOFS21DUPKY 23 *RANGE 21
*NOGEN 19 release-level option 26, 31
*NOINZDLT 23 *SECLVL 20
*NOLIST 21 *SEG1 25
*NOLSTDBG 21 *SEG2 25
*NOMAP 20 *SEQUENCE 19
*NOMAX 24 severity-level option 19, 26
*NONUMBER 19 *SOURCE 18, 19, 37
*NOOBSOLETE 25 source-file-member-name option 19
*NOOPTIMIZE 22 source-file-name option 18
*NOOPTIONS 20 specifying
*NOPATCH 21 *SRCDBG 20
*NOPRINT 21 *SRCMBRTXT 19
*NOPRTCORR 20 *STDERR 23
Index 393
Create Authorization List (CRTAUTL) CVTOPT parameter 23, 34
command 27
Create COBOL Program (CRTCBLPGM)
command
D
data area
AUT parameter 27
description 305
CVTOPT parameter 23, 34
local 305
description of 6
PIP 306
DUMP parameter 27
data class type (TYPE) field 45
entering from CL program 28
data communications file 139, 172
entering from command line 28
data description entry for Boolean data 144
EXTDSPOPT parameter 35
data description specifications (DDS)
FLAG parameter 26, 35
command attention (CA) keys 140
FLAGSTD parameter 25, 35, 37
CONCAT keyword 122
GENLVL parameter 19, 32
Create File commands 105
GENOPT parameter 21, 34
date fields 132
ITDUMP (n) parameter 27
DD option, description 113
MSGLMT parameter 24
DDR option, description 113
OPTION parameter 19, 33, 37
DDS option, description 113
parameters, description of 18—31
DDSR option, description 113
PGM parameter 18
definition 140
prompt displays, using 16
description 106
PRTFILE parameter 24
display management 140
REPLACE parameter 26
examples
SAAFLAG parameter 25, 35, 37
CONCAT keyword 122
SRCFILE parameter 18
for a display device file 141
SRCMBR parameter 18
for field reference file 107
syntax of 29
for subfile record format 159, 161
TEXT parameter 19
formats, data structures generated by 204
TGTRLS parameter 26
key generation 121
USRPRF parameter 26
keyed access path for an indexed file 247
creating files
RENAME keyword 124
indexed files 351, 356
specifications for a database file 110
relative files 351, 361
specifying a record format 109
sequential files 351
SST keyword 126
cross-reference listing
work station programs 200, 231
and breakpoints 57
externally described files 104, 242
CRTCBLPGM options 19, 21
FORMATFILE files 234
description of listing 48
function keys 140
example 47
function of 140
testing, using in 61
graphic data fields 133
CRTAUTL (Create Authorization List)
incorporate description in program 108
command 27
key fields 242
CRTCBLPGM command
multiple device files 162
See Create COBOL Program command
program-described files 104
*CRTF option 22
RENAME keyword 124
*CURLIB option 18, 25
SAA fields 132
*CURRENT option 26, 31
SST keyword 126
Customer Information Control System (CICS)
subfiles 156
statements 13
suffixes 123
time fields 132
Index 395
designing your program 9 divisions of programs (continued)
destination of compiler output 36 Environment Division 171, 310, 311, 340
device control information 142 Identification Division 10
device dependence 89 optional 10
examples 90 Procedure Division 176, 311, 343—348
device files required 10
and I/O 89 do while structure, testing for end of chained
DATABASE file considerations 241 list 304
DISK file considerations 241 double spacing 38
multiple 162 double-byte character set (DBCS)
single 162 support 337—350
device independence 89 ACCEPT statement 343
*DFRWRT option 25 and alphanumeric data 346
diagnostic levels 330 checking 339
diagnostic messages 48 comments with DBCS characters 340
diagrams, syntax 29 communications between programs 349
direct files definition 386
See relative files enabling in COBOL programs 337
disclaimers graphic 348
examples in the Data Division 341
patents ix in the Environment Division 340
sending information to IBM in the Identification Division 340
US government users in the Procedure Division 343—348
disk files 241 open 348
processing methods 252 PROCESS statement 337, 345
displacement (DISP) field 45 representation of DBCS data in batch
display device jobs 348
DDS for 140 searching for in a table 348
record format 140, 141 sorting 348
display device file 140 specifying DBCS literals 337, 338
display format data, definition 140 DROP statement 179
DISPLAY statement 344 DSPTRCDTA (Display Trace Data) command 65
Display Trace Data (DSPTRCDTA) command 65 *DUMP option 21
displaying a compiler listing 39 DUMP parameter for CRTCBLPGM command 27
displays dump, formatted 371
CRTCBLPGM prompt display 17 *DUPKEYCHK option 22, 270
data description specifications (DDS) for 140 duplication errors 258
display program messages 328 dynamic access mode 158, 173, 249, 253
ENDCBLDBG prompt display 315 dynamic file creation 22
for sample programs dynamic processing, definition 173
order inquiry 216, 217
payment update 228, 229, 230
transaction inquiry 205
E
EBCDIC character, definition 387
SEU display messages 327
editing source programs 9
STRCBLDBG prompt display 314
subfiles 157
See also source entry utility (SEU)
efficiency considerations 268
distributed data management (DDM) 387
efficiency, increased 22
DIVIDE statement 336
eight-byte binary items, and performance 268
divisions of programs
Data Division 20, 173, 175, 341
Index 397
exceptions 16, 52, 71, 81 Federal Information Processing Standard (FIPS)
*EXCLUDE option 27 (continued)
exclusive-allow-read lock state 93 standards to which the compiler adheres xiii
EXIT PROGRAM statement 274, 306 with DBCS characters 349
expressions 264, 343 FIB (file information block) 71
*EXTACCDSP option 23 field names
EXTDSPOPT parameter of the CRTCBLPGM -DDS added to 123, 125
command 35 additional notes 127
EXTEND mode, definition 93 construction of 116
extended ACCEPT and DISPLAY statements 23 fields
extensions, IBM attributes
double-byte character set (DBCS) BLANK WHEN ZERO 260
support 337—350 defaults 260
flagging 25, 331 SIGN IS TRAILING 260
format, indication in syntax 5 USAGE IS DISPLAY 260
GOBACK BLANK WHEN ZERO attribute 260
overview 1 date 132
reading 5 fixed length 132
transaction files 139—231 floating-point 127
extensions, list of 1 null-capable 133
external description time 132
adding functions to 130 time separator 38
overriding functions to 130 timestamp 132
external file status 70 variable-length 131
externally described files 113, 236 character 131
adding functions 130 graphic 131, 134
advantages of using for printer files 234 length of, example 132
and COPY statement, DD, DDR, DDS, DDSR maximum length 131
format 119 restrictions 131
considerations for using 105 figurative constant QUOTE 20
DDS for 108 figurative constant, NULL 286
description 104 file and record locking 93, 95
level checking 130 file boundaries 251
overriding functions 130 file considerations 89, 241, 306
printer files, specifying with FORMATFILE 234 file control entry 89
EXTERNALLY-DESCRIBED-KEY 242 of Environment Division 171
externally described TRANSACTION TRANSACTION file processing entry 171
files 139—142 file descriptions 108, 175
file information block (FIB) 71
file locking 93
F file-name option 24
failed I/O and record locking 94
file operations for printer file 233
failure of compiler 16
file organization 250
Federal Information Processing Standard (FIPS)
file processing
1986 COBOL standard 331
See files
description 331
file redirection 90, 92
flagging deviations from 25, 331, 349
file status
FLAGSTD parameter 25, 46
0Q 251
messages 46, 329, 331
9N 83
options 25
9Q 251
standard modules 331
Index 399
Grant Object Authority (GRTOBJAUT) indexed files, definition 356
command 27 indexed I-O module 324
graphic data types 133 indicator structures 117
restrictions 133 indicators
*GRAPHIC option 24 and ASSIGN clause 143
group level names 116 and Boolean data items 144
group structures, aligning pointers within 284 and COPY statement 114, 118
GRTOBJAUT (Grant Object Authority) associated with command keys 140
command 27 data description entries 144
description 115, 142
example, using in programs 146
H in a separate indicator area 143, 145, 270
handling data errors, de-editing 267
in the record area 143, 146
*HIGH option 25
INDARA DDS keyword 143
highlights 2, 351
INDICATOR clause 145
hyphen, produced when copying ALIAS
INDICATORS phrase 145
names 113
performance considerations 270
sample programs 146
I special considerations for 144
I/O formats 118 structures 116
IBM extensions TRANSACTION file processing 142
double-byte character set (DBCS) using 144
support 337—350 industry standards xiii
flagging 25, 331 initialization of storage 279
format, indication in syntax 5 initializing files with deleted records 251
GOBACK initializing pointers 286
overview 1 with NULL figurative constant 286
reading 5 input field 140, 189
transaction files 139—231 input records 102
ICF input spool 91, 92
See intersystem communications function input verbs, processing of
Identification Division since Version 1, Release 3 80
and DBCS characters 340 Input-Output formats 118
description 10 input-output verbs, processing of
identifier since Version 1, Release 3 80
call by 282 INSPECT statement 345
defining in Working-Storage section 258 inter-program module 324
unreferenced 22 *INTERMEDIATE option 25
increasing efficiency 22 intermediate representation of program (IRP)
INDARA keyword 118 cross-reference listing 21
independence, device 89 how to list 21
independent segments 309 how to list attributes 21
indexed files how to use 57
creation 351, 356 sample listing 62
description 241 internal file status 70
key fields 241 internal name (I-NAME) field 45
processing methods for types DISK and DATA- internal size limits 15
BASE 241 International Standards Organization (ISO) xiii
updating 351, 357 interprogram calls using pointers 289
Index 401
listings (continued) messages (continued)
messages (continued) interactive 327
example 48 responding to in an interactive
from COBOL/400 compiler 329 environment 329
minimum record length 24 run-time 328
options 40 and standard error handling 69
scanning for syntax errors 39 SAA, flagged 47
specifying output file for 24 severity levels 19, 24, 330
verb usage by count 19, 43 statistics 49
literals, DBCS 338—340, 348 types 327
literals, delimiting 20 methodology for entering programs 9
local data area (LDA), definition 305 migrating
lock level ANSI 74 COBOL programs 335
(*CS), under commitment control 95 to ANSI 85 COBOL 335
high, under commitment control 95 to COBOL/400 language 335
low, under commitment control 95 *MINIMUM option 25
lock state 93 mismatched records, reducing occurrence 281
locking, file and record 93 module global table (MGT), definition 371
logic of segmentation 310 Monitor Message (MONMSG) command 16
logical file considerations 246 monitoring exceptions 16
logical operators 2 monitoring operations
looking at a compiler listing monitors, message 73
See source entry utility (SEU) MONMSG (Monitor Message) command 16
loops in a program 271 MOVE statement 319, 346
*LSTDBG option 21 CORRESPONDING phrase 256
using pointers 287
MSGID and severity level field 49
M MSGLMT parameter 24
main program, description 273
multiple contiguous key fields 242
major/minor return codes 75
multiple device files 162—170, 178, 184, 190
*MAP option 20, 37
multiple members 92
maximum record length, dynamically created
files 22
maximum-severity-level option 24 N
maximum source statement length 11, 12 name, assignment 89, 143, 172, 341
member type names defined when GENOPT(*NOUNREF) spec-
See source member type ified 15
members 92 NAMES field 48
memory management NEXT MODIFIED phrase 189
See segmentation NO DATA phrase 186
MERGE statement 312, 335, 348, 368 role since Version 1, Release 3 80
message files 331 NO LOCK phrase, and performance 94, 270
message-limit option 24 NO REWIND phrase 336
message monitor generation 73 *NOATR option 21
messages *NOBLK option 23
Application Development Tools 327 *NOCRTF option 22
compilation 329 *NODATETIME option 24
compile-time 327 *NODDSFILLER option 22
diagnostic 48 *NODEB option 25
field on diagnostic messages listing 49
FIPS 329
Index 403
order of clauses 3 passing data item and its length 280
ORGANIZATION clause 172 *PATCH option 21
ORGANIZATION IS INDEXED clause 241 PERFORM statement 312, 336
OS/400 operating system performance considerations 268
and messages 331 I/O operations 102
breakpoint commands 57 permanent segment 309
device control information 142 *PGM option 18
device independence and device PGM parameter for CRTCBLPGM command 18
dependence 89 *PGMID option 18
functions for debugging 55 phrases
input/output 142 ADVANCING 233
internal size limits 15 ADVANCING PAGE 336
object names 16 AT END 187, 190
security, maintaining while testing 55 CORRESPONDING 20
testing, functions for 55 END-OF-PAGE 336
output END-REWRITE 192
compiler 37 END-WRITE 199
compiler, displaying 39 FOOTING 336
output field 140 FORMAT 181, 186, 189, 191
output file, definition 351 GIVING 335, 336
output spool 91 INDICATORS 145, 181
output verbs, processing of INTO 186, 335
since Version 1, Release 3 80 INVALID KEY 190, 192, 199
Override Message File (OVRMSGF) NEXT MODIFIED 189
command 331 NO DATA 186
Override to Diskette File (OVRDKTF) NO REWIND 336
command 90 NOT AT END 187, 190
overriding messages 331 NOT INVALID KEY 190, 192, 199
overriding program-specified files 92 REEL/UNIT 336
overview 6 RELATIVE KEY 335
OVRDKTF command 90 REMAINDER 336
OVRMSGF command 331 ROLLING 195
*OWNER option 26 STARTING 194
SUBFILE 182
TERMINAL 182, 187, 190, 192, 193, 198
P USING 335
packed decimal items 268
PICTURE clause 267, 342
paper positioning 233
and performance 268
parameters of CRTCBLPGM command 18
defining with LIKE clause 258
See also Create COBOL Program PICTURE definitions 116
(CRTCBLPGM) command
PIP (program initialization parameters) data
parameters, describing in the called program 280
area 306
partial key, referring to 242
description 306
parts of a COBOL program
pointer alignment, definition 283
See program structure pointer data items
parts of a program 9
definition 282
passing addresses between programs 303
elementary items 287
passing data 279
pointers
in groups 281
aligning on boundaries
01-level items 284
77-level items 284
Index 405
processing of I/O verbs program termination (continued)
since Version 1, Release 3 80 with the CANCEL statement 336
program control program variables
returning 274 changing 63
transferring 273 pointers 63
program-described files program-defined key fields 246
considerations for using 105 programming considerations 255
description 104 programming notes
externally described by DDS with Create File number of entries in Object Definition Table
commands 104 (ODT) 15, 22
TRANSACTION files 139 prompts, using SEU
program global table (PGT), definition 371 See source entry utility
program initialization parameters (PIP) data area *PRTCORR option 20
See PIP data area example listing 256
program listings, DBCS characters in 349 PRTFILE parameter for CRTCBLPGM
program loops 271 command 24
program-name 18 *PRV option 26, 31
program object punctuation 2
compiler options, specifying 21 purpose of this manual xi
optimizing, specifying at compile-time 22
output from compiler 15
specifying authority to 27
Q
QCMDEXC, using in a program 28, 255
subscript range checking 21
QLBLMSG compile-time message file 331
program parts 9
QLBLMSGE run-time message file 331
program patch area 21
QLBLSRC (default source file) 10, 18
program segments 309
QLRCHGCM API 70
program size 22
QLRRTVCE API 70
program stack, definition 273
QLRSETCE API 53, 70
program structure
QRLMAIN
Data Division 175
MGTFUNC 269
Data Division map 44
QSYSPRT (default printer file) option 24
data field 116
quadruple spacing 38
Environment Division 171
*QUOTE option 20
example 9, 10
QUOTE, figurative constant, value of 20
format (record) level 115
Identification Division 10
indicator 116, 117 R
level of language support 325 random processing, definition 365
Procedure Division 176 *RANGE option 21
required and optional divisions 10 reference modification 262
skeleton program 9 READ statement 344
program syntax, debugging line 321 changes in the use of ANSI 74 COBOL 335
program template 21 description 182
program termination format, nonsubfile 186—187
abnormal 52 format, subfile 189—190
and the CALL statement 312 indicators 145, 146
file considerations 273 processing facilities 181—182
initialization 279 FORMAT phrase 181
returning control 274
STOP RUN statement 274
Index 407
reusing deleted records SAA flagging 47, 333
indexed files 242 SAAFLAG parameter for CRTCBLPGM
relative files 249 command 25, 35
sequential files 250 screens
Revoke Object Authority (RVKOBJAUT) See displays
command 27 SEARCH statement 348
REWRITE statement searching DBCS characters in a table 348
and DBCS 344 *SECLVL option 20
description 191 SECTION field 45
for program-described transaction files 191 security
for TRANSACTION file 191 maintaining while testing 55
format 191, 192 specifying authority to object program 27
indicators 145, 146 *SEG1 option 25
processing facilities 181, 182 *SEG2 option 25
ROLLBACK statement 95 SEGMENT-LIMIT clause 310
boundary 95 segment-numbers 309—311
ROLLING phrase 195 segmentation 268, 309—312, 325, 368
run time segmented program 309
common errors 56 SELECT statement,
debugging 67, 314 EXTERNALLY-DESCRIBED-KEY 121
debugging switch 313 separate indicator area (SI) attribute 143
error handling, de-edit 267 sequence
messages 328 combining numbers 20
and standard error handling 69 errors, checking for 19
monitoring exceptions 16 number 10
program termination 52 of records, preserving 250
redirecting files 90 sequence error indicator (S) 43
subscript range checks, specifying 21 *SEQUENCE option 19
switch 67, 314, 315 sequential access mode 23, 173, 187, 189, 249,
run unit 251
definition 36, 273 sequential files
examples creation 249, 351
multiples, running consecutively 276 definition 249
single run unit 274 in COBOL 249
with a shared program 277, 278 updating and extension 351, 353
running COBOL/400 programs sequential I-O module 324
description 51 service marks x
system reply list and reply modes 52 SET statement 346
RVKOBJAUT (Revoke Object Authority) SEU (source entry utility)
command 27 browsing a compiler listing 39
editing source programs 6, 9, 11
entering source programs 6, 9, 11
S errors
S in PICTURE clause 268
coding errors 56
SAA Common Programming Interface (CPI)
common errors 56
support 325
detected by compiler 56
SAA CPI (Common Programming Interface)
listing 48
support 325
messages at run time 328
SAA data types
formats, using 11
prompts and formats 11
Index 409
statement length, maximum 11, 12 storage, initialization of 279
statement number (STMT) field 44, 49 storage, using less 22
statement number, compiler-generated STRCBLDBG (Start COBOL Debug)
(STMT) 43 command 314, 316
statements STRDBG (Start Debug) command 55
ACCEPT 103, 177, 343 STRING statement 346
ACQUIRE 178 STRSEU (Start Source Entry Utility) command 9
ALTER 312 structure, program
arithmetic, in DBCS processing 345 See program structure
breakpoints 57 Structured Query Language (SQL) statements 12
CALL 312 subfield contents, DEBUG-ITEM special
CANCEL 336 register 319
CLOSE 179, 336 subfiles 156—158, 182
COMMIT 95 subprogram 36, 273
compiler output 37 linkage 281
COPY 104, 114, 335, 348 subscript range checking, specifying 21
DISPLAY 344 subscript ranges 21
DIVIDE 336 subscripting 265
DROP 179 substitution character (X’3F’) in data 137
EJECT 38 suffix -DDS
in syntax diagrams 3 added to key field name 123, 125
INSPECT 345 added to reserved word 123, 127
MERGE 312, 335, 348, 368 summary of changes
MOVE 319, 346 changes made in Version 2 Release 1.1
OPEN 180 changes made in Version 2 Release 2
PERFORM 312, 336 support for ANSI X3.23-1985 standard 323
PROCESS 32, 337 suppressing source listing 41
READ 182, 335, 344 suppression of messages 330
RELEASE 348 switch, run-time 67, 314, 315
RETURN 335, 348 symbols used in syntax 3
REWRITE 191, 344 *SYNC option 22
ROLLBACK 95 syntax
SEARCH 348 arrows 3
SET 346 checking, in SEU 11, 12, 39
SKIP 38 checking, unit of 11
SORT 312, 368 debugging lines 321
START 344 diagrams, using 3
START, generic 242 keywords in 2
STOP 348 notation 2
STRING 346 of CRTCBLPGM command 29
UNSTRING 346 optional items 3
USE 199 punctuation 2
WRITE 193, 336, 345 required and optional clauses 3
*STDERR option 22 required items 3
*STDINZ option 23 stacks 3
STOP RUN statement 274, 306 symbols 3
STOP statement 348 system override considerations 92
storage optimization system reply list 52
See segmentation
Index 411
USE FOR DEBUGGING declarative 316, 317
in the Procedure Division 316
W
where DBCS characters can be used 340
using the procedures 317
WITH DEBUGGING MODE switch and compila-
*USE option 27
tion 313
USE procedure
work stations
role since Version 1, Release 3 80
communications between 139
USE statement
sample programs
coded examples 353, 354
order inquiry 206
description 199
payment update 217
EXCEPTION/ERROR for TRANSACTION
transaction inquiry 200
file 199
validity checking 140
format 199
Working-Storage section
user file control block (UFCB) 71
defining identifiers 258
*USER option 26
WRITE statement
user profile 26
and DBCS 345
user program status indicator (UPSI) switch
changes from ANSI 74 COBOL 336
user spaces
description 193
accessing using APIs 291
for program-described transaction files 193
using a subfile for display 156—158
for TRANSACTION file 193
using double-byte characters 337
format, nonsubfile 193—195
using less storage 22
format, subfile 198—199
USING phrase 335
indicators 145, 146
using REPLACING in format 2 COPY
processing facilities 181—182
statement 127
using the COBOL/400 language
See COBOL/400 language X
USRPRF parameter for CRTCBLPGM X’3F’ (substitution character) in data 137
command 26 *XREF option 19, 21, 37
V
V2R1M0 option 31
V2R1M1 option 31
V2R2M0 option 31
valid RECORD KEYS 242
validity checking 140
VALUE clause 342
VALUE IS NULL 304
value of figurative constant QUOTE 20
*VARCHAR option 23
variable-length fields 131
defining 131
example of 131, 134
length of, example of 132
maximum length of 131
restrictions 131
variables, changing values while testing 63
*VBSUM option 19, 37
verbs usage by count listing 43