Changes are periodically made to the information herein; before using this publication in
connection with the operation
of
IBM
systems, be sure you have the latest edition and any
technical newsletters.
This edition applies to version
Compiler and Library (program number 5708-CB1), and the
01, modification 00 of the
IBM
5280 COBOL
IBM
5280
OSjVS
COBOL
Host
DOSjVSE
Host Compiler and Library (program number 5708-CB2), and to all subsequent versions and
modifications until otherwise indicated in new editions or technical newsletters.
Use this publication only for the purposes stated in the section
It
is possible
services
construed to mean
that
that
this material may contain reference to, or information about, programming, or
are not announced in your country. Such·references or information must not be
that
IBM
intends to announce such
"To
The
COBOL Programmer".
IBM
products, programming, or services
in your country.
Publications are not stocked
for technical information about the system should be made to your
at
the address below. Requests for copies of
IBM
publications and
IBM
representative or to the
branch office serving your locality.
This publication could contain technical inaccuracies or typographical errors.
Comment Form
form has been removed, address your comments to
Division, Dept
at
the back of this publication to make comments about this publication.
26Xj037,
2800
Sand
Hill Road, Menlo Park,
IBM
Corporation, Information Systems
CA
94025.
Use the Readers
IBM
may use and
If
the
distribute any of the information you supply in any way it believes appropriate without incurring
any obligation whatever. You may, of course, continue to use the information you supply.
Before using this guide, you should be a ware
experience and knowledge you should have to use it, and the other IBM 5280
and host system manuals
you this information; reading the text
To use this guide, you should be either experienced or trained in the COBOL
language. The guide
learn the COBOL language. (The objectives
section.)
The IBM 5280 host compilers for
programs written in COBOL into load modules executable on an IBM 5280
system.
The information in this guide, together wIth
Language Reference, GL23-0031, should provide you with most
information you need to write COBOL programs and compile them on the
host system.
The guide also provides information on executing a COBOL program
IBM 5280. You will need additional information
5280 publications (in, for example, the Message Manual). A list of these
manuals and their order numbers
you
will need.
that
is
not intended as a tutorial for a beginner wishing to
OS/VS
is
at
of
the topics covered, the
It
is
the purpose of this section to give
follows may save you time.
of
and
that
the end
the guide
DOS/VSE
in the
that
of
this chapter.
are
given in a later
convert source
IBM
5280 COBOL
is
to be found in IBM
of
the
on
the
Organization of
Objectives
of
the
the
Guide
Guide
The information in this guide
program might be coded, compiled, executed, and debugged:
• Chapters 1 through 6 provide rules, guidelines, and examples for writing
transaction
• Chapter 7 provides information on the procedures in the host system for
compiling your source module. This chapter also describes the compiler
options and how to specify them when you compile a program
• Chapter 8 contains 5280 system information relating to the execution
a COBOL program; for example: allocating
COBOL program, error messages issued during execution, factors
affecting performance, etc.
• Chapter 9 describes compiler and language facilities you can use to
debug a program.
Refer to the "Contents" or
The objectives
follow.
I/O,
data
of
the guide and how to use it
is
presented in the order a 5280 COBOL
communications, and printer and other
data
sets, loading a
"Index"
for a more detailed listing
are
given in the sections
of
I/O.
of
topics.
that
iii
Writing A Work Station Application
Three chapters provide information
the 5280 keyboard and other system functions:
• Chapter 1 introduces transaction
(DDS), and the 5280 keyboard. Transaction
formatting and editing capabilities
in
writing applications
on
writing interactive applications using
I/O,
the Data Definition Statements
of
DDS, provide flexibility and ease
that
interact with a work station.
I/O
together with the
Data Communications
Diskette
I/O
• Chapter 2 describes
and gives the detailed rules for coding DDS.
• Chapter 3 describes how to code the COBOL statements for transaction
I/O.
Data can also be written to a work station using a DISPLAY statement or
with
SEQUENTIAL
The exchange
IBM 5280 COBOL programs
covers
data
• A summary
• The IBM 5280 facilities needed to execute a COBOL program
• The coding information necessary to write a
program.
• An example
facilities
Chapter 5 describes
the interchange
covered in this chapter include:
of
data
communications and has the following information:
of
of
of
data
how
to implement your screen designs with DDS
I/O;
these two methods are discussed in Chapter
between two systems over a communications link using
is
called data communications. Chapter 4
COBOL
a COBOL program using the
how
data
communications capabilities
data
communications
data
communications
to write a program using the
between a program and IBM 5280 diskettes. Subjects
I/O
facilities
6.
that
allow
• Sequential, relative, and indexed file organizations, their differences and
uses
• The random and sequential access methods
• Step-by-step guidelines for writing the statements required to process
sequential, relative, and indexed file organizations. The use
sequential and random access, where applicable,
to each
•
I/O
Printer and Other
iv
I/O
Chapter 6 provides information on:
• Writing
• Using the
an operator
• Using
at
of
the file organizations.
error processing options
data
to a printer using
DISPLAY
at
a work station screen and a COBOL program
SEQUENTIAL
a work station and a COBOL program.
and
I/O
SEQUENTIAL
ACCEPT
in the exchange of data between an operator
verbs in exchanging
of
is
discussed in relation
I/O
data
between
Compiling a COBOL Program
Chapter 7 describes the procedures available for compiling a source program;
it also provides information
your installation
the related job control language, and the options available for compilation.
on
the Host System
if
necessary. Information
that
can be used for modifying the procedures
is
given on the
data
sets required,
at
Executing a COBOL Program
on
Chapter 8 provides a guide to loading and executing a COBOL program on
the IBM 5280 system. Subjects covered include:
• Manuals and other documentation required by the operator
• Rules for creating COBOL
• The COBOL-initiated prompts and how to respond to them
• Improving performance
• How to interpret the status line in regards to keyboard, device, and
CORaL
Executing Jobs in Sequence on an
The COBOL job-to-job facility allows you to pass control from your program
to another COBOL program or any other program (for example, a
program, an assembler program, a system utility program, etc.). You achieve
this linkage with a
10.
Together with the
this facility permits you to control linkage among several programs with little
or no operator action.
Debugging COBOL Programs
Chapter 9 discusses procedures and the facilities provided by the compiler and
the COBOL languages for debugging COBOL programs. Coded examples
some
of
an
IBM
5280 System
data
sets
execution errors
IBM
5280 System
CALL
PROMPT
the debugging facilities provided by COBOL
to a COBOL library routine as described in Chapter
/NOPROMPT
option described in
are
included.
DE/RPG
Chapter
7,
of
Related Publications
References for Coding and Debugging COBOL Programs
Coding A ids for Transaction
You should have the following publications available for reference when
preparing and running COBOL applications:
•
IBM
5280 COBOL Language Reference, GL23-0031
•
IBM
5280 COBOL Host Compilers Problem Determination Manual,
SL23-0043
I/O
• Data Description Specifications, GX21-9362 (a pad
•
IBM
Printer/Display Layout, GX21-9174 (a pad
of
coding forms)
of
layout forms)
y
References for Executing a COBOL Program
• IBM 5280 Operator's Guide, GA21-9364
• IBM 5280 Utilities Reference/Operations Manual, SC21-7788
• IBM 5280 System Concepts, GA21-9352
• IBM 5280 Message Manual, GA21-9354
• IBM 5280 Printer Operator's Guide, GA21-9260
• IBM 5280 Communications Reference Manual, SC34-0247
General References for
Compilation Under
Compilation Under
Compilation Under
OS/VSl
OS/VS2
DOS/VSE
IBM
5280 System Information
• IBM 5280 General Information, GA21-9350
• IBM 5280 Planning and
• IBM 5280 Master Index, GA21-9356
• IBM 5280 User's Setup Procedures, GA21-9365
• IBM 5280 Machine Verification Manual, GA21-9357
• IBM 5280
Manual,
•
OS/VS
•
OS/VSl
• OS/VS2 JCL, GC28-0692
•
DOS/VSE
System
GC21-7824
1 JCL Reference, GC24-5099
JCL Services, GC24-5100
System
Site
Preparation Guide, GA21-9351
Control Programming Reference/Operations
Control Statements, GC33-5376
vi
Contents
To the COBOL Programmer iii
Before
Using This Guide iii
Scope of the Guide iii
Organiza tion of the Guide iii
Objectives of the Guide iii
Writing A Work
Station Application
iv
Data Communications
iv
Diskette
I/O
iv
Printer and Other
I/O
iv
Compiling a COBOL Program
on
the Host System v
Executing a
COBOL Program on an IBM 5280 System v
Debugging
COBOL Programs v
Related Publications v
References for Coding and Debugging
COBOL Programs v
Coding Aids for Transaction
I/O
v
References for Executing a COBOL
Program v
General References for IBM
5280 System Information v
Compilation
Under
OS/VSl
vi
Compilation Under
OS/VS2
vi
Compilation Under
DOS/VSE
vi
Chapter
1.
Transaction
I/O
- Introduction
1-1
Defining Display Screens
1-1
Uses of Data Definition Statements
1-1
The Copy Library and Data Definition Statements
1-1
Copying Members
1-2
General Rules for Data Definition Statements
1-2
The COBOL Program and Data Definition Statements 1-2
Steps
in
Writing an Interactive Program
1-2
The Keyboard
1-5
Command and Function Key Codes
1-5
Function Keys
1-7
Attention
1-7
Auto Dup/Skip
1-8
Auto Enter
1-8
Character Advance
1-8
Character Backspace
1-8
Character Delete
1-9
Character Insert
1-9
Cursor Left
1-9
Cursor Right
1-9
Duplicate 1-10
End-of-Job
1-10
Enter/Record Advance 1-10
Field Advance 1-10
Field Backspace 1-10
Field Exit
1-11
Field Exit Minus
1-11
Hexadecimal 1-12
Record Advance 1-12
Record Backspace 1-12
Reset 1-12
Skip 1-12
System Request 1-13
Sequence Number Field (Columns 1 through 5) 2-15
Form Type Field (Column 6) 2-15
Indicator Field (Columns 9 and 10) 2-15
Field
Name
Field (Columns
19
through 24) 2-15
Length Field (Columns
30 through 34) 2-16
Data Type Field (Column 35) 2-16
Decimal
Positions Field (Column 37) 2-18
Usage Field (Column 38) 2-18
Location Field (Columns
39
through 44) 2-20
Editing Field (Columns
45
through 80) 2-21
CHECK
(parameters)
2-21
DSPATR (attributes) 2-22
PMT(message) 2-24
SHIFT(codes) 2-24
Keyword Conflicts and Compatibilities 2-25
Chapter 3. Transaction
I/O
- Writing the COBOL Program
3-1
Summary of COBOL Transaction
I/O
Statements
3-1
FILE-CONTROL
Paragraph
3-1
OPEN
3-2
WRITE
3-2
READ 3-3
Sequence of Transaction
I/O
Statements 3-4
Clearing the
Screen with
WRITE
3-4
CLOSE 3-4
I/O
Error Processing 3-4
Status Key 3-4
Coding the
Status
Key
3-5
Exception/Error
Procedures 3-5
Example
Using Status Key and
ERROR
Procedures 3-5
Return Information 3-5
Attribute Data 3-6
Work
Station Control Area 3-7
Transaction
I/O
Examples 3-7
Example - Interactive Entry and
Processing 3-7
INDICATOR
Example 3-13
Chapter 4. Data Communications Programming With
COBOL
4-1
Uses of Data Communications Programs
4-1
Eligible Systems
4-1
COBOL Programs and the Communications Access Method
4-1
COBOL Program Responsibilities 4-2
System Requirements for Communication Programs 4-2
Before Running a Data Communication
Program 4-2
Writing
COBOL Communication Statements 4-2
Communication Routine
Parameters 4-3
Communication
Program Example - Explanation 4-3
Open Routine 4-3
Close Routine 4-4
Read Routine 4-5
Write Routine 4-6
Communication
Program Example - Listing 4-6
Chapter 5. Diskette Input/Output
5-1
Input-Output Summary
5-1
Contents
vii
File
Organization
and Access Method
5-1
Sequential
Organization
5-2
Relative
Organization
5-3
Indexed
Organization
5-3
Record
Formatting
5-3
FILE-CONTROL
Paragraph
5-4
FD
Entry -VALUE
OF
OWNER-ID
Clause
5-5
Sharing
Files 5-5
Unshared
Files 5-5
Shared
Files 5-5
When
Files
Can
Be
Shared
5-6
No
Sharing
with
OUTPUT
and
EXTEND
Modes 5-6
I/O
Error
Processing 5-6
Status
Key 5-7
EXCEPTION/ERROR
Procedures 5-7
The
INVALID
KEY
Clause 5-8
The
AT
END
Clause 5-9
Error
Handling
Considerations 5-9
Permanent
I/O
Errors 5-10
Processing
Files with Sequential File
Organization
5-11
ASCII
File Processing 5-11
Creating
a Sequential File 5-11
Reading
from a
Sequential
File 5-11
Updating
a Sequential File 5-12
Multivolume Record
Processing 5-12
Example
5-13
Processing Files with a Relative
Organization
5-15
Creating
a Relative File 5-15
Contents
of
Relative Key 5-16
Example -Creating
a Relative File 5-16
Reading
from a Relative File 5-18
Updating
a Relative File 5-18
Example
- Reading
and
Updating
a Relative File 5-18
Processing Files with
an
Indexed
Organization
5-21
I
Two Types
of
Indexed Files 5-21
FILE-CONTROL
Paragraph
for Indexed Organization 5-22
Rules
and
Considerations for Index
Data
Sets 5-23
Adding
Records To Indexed Files 5-24
Creating
an
Indexed File 5-25
Example
5-25
Reading
an Indexed File 5-27
Updating
an
Indexed File 5-28
Chapter
6.
Other
I/O.
6-1
Printer
I/O
6-1
Example
of
Printer
I/O
Statements
6-1
DISPLAY
and
ACCEPT
6-2
Example
of
DISPLAY
6-3
SEQUENTIAL
Work
Station
I/O
6-4
Work
Station
I/O
with
Sequential
I/O
- Example 6-5
STOP
Statement
6-6
Chapter
7. Compiler
Job
Procedures and Options
7-1
inter-Program
Communications and Multiple-Compilations
7-1
A
Note
on Compiler Options 7-1
OS/VS
Compilation 7-3
DOS/VSE
Compilation 7-5
Compiler
Storage
Requirements 7-6
Multiple
Compilations -
The
*PROCESS
Statement
7-7
When
Using
Subprogram
Linkage 7-7
With
Segmented Programs 7-7
Maximum
Number
of
Programs 7-7
Format
and
Rules -
*PROCESS
7-7
Host
Compiler Options 7-9
Defaults
and
Overrides 7-9
CMPAT(SIGNC
or
SIGNF)
7-10
DECK
or
NODECK
- D or
NOD
7-10
FIPS
or
NOFIPS
7-11
viii IBM
5280
COBOL
Programmer's
Guide
FLAG
or
NOFLAG
7-11
FI
tISHFR
R 7-11
GONUMBER
or
NOGONUMBER -GN
or
NOGN
7-12
LINECOUNT
(n) -
LC(n)
7-12
LIST
or
NOLIST
7-12
MAP
or
NO
MAP
7-12
NUMBER
or
NONUMBER -NUM
or
NONUM
7-13
OBJECT
or
NOOBJECT -OBJ
or
NOOBJ
7-13
OFFSET
or
NOOFFSET -OFF
or
NOOF
7-14
OPTIONS
or
NOOPTIONS -OPTN
or
NOOPTN
7-14
PRINT
or
NOPRINT
7-14
PROMPT
or
NOPROMPT
7-14
QUOTE
or
APOST
7-15
RUNMSG
(n) 7-15
SEQUENCE
or
NOSEQUENCE -SEQ
or
NOSEQ
7-15
SOURCE
or
NOSOURCE
- S
or
NOS
7-16
STMT
or
NOSTMT
7-17
XREF
or
NOXREF
- X
or
NOX
7-17
Chapter
8. Guide for COBOL
Program
Execution
8-1
Manuals
and
Documentation
Needed
by the
Operator
8-1
Transferring
the Load Module from
the
Host
to
IBM
5280
8-1
I Remote Job
Entry
Subsystems 8-3
Storage
Required for
Object
Programs 8-3
Storage
Required on Diskette 8-3
Main
Storage
Required for Execution 8-3
If
A
Program
Is Too
Large
8-4
Allocating
Data
Sets for
Object
Programs
8-4
When
Programs
Are
Segmented
8-4
Allocating
Data
Sets for
Program
Files 8-4
Initializing Diskettes 8-4
Allocating
Data
Sets 8-5
Specifying a Multivolume Indicator 8-5
Determining Exchange Type 8-5
Record
Size 8-6
Number
of
Records for Indexed Files 8-6
Delete
Character
8-6
Improving
Performance 8-7
System
Considerations 8-7
Improved Performance with Sequential Access Method 8-7
Improved Performance when
Creating
Indexed Files 8-7
Improved Performance with
SIZE
Clause 8-7
Loading
the
COBOL
Program
and
Responding to Prompts 8-7
Prompts for Loading a
COBOL
Program
8-8
Prompts
for
Run-Time
Options 8-8
Prompts
for Diskette Files 8-9
Prompts for
Printer
Files 8-9
The
Status
Line
and
Error
Messages 8-11
Device Errors 8-12
COBOL
Execution Errors 8-12
Chapter
9. Debugging
9-1
Compiier Messages 9-i
Types
of
Messages 9-1
Acting
Upon Compiler Messages 9-2
Compiler Abends 9-2
Abnormal Termination
and
SYSDOVL
9-3
Messages
at
Execution 9-3
Possible
Causes
of
Execution Errors 9-3
Debugging Language 9-4
Debugging
Lines··
WITH
DEBUGGING
MODE
9-4
Declarative
Procedures -
USE
FOR
DEBUGGING
9-4
Example -
COBOL
Debugging
Language
9-4
Chapter
10.
Job-to-Job
Facility
COBOL
Statements
Required 10-1
When
Using the Job-to-Job Facility 10-2
Appendix
Before Running a
Functions Supported A-I
TIN
TTERM
TOPEN
TCLOZ
TREAD
TWRT
TCTL
A.
Direct Communications Support
Data
IT
Routine A-2
Routine A-3
Routine A-3
Routine A-3
Routine A-4
Routine A-4
Routine A-5
Communication Program A-I
A-I
Status
Appendix B.
Appendix C. Compiler Limitations
Appendix D. Compiler Return Codes D-I
Appendix E.
Appendix F.
Index
X-I
Key Return Codes
Storage
Estimates for
Storage
Estimates for
C-I
OSjVS
DOSjVSE
B-1
E-I
F-I
Contents
ix
x
IBM
5280
COBOL
Programmer's
Guide
Figures
Figure 1.1. Steps
Figure 1.2 The data entry keyboard
in
preparing and compiling display screen formats
1-5
1-3
Figure 1.3. COBOL command keys and codes for data entry keyboards 1-6
Figure 1.4.
Figure 2.1. Sample form used
COBOL command keys and codes for typewriter keyboards 1-6
by
data entry operator
2-1
Figure 2.2. Printer/Display Layout form 2-2
Figure 2.3 Data Definition Statements Coding Example 2-4
Figure 2.4 Data Definition Statements as compiled by the
COBOL compiler 2-4
Figure 2.5. Data Definition Statements Coding Example 2-6
Figure 2.6. Attributes that can be specified with the DSPATR keyword 2-23
Figure 2.7 Keyboard conflicts and compatibilities 2-7
Figure 3.1. Explanation of values returned in the ATTRIBUTE-DATA area 3-6
Figure 3.2. Example of transaction
I/O
statements
3-8
Figure 3.3. Example of indicators and conditional bypass 3-14
Figure 4.1. The
Figure 4.2. Return codes from the
Figure 4.3.
COBOL library routines that perform data Communications 4-3
COBOL communication library routines 4-4
Options available with the Close routine 4-5
Figure 4.4. Coding example: data communications 4-7
Figure 5.1. Valid combinations of
Figure 5.2.
Figure 5.3.
COBOL statements for Status Key and
COBOL statement execution with
SHARE/SHARER
EXCEPTION/ERROR
AT
END
and
and
OPEN
modes 5-6
INVALID
routine 5
KEY 5-9
Figure 5.4. Statements used with sequential file organizations 5-11
Figure 5.5. Example of processing files with a sequential organization 5-13
Figure 5.6. Statements used with relative file organizations 5-15
Figure 5.7. Creating a relative file 5-17
Figure 5.8. Example of processing files with a relative organization 5-19
Figure 5.9. Statements used with indexed file organizations
5-21
Figure 5.10. Creating an indexed file - without index data set 5-23
Figure 5.11. Creating an indexed file - with index
data
set 5-23
Figure 5.12. Updating an indexed file 5-24
Figure 6.1. Example of
Figure 6.2. Example of statements used for DISPLAY
Figure 6.3. Example of statements used for sequential
Figure
7.1
Job Control Procedure for the 5280 COBOL
COBOL statements used for printer
6-3
I/O
OS/VS
I/O
6-2
to a work station
compiler
7-3
6-6
Figure 7.2. Required parameter for allocating COBOL data sets 7-4
Figure 7.3 Example of using a
Figure 7.4. Sample job control statements for a
Figure 7.5 List of options available
Figure 7.6. Sample listing with
Figure 7.7. Sample listing with
COBOL compile procedure 7-4
at
compilation 7-10
MAP
option 7-12
OPTIONS
DOS/VSE
specified 7-13
compilation
7-5
Figure 7.8. Sample listing - source program 7-15
Figure 7.9. Sample listing with - Data Definition Statements 7-16
Figure
Figure 8.1. Possible methods of
Figure 8.2. Layout of
7.10. Sample listing with
5280 screen information 8-10
XREF
specified 7-17
host-5280 data exchange 8-2
Figure 9.1. Coding example with COBOL debugging language 9-6
Figures
xi
xii IBM 5280
COBOL
Programmer's Guide
Chapter 1. Transaction
I/O
-Introduction
Transaction
writing
chapter
followed in writing transaction
• Statements used to define display screens and what they can
• How the statements are compiled with the COBOL source program
• Steps to follow in writing an interactive application
• A summary of the 5280 keyboard and
Defining Display Screens
The statements which you code to define display screens are called Data
Definition Statements
consist of one
description statements.
Uses
of
Data Definition Statements
Here are some examples
Statements:
• Define the layout of the screen: the position of the fields
I/O
is an IBM extension to COBOL
data
to and reading data from a display screen. The purpose
is
to introduce transaction
formatting the screen and editing data entered by an operator
with your
COBOL program
(DDS). The Data Definition Statements for a screen
I/O
and provide some rules
I/O
applications. Subjects covered include:
record description statement followed by one or more
of
what you can do with the Data Definition
if
appear on the screen, the data,
how the characters appear on the screen (highlight, blink, reverse image,
underline, nondisplay, and column separators).
any,
that
gives flexibility in
how
some of the keys interact
that
is
to appear in the fields, and
that
that
of
must be
do
in
field
are to
this
The Copy Library and Data Definition Statements
• Cause the data to be edited as the operator enters it. For example, you
so
that
can define a field
the operator tries to enter a numeric, the keyboard will lock and an error
code will be displayed.
• Set the shift key on a character-by-character basis,
either to the lower symbol or to the upper symbol automatically as the
cursor enters each position in the field
The coded Data Definition Statements must be library text in a COBOL
library.
and converts them into
The
for defining the library for each of the host compilers are given
At
compilation, the COBOL compiler brings them into your program
COBOL library
COBOL source statements.
is
allocated by the facilities of the host system. The rules
only alphabetic characters can be entered.
so
that
it shifts
in
Chapter
Chapter
1.
Transaction
I/O
- Introduction
If
7.
1-
1
Copying Members
You must code a
COpy
verb, specifying the name
of
the library text,
at
an
appropriate point
in
the
Data
Division
of
your
COBOL
program.
At
compilation, the compiler creates a record definition for each set
of
Data
Definition Statements: for each record description statement, the compiler
creates an
01
level group item; and, with certain exceptions, for each field
description statement, it creates a
02 level data-item, as shown in figure 2.4
in
Chapter
2.
In writing and reading information from the work station screen, you
refer to the record definitions created from the
Data
Definition Statements
in
associated
READ
and
WRITE
statements. This
is
shown
in
Chapter
3 in
figure 3.2.
General Rules
for
Data Definition Statements
Here
are
some guidelines and rules for preparing
Data
Definition Statements
and entering
them
in a
COBOL
library:
1.
You must prepare a record description statement, followed
by
at
least one
field description statement, for each screen image.
2.
Some
of
the
specifications you make in the record description statement
can be taken as defaults by
the
field description statements
that
follow it.
That
is,
if
you write these items in a record description statement, you
needn't write
them
in a field description statement.
3.
Keep the record description statement and subsequent field description
statement(s) for each screen image entirely within one library text.
4.
If
desirable, enter sets
of
data
definition statements for multiple screen
images within
the
same library text.
The
COBOL
Program and Data Definition Statements
The
COBOL
program treats all
the
information passed to it from one
DDS-defined screen format as a single record.
You can specify two kinds
of
fields:
• An
output
field (O-field) contains information
that
cannot be changed
by
the
operator. For a normal output operation,
the
data
in the field
is
supplied in the field description statement as a constant
• An
input/output
field (B-field) is both displayed (output) on the display
screen
and
read (input) back into the program. The operator
can
enter
new
data
over
the
data
that
is displayed by the program. This
data
can
then be read back into the program.
Both types
of
fields
can
be used in the same display screen formats.
By
your entry in
the
field definition statement, you can also control how
the
data-items are defined in your program: either aiphanumeric or numeric,
signed or unsigned.
Steps in Writing an Interactive Program
The
recommended steps in writing an interactive program, shown in figure
1.1, are:
1.
Design
the
screen layouts which the operator
is
to interact with. Display
screen layout sheets and coding forms
are
available to aid you in this task.
Their order numbers
are
given in the first section
of
this book; their use
is
illustrated in the examples in
Chapter
2.
1-
2 IBM 5280 COBOL Programmer's Guide
Layout
Sheet
1.
Arrange fields
GX21-9174)
screen.
on
just
as
the
layout
they
will
sheet
appear
(order
on
the
number
display
Coding
DDS
Form
Compiler
COBOL
COBOL
Source
Program
Source listing. Contents determined
by the options specified at
compilation
include:
• Source statements,
• DDS
•
•
(see
Chapter 7).
generated code
code,
if
present
Diagnostic
Maps
messages
and cross-reference list
and
with
COpy
Can
DDS-
Librarv
2.
3.
4.
5.
the
Use
out
completed
the
DDS
GX21-9362).
Enter
the
DDS
Code
source
as
appropriate.
Compile
the
layout
coding
sheet
in
a COBOL library.
program;
source
Enter
write
the
program.
sheet
as a guide
(order
COpy
COBOL
number
DDS
source
for
filling
statements
program.
Object
Module
Figure 1.1. Steps in preparing and compiling display screen formats
Chapter
1.
Transaction
I/O
- Introduction
1-
3
2.
Define
the
COBOL
in
detail in
3.
Code the
Information on
given in
4.
Compile
procedures
screens with
Data
Definition Statements, placing them in a
library. The rules for coding
Chapter
COBOL
Chapter
the
program. Information
is
2.
source program
the
COBOL
3.
given in
Chapter
that
statements
7.
data
definition statements
is
to read and write the screens.
that
perform transaction
on
compiler options and host
are
I/O
job
given
is
1-
4 IBM 5280 COBOL Programmer's Guide
The
Keyboard
The
Keyboard
This section describes the function and command keys, and their interaction
with
COBOL
primarily for the
explanation
Guide.
Figure 1.2 shows a
The relative positions of most
with IBM 5280,
description of all keyboards, see the
For descriptive purposes, the keys can be classified as data keys,junction
keys, and command keys.
•
Data
COBOL
• Function keys, when pressed, cause the
action.
• Command keys, when pressed, give control to your
code showing which key was pressed
specified, in the program.
programs and the
COBOL programmer. For a tutorial, with a detailed
of
the use
keys, when pressed, cause entered
program or the system.
of
each key, the operator should look
data
entry keyboard.
are
the same as on the
IBM
5280 system. The chapter
of
the keys on the other keyboards available
data
entry keyboard. For a detailed
Operator's Guide.
data
to be processed by your
IBM
5280 system to take some
COBOL
is
passed to a control area,
is
intended
at
the Operator's
program. A
if
I
I
I
Command
and
Function
Figure 1.2 The
In general, the function keys shown in figure
data
keys
data
or execute a desired function. Additionally, the top row of
also be used as function keys or command keys. The next two sections
describe the use
Key
Codes
The following codes are returned in the work station control area (described
under
"Work
receives control from the work station:
data
entry keyboard
1.1
are
colored dark, and the
are
white. The operator presses a function key to enter the desired
data
of
these keys and how they affect your COBOL programs.
Station Control
Area"
in
Chapter
3) to your program when it
keys can
• 0 when either
• 99 when any other function key
the
Enter or Record Advance key
is
pressed.
Chapter I. Transaction
is
pressed.
I/0
- Introduction
1-
5
• One
of
the codes shown in figures 1.3 and 1.4 when the indicated
command key
is
for use with your
pressed. (Twenty-one (21) command keys
COBOL programs.)
are
available
Command keys can make interaction between an operator and the program
in
easier and more efficient. For example,
response to a program prompt, the
operator can simply press one of the command keys instead of having to enter
data. You can then determine the next logical action
of
your program based
on the command key code returned to the program.
The operator selects a
either lower case (alpha) or upper case (numeric), (2) pressing the
COBOL
command key by (1) adjusting the shift to
CMD
key,
and (3) then pressing the desired command key.
data
The command keys as they appear on the
typewriter keyboard
program
when each key
are
shown in figures
is
pressed
is
shown in the figure. The code
in a data-item you define in your program.
CONTROL-AREA
in
Chapter
3.
ALPHA
KEY
@
%
*
<
CORR
,
/
~
RECADV
~I
SEL
FMT
clause as described under
SHIFT
CODE
1
2 $
3
4
5
7
8
9
10
11
12
entry keyboard and the
1.3
and 1.4. The code passed to the
is
You relate the data-item to the
"Work
KEY
CORR
DUP
RELADV
~
SEL
Station Control
NUMERIC
#
-
0 20
FMT
SHIFT
CODE
13
15
16
17
18
19
22
22
24
inserted
Area"
I
1-6 IBM
5280
COBOL
Programmer's
Figure 1.3.
KEY
I
f--
Figure 1.4.
Guide
COBOL
LOWERCASE.
2 1
3 2
4
5 4
6
8
9 8
0
COBOL
command keys and codes for
CODE
command keys and codes for typewriter keyboards
10
11
12
data
entry keyboards
UPPERCASE.
KEY
@
$
3
5
7
9
%
&
*
+
f--
co~
13
15
16
17
18
19
20
22
23
24
I
I
I
Function
Keys
Attention
The
Keyboard
This section explains the use of the following function keys, and their
interaction with the
IBM
5280 system and your
COBOL
program:
Attention
Auto
Dup/Skip
Auto Enter
Character
Advance
Character
Backspace
Character
Delete
Character
Insert
Cursor Left
Cursor Right
Duplicate
End-of-Job
Enter
/Record
Advance
Field Advance
Field Backspace
Field Exit
Field Exit Minus
Hexadecimal
Record Advance
Record Backspace
Res{(t
System Request
Two conditions
are
referred to frequently in the sections
that
follow: the
awaiting-field-exit condition and the awaiting-record-advance condition. The
following paragraphs explains what these terms mean.
In fields
that
require field exiting (for example, you have coded
CHECK(FE)
in the related field description statement), an awaiting-field-exit condition
starts
after
the operator enters a character in the last position of the field.
This condition
is
indicated on
the
screen by the cursor blinking in the last line
of the field, and positions
15
and
16
of
the
Status
Line contain 01.
An awaiting-record-advance condition exists
after
the operator enters a
character into the last position
of
a record when
the
automatic enter function
is
disabled.
The
awaiting-record-advance condition
is
indicated on the screen
by
the
blinking cursor beneath the last position
of
the record. The status line
contains
00 in positions
15
and 16.
Pressing the Attention key permits the change
of
control between programs
operating in background and foreground partitions. For example, while
operating in the foreground, pressing the Attention key permits a program
operating in a background partition to
attach
to
the
keyboard/display if
operator action
is
required by
that
program.
If
action is required, the entire
display
is
replaced by
that
program.
After operator action, the original program resumes control
if
the background
program terminates. Otherwise, the operator can return control to the
foreground program by pressing the Attention key.
For more information, see the
5280
System
Concepts manual under
"Partition
Interface".
Chapter
1.
Transaction
I/O
- Introduction
1-
7
Auto
Dup/
Skip
Auto Enter
Character Advance
Character Backspace
Pressing the Auto
DupjSkip
key has the following effect:
• When the cursor enters a field,
data
is
automatically duplicated
in
that
field from the corresponding field
in
the previous record. You must have
coded the
CHECK(AD)
keyword in
the
field description
statement
that
describes the field.
•
When
the cursor enters a field, it automatically skips to the next field.
You must have coded the
CHECK(AS)
keyword
in
the field description
statement
that
describes the field.
See
Chapter
2 for information on
CHECK(AD)
and
CHECK(AS).
When
automatic
duplication or skip
is
in effect, a D in reverse image appears
in position
21
in the
status
line
at
the
top
of
the
screen.
The
operator
can
stop
automatic
duplication
and
skip by again pressing the
Auto
DupjSkip
key.
Data
can
now be entered manually in all fields.
When
automatic
enter
(caused by pressing
the
Auto
Enter
key) is in effect,
the operator doesn't have to press the
Enter
key
after
entering a
character
into
the
last position
of
the
last field
of
a record.
After
the
Auto
Enter
key
is
pressed, entering a
character
into the last position
of
a record has
the
same
effect as pressing
the
Enter
key. Control is then passed to the
COBOL
program for processing.
When
automatic
enter
is
in effect,
an
R appears (in reverse image) in position
23 in
the
status
line
at
the top
of
the
screen. To stop
automatic
enter, the
operator again presses the
Auto
Enter
key; a blank will now
appear
in position
23
of
the
status
line.
Pressing the
Character
Advance key moves the cursor
ahead
one position in a
field.
The
data
in the position isn't changed.
When
the cursor
is
moved
out
of
one field into
the
next, a field advance function
is
performed.
If
automatic
enter
(described above)
is
in effect, advancing
the
cursor into the
last position
of
the record has
the
same effect as pressing the
Enter
key.
If
automatic
enter
isn't
in effect,
and
the
operator presses
the
Character
Advance key when the cursor
is
in
the
last position
of
the record,
an
error
will
occur.
When
awaiting-field-exit
is
indicated, pressing the
Character
Advance key
has the same effect as pressing
the
Field Exit key.
Pressing the
Character
Backspace key moves the cursor back one position.
The
data
isn't changed.
The
key
can
be used to move the cursor from the first
position
of
one field to the last position of
the
preceding field, unless
automatic
duplicate or
automatic
skip (as described under
"Auto
DupjSkip"
earlier in
this
chapter)
is
in effect. Then, the field
is
either automatically duplicated or
skipped.
When
awaiting-field-exit
is
indicated, pressing the
Character
Backspace key
resets
the
condition. the cursor stays in the last position
of
the field; the
operator
can
now enter a
character.
1-
8 IBM 5280 COBOL Programmer's Guide
Character Delete
Character Insert
Cursor
Left
Cursor Right
The
Keyboard
When awaiting-record-advance
is
indicated, pressing the
Character
Backspace resets the awaiting-record-advance condition and puts the cursor in
the last position
of
the last preceding field in which the operator can enter
data.
Pressing the
Character
Delete key deletes the character
at
the cursor position.
The characters within the field and to the right of the cursor shift to the left
one position, and a blank
is
inserted in the rightmost position
of
the field. The
cursor position doesn't change.
In a character check type field (when you code a C in
the
Data Type field
of
the field description statement
that
defines the field) the
character
delete
function acts within subfields only. Subfields
are
adjacent character positions
for which the same
character
type
is
specified in the parameter for the
keyword
SHIFT.
The operator cannot use the
Character
Delete key when you code a blank
check -
CHECK(BC)
-or a mandatory
fill-
CHECK(MF)
-in the
related
Data
Definition Statements.
After pressing the
Character
Insert key, the operator can insert characters
into a field
at
the current position of the cursor. (When the key
is
pressed
a>
appears in position
14
of
the status line.)
After each character
is
entered, all
data
between the cursor and the right end
of the field moves to the right one position. The operator can move the cursor
within the field by using the
Character
Advance and
Character
Backspace
keys.
After insertion, the operator must press the Reset key before exiting the field.
When a nonblank
data
character occupies the rightmost position
of
the field,
an
attempt
to insert a character causes an error.
If
you specify
character
check
data
in the field description statement
that
defines the field (a C in the Data Type field) any characters shifted to new
positions must conform to the specifications for those positions
that
you code
in the
SHIFT
keyword. Data can be shifted only within a range
of
positions
for which the same
character
type
is
specified in the parameter for the
SHIFT
keyword.
Data
isn't shifted into a position for which a different
data
type
is
specified.
You can insert characters in a hexadecimal field when an H
is
specified in the
Data Type field
of
the related field description statement. A hex entry
character requires two keystrokes. The Insert key must be pressed before the
first character
is
entered.
The operator cannot insert characters in fields for which you specify
mandatory
fill-
CHECKC,MF) -in the related field description statement.
Pressing the Cursor Left key has the same effect as pressing the
Character
Backspace key.
Pressing the Cursor Right key has the same effect as pressing the
Character
Advance key.
Chapter
1.
Transaction
I/0
- Introduction
1-
9
Duplicate
End-oj-Job
Enter / Record Advance
Field Advance
Field Backspace
Pressing the Duplicate key copies characters into the field from the
corresponding field in the previous record, unless the keyword
CHECK(DD)
(for duplicate disable) has been specified for the corresponding field
description statement.
Pressing the
CMD
key followed by the End-of-Job key closes all files and ends
program execution. The operator
is
then prompted to load a program.
Pressing the
Enter
Key has the following effect:
• All edits you specify in the
Data
Definition Statements for all
the
fields
on
the
screen
are
completed.
•
If
an
error
is
found, a four-digit blinking error code appears in positions
8-11 in
the
status line
at
the
top
of
the screen. See the section
"Status
Line" in
Chapter
8.
for a description
of
the different types
of
error
codes
that
can appear and other related information in the status line.
•
If
no edit error
is
found, your
COBOL
program is given control.
When
the
operator presses
the
Field Advance key, the following takes place:
• Any edit function you specify in
the
Data
Definition Statements for the
field
are
started.
•
If
the
edit
is
completed without error, the cursor moves to the next field
where the operator
can
enter data.
•
If
the
edit finds an error, a blinking error code will
appear
in positions
8-11
of
the
status line.
The
cursor remains in the right-most position of
the
field.
Pressing
the
field advance key before
the
cursor reaches the last position in the
field doesn't affect any characters between
the
cursor and the end
of
the field.
If
automatic
enter (as described under
"Auto
Enter"
earlier in this chapter)
is
in effect, pressing
the
Field Advance key when the cursor
is
in
the
last position
of
the
record has the same effect as pressing
the
Enter
key.
That
is, control
is
given to the
COBOL
program for processing.
Pressing the Field Backspace key has the following effect:
• When the cursor
is
in
the
first position
of
the field, the cursor moves to
the first position
of
the first previous field where automatic skip or
automatic duplication isn't in effect. (Automatic skip and duplication
are explained under
"Auto
Dup/Skip"
earlier in this chapter.)
• When the cursor
is
in
a position other
than
the first position,
the
cursor
moves to the first position
of
the same field.
If
awaiting-field-exit or awaiting-record-advance
is
indicated in the status
line, pressing the Field Backspace key resets the status line and returns
the
cursor to the first position
of
the field.
1-
10
IBM 5280 COBOL Programmer's Guide
Field
Exit
Field
Exit
Minus
The
Keyboard
When awaiting-record-advance
is
indicated, the field backspace function
resets
the
condition and returns
the
cursor to the first position
of
the
last
preceding field in which
the
operator
can
enter data.
Pressing the Field Exit key has the following effect:
• For fields
that
contain signed numeric
data
(you coded
an
S in
the
Data
Type
field in
the
related
Data
Definition
Statements),
all
data
is
shifted
to the right, and unused positions are filled with zeros.
The
position
immediately to
the
right
of
the field
is
set to blank to indicate a positive
number.
• For fields in which
data
is
to be right-adjusted (you specified
CHECK(RZ),
CHECK(RB)
or
CHECK(RL)
in
the
related field
description
Statement),
data
to the left
of
the cursor
is
shifted to the
right.
Unused positions
are
filled with zeros or blanks, depending on
your specification.
•
If
neither
of
the
above
is
true, all positions to the right
of
the cursor are
filled with blanks.
In
all
of
the
above cases, any other edits you specify in
the
Data
Definition
Statements
are done.
If
no
error
is
found, the cursor advances to the next field
in which
the
operator can
enter
data.
If
an error
is
found, a four-digit blinking error code appears in positions 8-11
in
the
status line
at
the tops
of
the
screen. See the section
"Status
Line" in
Chapter
8 for a description
of
the different types
of
error codes and other
related information
that
can
appear
in the status line.
Pressing
the
Field Exit Minus key affects only those fields in whose
Data
Definition Statements you have coded one
of
the
following in
the
Data Type
field:
D (digits only)
N (numeric shift)
S (signed numeric)
Y (numeric only)
Pressing the Field Exit Minus key has the same effect as pressing the Field
Exit key, except the sign
of
the
data
in the field indicates a negative quantity.
In
signed numeric fields, a minus sign
is
displayed in the position to the right
of
the field.
In
fields for digits only, numeric only, or numeric
data
types when right-adjust
is
specified or awaiting-field-exit
is
indicated, the zone
of
the
rightmost
character
(which must be a number)
is
changed to hexadecimal D.
Chapter
1.
Transaction
I/0
- Introduction
1-
11
Hexadecimal
Record Advance
Record Backspace
Reset
Skip
The
rightmost
character
in
the
field, signifying the negative sign,
is
displayed
as follows:
Numeric
{ for 0
J for 1
K for 2
L for 3
M for 4
N for 5
o for 6
P for 7
Q for 8
R for 9
Digits
Only
/
Numeric
Only
0* for 0
1 * for 1
2*
for 2
3* for 3
4* for 4
5*
for 5
6* for 6
7*
for 7
8* for 8
9* for 9
*
Each
digit will
appear
on
the
screen smaller
than
the
standard
size digit
usually displayed
and
will have a
bar
just
above it.
In
fields for digits only,
numeric
only, or
numeric
data
types
without
right-adjust
specified
and
without
awaiting-field-exit indicated, all positions
from
the
cursor
through
the
next-to-Iast position
of
the
field
are
blanked,
and
the
rightmost
position
is
set
to hexadecimal
DO.
Pressing
the
Hexadecimal
key allows
the
operator
to
enter
a hexadecimal
value. Two
data
keys in succession
must
be pressed for
each
hexadecimal
character.
The
numbers 0 through 9 and
the
letters A
through F are
the
only
valid entries.
The
character
displayed above
the
cursor
is
the
single
character
that
results
from
the
translation
of
the
hexadecimal
value entered.
If
the
translation
doesn't
yield a displayable
character,
the
value is displayed as
•.
The
hexadecimal
representation
of
the
characters
entered
by
the
operator
is
displayed in positions
18
and
19
in
the
status
line
at
the
top
of
the
screen.
See
"Enter/Record
Advance".
Pressing
the
Record Backspace key
returns
the
cursor
to
the
first position in
the
first field
of
the
record where
the
operator
can
enter
data
manually.
By pressing
the
Reset Key,
the
operator
can:
Reset
the
status
line
and
unlock
the
keyboard
after
an
error
is
found.
•
Cancel
the
effect
of
pressing
the
Command
(CMD),
Hexadecimal,
and
Insert
keys.
Pressing
the
Skip
key
cause
the
remainder
of
the
field to be filled with blanks.
Any
edits specified for
the
field
are
then
done.
If
no errors
are
found,
the
cursor
advances to
the
next field where
the
operator
can
manually
enter
data.
When
awaiting-field-exit is indicated,
either
the
Skip
key
or
the
Field
Exit
key
can
be pressed.
1-
12
IBM 5280 COBOL Programmer's Guide
System Request
The
Keyboard
By
pressing the System Request key, the operator temporarily stops the
execution
of
the current program to load a program into another partition.
Then, execution
of
the current program resumes.
If
the
new program
is
loaded into the same partition as the first program,
execution
of
the first program stops.
Chapter
1.
Transaction
I/O
- Introduction
1-
13
1-
14
IBM
5280 COBOL Programmer's Guide
Chapter 2. Transaction
I/O
-Screen Definition
This chapter provides the information necessary to define the screens used by
a
COBOL
operator
• An example of coded
program in interactive processing between the program and the
at
the work station. The following topics are covered:
Data
Definition Statements
• Coding Conventions
• Rules for coding the
Data
Definition Statements.
Example
of
Coding Data Definition Statements
The example in this section shows the steps followed in planning a screen
format and coding the necessary
Definition Statements are used in the COBOL coding example shown figure
3.3 in
Chapter
For the purpose
3.
of
the example, it's assumed
information from a form like the following to update an employee master file:
Data
Definition Statements. The same
that
data
entry operators entered
EMPLOYEE MASTER FILE RECORD
(for entering or adding records)
Social
security
number
Data
Employee
Street
City,
na.
addres~
State
Figure 2.1. Sample form used by
In the example, the screen
the figure.
The
following editing characteristics will be defined for the fields
is
designed to resemble the sample form shown in
(and explained in detail later):
data
Chapter
entry operator
2.
Transaction
I/0
- Screen Definition
2-
1
IBM
•
Data
must be entered in all fields
•
Certain
fields (zip code, beginning
date,
and
social security
number)
must be completely filled before the
operator
can move
the
cursor to the
next field or
enter
the
record.
•
The
beginning
date
in the previous record
can
be automatically
entered
in
the
beginning
date
field
of
the
current
record
at
the option
of
the
operator.
Using the above information, the layout
of
the
screen
is
planned on
an
IBM
Printer/Display
Layout
form (order
number
GX21-9174)
as shown below:
International
Bus,""s
MachlnM
Corporation
Printer IDisplay Layout
POSITION
Figure 2.2.
Printer
jDisplay
Layout
form
Using the layout form makes it easier to see how
the
data
will
appear
on
the
screen
and
to code
the
field description
statements,
in which you usually write
the
position on
the
screen where each field
is
to appear.
Keep in mind
the
size or sizes
of
the
work station screens available
at
your
location when designing
the
screens.
They
come in
three
sizes: 1920, 960, and
480.
The
dimensions for each size
are
as follows:
2-
2 IBM 5280
COBOL
Programmer's Guide
Size in Characters Number
of
horizontal rows Number
of
l'ertical columns
1920
960
480
Once the format
of
the screen has been planned, the next step
Data Definition Statements.
The
24
12
6
IBM
5280 Data Description Specifications
80
80
80
is
to write the
form, order number GX21-9362 can be used as an aid in coding the
specifications. The
that
continuation lines
CHECK
containing a
for coding a secondary line are:
• A secondary line must always follow a
•
• A secondary line must begin with a keyword.
• A secondary line
Comment statements, which contain an asterisk
placed where desired between primary, secondary,
keyword (whose functions
line.
The
primary or continuation line
must not have a
character.
specified for
of
lines for field
starting
must
described above, one or more secondary lines. A
+
character
can
in column 45, the editing field, which
that
have a +
have continuation lines under the
lines.
character
can
contain, in addition to
are
explained
must always begin on a secondary line.
that
or a -
character
and
record statements:
and
optional, in
and
literals.
the
editing field (begun on
comes before
or a -
character
the
later
primary
comes before a secondary line
specified as the last
(*) in column 7, can be
and
another
as
the
differences between
primary
in this chapter)
line
continuation lines.
and
or
a continuation
same
last
The
rules
rules
Continuation Characters
Keywords
If
a literal, keyword, or keyword
continue it on the next line by coding a plus
character
A plus
the first nonblank
A minus (-)
first non blank
always includes any blanks preceding the
Keywords represent
accompanied by a string
attributes
must be enclosed within a
The general syntax for a keyword
KEYWORD
When the
parameter
blank.
( -) as the last non blank
(+)
character
character
or function.
indicates
character
causes the compiler to include
character
attributes
in the continuation line
of
The
(parameter string)
parameter
must be separated from the preceding
string contains two or more parameters, each consecutive
parameter
character
that
the compiler
in
the
continuation line
and
functions. Most keywords must be
one or more
string
of
pair
of
parentheses.
and
Chapter
+ or - continuation
parameters
parameters must follow the keyword and
its
parameter
2.
Transaction
doesn't fit on one line, you can
character
in the line.
(+)
is
to ignore
that
follows.
any
blanks before the
that
follows.
that
further
string
parameter
I/0
- Screen Definition
or a minus
any
blanks before
The
compiler
character.
define the
is:
by
at
least one
2-
9
Constants
Comment Statements
Two or more keywords can be specified on a single line. Any keyword
that
is
specified without a parameter string must be separated from the following
keyword by
at
least one blank.
Within these guidelines, the following three lines convey identical meanings to
the compiler.
CHECK(DR
FE
RB)DSPATR(CS)
CHECK
(DR
FE
RB)
DSPATR(CS)
CHECK
(DR
FE
RB)
DSPATR
(CS)
In the above three lines, the only required blanks are between the parameters
following the
CHECK
keyword. Whenever a keyword and its parameters
aren't
started and completed
on
the same line, the use of a continuation
character
is
required. See Continuation Characters, earlier in this chapter.
Character
constants consist
of
any combination
of
characters, including
blanks. Character constants must be enclosed
in
apostrophes. An apostrophe
required as
data
within the constant must be represented by two apostrophes.
If
necessary, you can continue a constant on one or more continuation lines.
Comment statements allow you to insert comments among the Data
Definition Statements, providing a means to document their logic
if
necessary.
Comment statements can be placed anywhere in the source statement
sequence. They are ignored by the compiler. You write a comment
by
entering an asterisk (*) in column
7.
The remaining positions
of
the line
(columns 8 through 80) are then ignored by the compiler and are available for
comments.
2-
10
IBM 5280 COBOL Programmer's Guide
Record Description Statements
Record description statements name the record and describe characteristics
that
apply to the entire record.
SelJllence Number Field (Columns 1 tllrougll5)
Enter
the statement sequence number,
entered, will appear next to the
out by the compiler. This name
19-26) described below.
Sequence numbers in source statements
when you want to change, add, delete, or relocate a source statement. The
only restriction
contain
Form Type Field (Column 6)
Enter an A in the
Name Type Field (Column 17)
The letter R
statements.
**.
is
that
Form
is
required in the
Record
01
level data-name in the source listing
is
defined in the
the
first two columns
Type field.
Name
Description
if
desired. The sequence number,
Record
are
optional. They can be useful
of
the Sequence field cannot
Type field for record description
Statement
Name
field (columns
if
put
Record Name Field (Columns 19 through 26)
A name
more than eight (8) characters long. In the source listing put out by the
compiler, the name specified will appear as a
item.
The rules for defining names are the same as for
(except for the limit
field
with an alphabetic character.
need more details on these rules.
is
required on a record description statement. The name must not be
are
A through
Usage Field (Column 38)
The entry you make in the
field statements which contain a blank in column 38.
Valid entries in the
o establishes a default
statements.
B establishes a default
field description statements.
blank indicates no default; an entry must be made in the
subsequent field description statement.
Output
(0)
Fields
For those fields defined for output (you enter an
1.
The operator cannot enter
2.
You must specify a nonnumeric literal in the
column 45. The literal can have any character in the
must be enclosed within single quotes ( ,
used as
part
of the
01
level record-name and group
COBOL
of
eight characters): valid characters in the
Z,
0 through 9, and - (the hyphen); the name must begin
See the COBOL Language Reference
Usage field supplies a default value for subordinate
Usage field are:
of
output only for subordinate field description
that
is
for both input and output in subordinate
record-names
Record
if
Usage field in each
0 in the Usage field):
data
into the field.
character
Editing
1
it
era
string must be coded twice
field starting in
EBCDIC
1 ' ). Any single quote
('
set and
').
name
you
Chapter
2.
Transaction
I/0
- Screen Definition
2-
11
on
The literal appears
associated
in
Figure 2.5 earlier in this chapter.
3.
You must leave the Field
WRITE
the screen when your COBOL program issues an
statement. The use
description statement) blank.
Name
field (columns 19-24
of
literals
is
shown
of
the field
at
II through D
Both Input and Output
(B)
Fields
For those fields defined for both input and output (you enter a B in the
Usage
field):
1.
The operator can enter data on the screen in fields defined by the
statements.
2.
The operator can duplicate
data
from the corresponding positions in the
preceding record by pressing the Duplicate key, unless you specify
CHECK(DD)
3.
Data
can be automatically duplicated in the field when the the operator has
pressed the Auto
keyword and parameter in
description statement. The
as explained later in this section.
Dup/Skip
key, and you have coded the
the
editing field
data
is
automatically duplicated from the
of
CHECK(AD)
the associated field
corresponding positions in the previous record when the cursor enters the
field.
When using a field for both input and output, consider the following when
writing your
1.
The field description statements with a B specified in the Usage field define
02 level elementary items in the
2.
When a
written to the screen.
either initialized with blanks or the
COBOL program:
WRITE
is
executed, any
You should therefore ensure
COBOL
data
program.
in the associated record will be
that
data
you want before the
such fields are
WRITE
executed.
3.
The operator can write over any
data
appearing in the field.
is
To
Prevent Entry
of
Data
in a B-Field
Editing Field (Columns
CHECK(DD)
2-
12
IBM 5280
COBOL
Programmer's Guide
To prevent the entry of
data
in a B-Field, use the
CHECK(BY)
keyword
described later in this chapter. With this keyword, you can cause the cursor to
bypass a field on the screen either conditionally or unconditionally.
45
through 80)
The entry you make in the editing
which don't contain overriding keywords in columns
field
applies to subordinate field statements
45-80.
You can specify the fonowing keywords in a record description statement:
Keyword
CHECK
DSPATR
CHECK(DD)
The
fields defined by subordinate field description statements.
Description
Keyboard level edits
Display attributes
keyword prevents the operator from using the
DUP
If
CHECK(DD)
specified in the record description statement, you cannot override it in a
subordinate field description statement.
CHECK
statement, as described under
allows a wider range
of
edits when specified in the field description
"Field
Description
Statement"
below.
key for
is
DSPATR (attributes)
Record
Description
Statement
With the DSPATR (for display attributes) keyword, you can control the
on
display attributes
the screen. The attributes specified by this keyword are
combined with those specified in the field description statement (if any) to
establish the display attributes to be used for a field.
See the explanation
of
DSPATR
in
the section "Field Description Statement"
for a description of the attributes and the rules for specifying them.
Chapter
2.
Transaction
I/0
- Screen Definition
2-
13
(This page
is
intentionally left blank.)
2-
14
IBM
5280
COBOL
Programmer's
Guide
Field Description Statements
A field description statement can be made up
secondary lines as described under
chapter.
Sequence Number Field (Columns 1 through 5)
Enter the statement sequence number,
entered, will appear next to the 02 level elementary item in the source listing
put out by the compiler.
(columns 19-24) described below.
Sequence numbers in source statements
when you want to change, add, delete, or relocate a source statement. The
only restriction
contain
**.
Form Type Field (Column 6)
Enter an A in the Form Type field.
Indicator Field (Columns 9 and 10)
Leave this field blank except when you want to cause the cursor to
conditionally bypass a field and specify the
purpose.
this chapter.
Code any number from 1 through 99. Single digit numbers
must be right-adjusted with a leading blank.
The indicator you specify is associated with a boolean data-item you code
in your program.
For the rules to follow in coding the
see the
and
For the format
Chapter 3 of
under
For an example
Statements using conditional bypass with indicators, see
"INDICATOR
5280 COBOL Language Reference manual under
"INDICATOR
"WRITE".
is
that
You specify
this manual or the 5280 COBOL Language Reference manual
CHECK(BY)
Clause".
of
the
INDICATOR
of
the
Example".
Field
"Coding Conventions" earlier in this
You define this name in the field name field
the first two columns
in the Editing field as described later in
INDICATOR
clause in the
COBOL
statements and the
Description
of
primary, continuation, and
if
desired. The sequence number,
are
optional. They can be useful
of
the
Sequence field cannot
CHECK(BY)
WRITE
keyword for this
(1
clause with a data-item,
"OCCURS
statement, see
Data
Definition
Chapter
Statement
if
through 9)
Clause"
3 under
Field Name Field (Columns 19 through 24)
Leave this field blank when you
output only (column
Field
The
(8) characters long. The name will appear as a
your
If
you leave this field blank when the statement defines a field
used for both input and output (column 38, the
resulting
The rules for defining names are the same as for COBOL record-names: valid
characters in the
hyphen); the name must begin with an alphabetic character. See the
Name
COBOL
02 level data-item will appear as
Language Reference
38
the Usage field, has an 0 in it).
field must be a valid COBOL data-name not more
program.
Field name field
if
you need more details on these rules.
are
defining a field
are
A through Z, 0 through
Chapter
2.
02 level elementary item in
Usage field, has a B in it), the
FILLER
Transaction
that
is
to be used for
than
eight
that
is to be
in your COBOL program.
9,
and - (the
COBOL
I/O
- Screen Definition
2-
15
Length Field (Columns 30 through 34)
Leave this field blank when you
output only (column
You must specify a length when a
(the
Usage field, column 38, has a B in it). The following rules apply:
The maximum length of the field depends on the type
1.
Character
statements, as noted earlier,
COBOL
2.
Numeric fields can contain up to
program.
Only the digits 0 through 9
zeros or leading blanks are acceptable. The entry in the
right adjusted.
Data Type Field (Column 35)
Leave this field blank when:
• You code
• This statement defines a field
Usage field, column 38, has an 0 in it).
You must specify a
(the
Usage field, column 38, has a B in it) unless you specify
the
Editing
field.
are
defining a field
38
the Usage field, has an 0 in it).
data
field
is
that
is
to be used for
used for both input and output
of
field you specify:
fields can contain up to 256 positions; field description
are
compiled as 02 level data-items in your
18
positions.
are
allowed in the Length field; either leading
Length field must be
CHECK(BY)
data
in the
Editing
that
is
type when the field
field.
to be used for output only (the
is
used for both input and output
CHECK(BY)
(The
CHECK
keyword is explained later in this chapter.)
in
Data-Item Class in COBOL Program
The class (numeric or alphanumeric) of the data-item compiled in the
COBOL
Decimal Positions field, as shown in the following table:
program depends on you entry in both the Data Type field and the
Data
Type
field contents:
A,C,D,H,N,
S,
V, W, X, or Y
A,C,H,
X,orY
D,
N,
or S
V,
W,
Decimal Position
field contents: program
blank alphanumeric (X)
0-9
0-9
Data
class
of
field in COBOL
after
compilation:
unsigned numeric
(9V9)
signed numeric
ICOUO\
tJ71'7
2-
16
IBM 5280
COBOL
Programmer's Guide
Data
Type
Field
Entries
Field Description
You can make the following entries in the Data Type field:
Statement
Entry
A
C
D
H
Condition
Alphabetic shift - Any
positioned to
The operator
the
can
character
can be entered.
The
shift
lower symbol on each key on all keyboards.
use
the
shift key to enter the upper symbol on
the keys.
Character
determined by the
field description statement.
when this
check - The characteristics
data
parameter
type
is
specified. See
for the
The
SHIFT
of
the keyboard
SHIFT
keyword
the
SHIFT
are
keyword in the
is
required
keyword
later
in this section.
Digits only -
The shift
keyboards and
Only the numbers 0 through 9 can be entered.
is
positioned to
is
positioned to the upper symbols on both
the
lower symbols on typewriter
data
entry keyboards and proof keyboards. The operator cannot
override the shift. Negative numbers
of
sign over the units position
is
A negative value
entered in the field when
the number.
having entered one or more digits, presses
are
displayed with the
the
operator,
the
Field Exit Minus
key.
Hexadecimal-
and only
can be entered. No shift key operation
data-entry
Each
character
the
numbers 0 through 9
keyboards.
position requires two keystrokes
and
the letters A through F
is
required on
is
N
Numeric
positioned to the lower symbols on typewriter keyboards
positioned to the upper symbols on both the
shift - Any
character
can be entered. The shift
data
entry
is
and
is
keyboards and the proof keyboards. The operator can change
the shift by using the
A negative value
Shift key.
is
entered in the field when
the
operator,
having entered one or more digits, presses the Field Exit Minus
key.
S Signed numeric - Only the numbers 0 through 9 can be entered.
The
signed numeric
digits only, and field exit required. To exit the field,
operator must press the Field Exit key (for positive values)
the Field Exit Minus key (for negative values).
shift
is
positioned to the lower symbols
and to the upper symbols
When signed numeric
additional display position, which
of
the
data
field. This additional display position
position.
It
is blank for positive values and
data
type implies right adjust with zero-fill,
The
on
typewriter keyboards
on
data
entry and proof keyboards.
data
is
entered,
the
system designates an
is
adjacent to and to the right
is
the
is
set to - (minus
the
or
keyboard
sign
sign) for negative values.
of
The corresponding field
the record in the
not lengthened. The zone portion
contains hexadecimal D instead
of
the lower-order digit
of
a hexadecimal F, indicating a
COBOL
program
is
negative value.
Chapter
2.
Transaction
I/O
- Screen Definition
2-
17
A negative value
having entered one or more digits, presses
key.
V Right
half
only - Only the
generation can be entered.
right symbols on appropriate keyboards.
entry
of
the upper right symbols. (See the note below
explanation for
W Right
half
shift - Any
positioned to the lower right symbols on appropriate keyboards.
The
opera tor can change the shift by using the shift keys.
aNote:
more
V
and
W should be used only for those keyboards with
than
two shift positions (such as the
Don't use these
on other keyboards or an unrecoverable error will occur
execution.
X Alphabetic only -
and
hyphen,
space can be entered.
lower symbols on all keyboards.
the opera tor.
Y
Numeric
plus, minus,
to
only - Only
and
the
lower symbols on typewriter keyboards and to the upper
symbols on both the
keyboards.
The
A negative value
having entered one
key.
is
entered in the field when
characters
The
shift
the
operator,
the
Field Exit Minus
that
are defined
is
positioned to the lower
The
shift key allows
at
system
after
W.)
character
data
types in programs
can
be entered. The shift
Katanana
that
are
is
keyboard).
to be executed
at
Only the letters A through
The
The
shift cannot be changed by
the
numbers 0 through 9, comma, period,
shift
Z,
comma, period,
is
positioned to
space can be entered. The shift is positioned
data
entry keyboards and
shift cannot be changed by
is
entered in
or
more digits, presses
the
field when
the
proof
the
operator.
the
operator,
the
Field Exit Minus
the
the
Decimal Positions Field (Column 37)
Leave this field blank
data-item
created by the field description
alphanumeric, regardless
Enter
any value from 0 through 9 to indicate a numeric value.
COBOL
program,
will be defined as numeric, regardless
The
field.)
the decimal point for the data-item. You must also specify a length in the
Length field (columns 30-34).
TT~noo
"""'..,
.. 6 .....
FiolJ
.a.
..........
frnl",.,"
'''''''"
............
~R)
..,"'/
You needn't make an entry in the Usage field if you already have an entry in
the Usage field
override
ONote:
make one
If
the
the
of
o the field can be used for
B the field
blank the field
description statement.
if
the
data
is alphabetic.
of
what you specify in
(In
statement
the
the
COBOL
program, the
will be defined as
Data Type field.)
(In
the
data-item
0 through 9 value defines
of
the record statement. However,
created by the field description statement
of
what you specify in
the
number of positions to the right
if
you make
the
Data Type
an
corresponding entry in the record description statement.
Usage field
of
the record description statement is blank, you must
the following valid entries:
output
can
be used for both input and output.
is
to use the default specified in the preceding record
only.
the
of
entry, it will
2-
18
IBM 5280 COBOL Programmer's Guide
Field Description
Statement
Output
Input
(0)
and
Fields
Output
(B) Fields
For those fields defined for
1.
The operator cannot enter
2.
You must specify a nonnumeric literal in the
column 45. The literal can have
must be enclosed within single quotes ( ,
part
of
used as
the
The literal appears on the screen when your
associated
When using a field for both input and output, consider the following when
writing your
1.
The field description statements define 02 level elementary items in the
COBOL
COBOL
program.
program:
Chapter
2.
Transaction
I/0
- Screen Definition 2-.19
2.
When a WRITE
written to
either
the
initialized with blanks or the
executed.
3.
The
operator
CHECK(BY)
To
Prel'ent
Entry
of
Data
in a B-Field
To
described
prevent
the
later
bypass a field on
Location Field (Columns 39 through 44)
In
the
location field, you code
screen as follows: you specify
and
39-41
data
STARTING
your
will
1.
To
LINE
2.
If
be 3.
3.
The
is 2.
always
chapter.
If
4.
fields,
3.
following
The
prompt
AT
between
physical line on
the
appears
COBOL
appear
on:
determine
value with
you
don't
minimum
Note
appear
you
don't
the
starting
Each
field
the
defaults for line
line
at
LINE
is specified or not.
STARTING
is executed, any
data
in the associated record will be
screen. You should therefore ensure
data
you
want
can
write over
any
data
appearing
is in effect.
entry
of
data
in this
the
chapter.
screen
in a B-Field, use
With
this keyword, you can
either
conditionally or unconditionally.
the
location where
the
line
number
the
(vertical position) in columns
horizontal position in columns 42-44.
on
the
screen depends on
AT
LINE
n clause in
program.
the
specify a
that
specify a
Here
physical line on
the
value you write in columns 39-41.
STARTING
value
that
be specified in
prompts specified with
on
line 2.
The
STARTING
position for
that
follows will be in
are
whether
the
corresponding
the rules
the
AT
that
screen,
LINE
the
the
PMT
PMT
keyword is explained
AT
LINE
the
first field will be
the
next available display position
or not you specify
determine
STARTING
previous field.
and
position entries ensure
the
top
of
the
screen
aren't
overlayed, whether
The
AT
the
screen where
following
LINE
values, line entries in columns 39-41,
the
field will appear.
table
that
such fields
before the
in
the
field unless
CHECK(BY)
cause
the
field will
The
actual
WRITE
which line a field
add
the
STARTING
Then
clause,
the
default
AT
(for
prompt)
later
clause, or Line
the
first position in line
that
the
Status
shows
the
relationship
are
WRITE
keyword
the
cursor to
appear
on
line where
the
statement
AT
subtract
value will
LINE
clause
keyword
in this
and
Position
Line
and
STARTING
and
is
the
the
in
1.
the
the
STARTING
Blank
Blank
Blank
Blank
3
3
3
3
4
4
4 2
4 3 6
2-
20
IBM 5280 COBOL Programmer's Guide
Value Cols. 39-41 Screen Line
(default
(default
(default
(default
3)
Blank
3) 3
3)
3)
2
3
Blank
1 3
2
3
Blank
1
Next
available position
4
5
Next
available position
4
5
Next
available position
4
5
Field
Description
Statement
Editing Field (Columns
CHECK
(parameters)
Entries
in
the Line and Position fields must be right adjusted. Either leading
zeros or leading blanks are allowed. The following table gives the dimensions
for the three screen sizes available with a 5280 system:
~umber
of
Size in Characlers
45
through 80)
Number
-
1920 24
960
480
~
of
. -
12
horizontal rows
6 80
.....
, .
-
--
vertical columns
•
CT-'
80
80
Entries in the Editing field are optional. An entry in this field can be a single
keyword with a parameter string or multiple keywords, each with its
parameter string. You can extend the Editing field with continuation lines.
The
CHECK
the system.
keyword allows you to cause data to be edited automatically by
If
the
data
isn't entered as you specify, the keyboard will lock and
an error message will appear on the screen.
CHECK
requires
at
least one
of
the following parameters.
Parameter Meaning
AD Automatic duplication - when the cursor moves into the field
for which
corresponding positions in the previous record
CHECK(AD)
is
specified, data from the
is
automatically
copied into the field. The operator controls whether or not
duplication will occur with the Auto
in
Chapter
CHECK
1.
During automatic duplication, data type and
keyword edits are ignored.
Dup/Skip
key as described
AS Automatic skip - when the cursor moves into a field for which
CHECK(AS)
is
specified, blanks
are
inserted into the field, and
the cursor moves to the next field where the operator can
manually enter data. The operator controls whether or not a
skip will occur with the Auto
Chapter
1.
BC Blank check -
which
CHECK(BC)
bypass the field, leaving it blank,
when the cursor moves to the first position
BY Bypass -
The
unconditionally. When the field
cannot enter
The
operator cannot enter blanks into a field for
is
cursor bypasses the field, either conditionally or
data
and the contents
Dup/Skip
key as described in
specified. However, the operator can
by
using the Field Exit key
of
the field.
is
bypassed, the operator
of
the field remain
unchanged.
A field can be conditionally bypassed
(and indicator) and
CHECK(BY)
if
you code the condition
in
a secondary line
of
field description statement. The only entries you can make in
the secondary line are an entry in the Sequence field, an
indicator number
Form Type field, and
in
the Indicator field, the required A in the
CHECK(BY)
in the Editing field.
the
Chapter
2.
Transaction
I/O
- Screen Definition
2-
21
DD Duplication disable - The operator cannot use the Duplication
Key
in
DR
fields for which
Data
required - The operator must enter
character in fields for which
CHECK(DD)
CHECK(DR)
is
specified.
at
least one nonblank
is
specified.
FE
Field exit required - The operator must press one of the Field
Exit keys to exit the field. See
Chapter
1 for an explanation of
the Field Exit keys.
Normally, when the last character in a field
is
exited automatically.
is
entered, the field
LC Lowercase - The operator can enter both uppercase and
lowercase characters
LC
Without
characters.
specified, all characters
LC
is
ignored
if
the typewriter keyboard is used.
are
treated as uppercase
if
the typewriter keyboard is not
being used.
ME
Mandatory entry - The operator must enter
at
least one
character, either blank or nonblank.
MF
Mandatory
fill-
If
one character is entered, the operator must
enter characters into all the positions of the field.
fill-
RB Right adjust with blank
Field Exit key, all
the
rightmost positions
to
data
when the operator presses the
is
shifted from the position of the cursor
of
the field,
if
no
data
has been
entered in these positions. The unused positions to the left of
the
data
are
filled with blanks. The operator must press the
Field Exit key to exit the field.
RZ
Right adjust with zero
data
is
Exit key, all
rightmost positions
these positions.
filled with zeros.
shifted from the position of the cursor to the
of
The
The
fill-
when the operator presses the Field
the field,
if
no
data
has been entered in
unused positions to the left of the
operator must press the Field Exit key to
exit.
data
are
RL
DSPATR
(attributes)
With the
screen with the parameters shown in figure 2.6.
give special rules when coding a
2-
22
IBM 5280 COBOL Programmer's Guide
Right to left - As the operator enters characters, the rightmost
position
filled first; each additional character
is
added in the
is
next free position to the left. The operator must press the Field
Exit key to exit. A
Vor
W must be specified in
the
Data Type
field.
DSPATR
keyword, you can control how characters appear on the
The
following two sections
DSPATR
keyword.
Field Description
Statement
Placement
of
Attribute Control
Attribute
BL
CA
CS
HI
ND
RI
UL
Figure 2.6.
Meaning
Blink. The displayed field(s) blinks (flashes on and off).
Cancel. When specified in a field description statement,CA cancels
display attributes made
when an
statement isn't desirable for the field being defined.
can then be specified to control the display for the record.
parameter
coded.
Column Separators. Column separators are displayed in the field(s).
Column separators
they do not reduce display capacity.
Highlight. The displayed characters are highlighted (displayed with
increased intensity).
Nondisplay.
Reverse image.
reversed (dark characters
Underline. Each
Attributes
attribute
CA affects only the field description statement for which it
The
that
can be specified with
in
the
record description statement. Use
or characteristic specified in the record description
are
thin vertical lines between
field(s) in the record
The
field(s)
in
are
displayed
character
in the field(s)
aren't
the record
the
is
on
a light background).
is
DSPATR
Characters
A
DSPATR
the
and
causes control characters to be placed in the first position before
first position
after
a field.
(the
control
characters
the screen). Keep the following in mind when you code the
(columns 39-44):
Other
parameters
The
character
displayed.
displayed with images
underlined.
positions;
keyword
do not
appear
Location field
CA
is
on
1.
The position immediately before, and immediately
You control whether a position
Position field (columns 42-44)
two or more fields with display
2.
blank.
in the
If
- A blank position must precede the first field.
1,
-
-
3.
Rules (1)
column
At
least one blank position must be between each two fields.
One
column 80
blank position must follow the last field.
and
(2)
of
the previous line must be blank.
are
valid regardless
is
blank or not by what you specify
and
the Length field (columns 30-34).
attributes
of
the
follow in succession:
If
number
BL, etc.) you specify.
uNote:
Make
sure the positions in which display
attributes
cleared before a new screen format is written to the screen.
are
not cleared, the display
attributes
will apply to the new format. (You
clear the positions desired by writing a blank record to
the
Assume, using
been written to the
the field to
separators
4, column 80 has not been cleared. Although not specified,
field will have column separators.
R
INVFILE
PRTNO
Data
Definition Statements,
STARTING
5D B
01
01
AT
that
LINE
INVFILE
value
of
is
5 or
Valid Combinations
PMT
(message)
Of
HI,
RI, and
UL
You cannot specify
explicitly in
statement
the
in combination with a record description statement. You can,
the
HI,
RI,
and
same field description
however, specify any combination
If
you wish to cancel
code the
CA
(for cancel)
and then code
The
PMT
(for
2
of
the
line
The
prompt is cleared when
The
prompting message
screen.
the
desired
prompt)
The
the
defaults specified in a record description statement,
attribute
HI,
RI,
keyword allows you to display a prompting message on
prompt appears when
the
is
displayed on
UL
attributes for the same field, either
statement
of
two
of
in
the
desired field description statement,
and/or
UL
cursor leaves
the
second physical display line
or in a field description
these attributes.
attributes.
the
cursor enters the field.
the
field.
starting in position 1 and continues on the following lines depending on length
the
message.
of
The
required
length
valid in
The
message must be within single quotes (
within
parameter,
of
200
character
the
message.
the
message must be coded twice
message, can be any message, with a maximum
positions. Any displayable
'message').
('
').
character
and spaces
Any single quotes
are
rINote:
SHIFT
(codes)
The
SHIFT
letter C
keyboard conditioning for each position in
The required
character
2-
24
IBM 5280 COBOL Programmer's Guide
The
prompt message
keyword
is specified for
parameter,
position in the field.
is
cleared when the cursor exits the field.
is
required in field description statements in which the
Data
Type. This keyword allows you to program the
the
field.
codes,
is
a string
The
of
characters, one for each
following characters
are
valid:
Field Description
Character Meaning
Statement
A Alphabetic shift - Any character can be entered. The shift is
positioned to the lower symbol on each key on all keyboards. The
operator can use the Shift key to enter
the
upper symbol on the
keys.
D Digits only -
is
positioned to the lower symbols on typewriter keyboards and
positioned to the upper symbols on both
proof keyboards. Negative numbers
over the last digit
Only the digits 0 through 9 can be entered.
data
entry keyboards and
are
displayed with the sign
of
the number. The operator cannot override the
The
shift
shift.
H
Hexadecimaland only the numbers
be entered.
Each
character
0 through 9 and the letters A through F can
No
shift key operation
position requires two keystrokes
is
required on data-entry
keyboards.
N Numeric shift - Any
positioned to the lower symbols on typewriter keyboards and
positioned to the upper symbols on both the
character
can be entered. The shift is
data
entry keyboards
is
and the proof keyboards. The operator can change the shift by
using the Alphabetic Shift key.
V Right
half
only - Only the characters
that
are defined
at
system
generation can be entered. The shift is positioned to the lower right
symbols on World
Trade
keyboards. The shift key allows entry
the upper right symbols.
W Right
half
shift - Any
positioned to
character
the
lower right symbols on the World
can be entered. The shift
Trade
keyboards. The operator can change the shift by using the shift
keys.
tINote: V and
than two shift positions (such as the
use these
keyboards or an unrecoverable error will occur
X Alphabetic only -
hyphen, and space can be entered.
W should be used only for those keyboards with more
data
types in programs
Only the letters A through
Katakana
that
are
The
shift
keyboard). Don't
to be executed on other
at
execution.
Z,
comma, period,
is
positioned to the
lower symbols on all keyboards. The shift cannot be changed by
the operator.
Y Numeric only - Only the numbers 0 through 9, comma, period,
plus, minus, and space can be entered. The shift
is
positioned to
the lower symbols on typewriter keyboards and to the upper
symbols on both the
data
entry keyboards and
the
proof keyboards.
The shift cannot be changed by the operator.
is
of
Keyword Conflicts and Compatibilities
Some keywords for field description statements cannot be used in combination
with certain entries in the
Usage field, certain entries in the Data Type field,
or certain other keywords and parameters. The valid and invalid
combinations
The Xs represent invalid combinations. For example, in figure 2.7
CHECK(DR)
field). Also notice
parameters for
are
indicated in the following charts.
(Part
cannot be used for output fields (coded with 0 in the Usage
that
CHECK
combining
is
invalid. Also,
DR
(data required) and BY (bypass) as
DR
cannot be specified twice for the
2),
same field.
Chapter
2.
Transaction
I/O
- Screen Definition
2-
25
Keyword
PMT
SHIFT I X
Data
Usg.
Fld.
Field
Type
Entry
Check
Parameters
I I
I I I
S C Y
X .
X
B
1*R E
E F B Z L I T T
I
I I
0
I
I X I
I
D H N
A C
I
X . X X X X X X X X
I
S W X Y V
L A A B B Y F M F M R R R
C D
Keywords
S
I
H
P I
I
M F
I
X
I
X
I
*BYI refers to
CHECK(BY)
an indicator specified.
Figure 2.7
Check
Parameter
LC
AD
AS
BC
BY
BY1*
DR
FE
ME
MF
RB
RZ
RL
*BY 1 refers to
Usg.
Fld.
I I
I
I
0
A C
X
X
X
X
X
X X
X X X
X
X
X X X
X
X X X X X X X
X
X
X
X X X X X X X X X X X X
CHECK(BY)
an indicator specified.
used as the exclusive entry in Editing field on a secondary line with
(Part 1 of
Data
Type
Field
Entry
S W X
D H N
X X
X X X X X X X X X X X X X X X X X X X
X
2). Keyboard conflicts and compatibilities
Y
L A A
V C D S C
X X
Check
X X
X X X
Parameters
B
B B Y D F M M
y
1*R E
X
X X
X X
X
X X X X
X X X X X
used as the exclusive entry in Editing field on a secondary line with
Keywords
S
H
I
Ip
I
F
R
R R
B Z L
1M
IT
I·
I·
I·
I·
Ix
I.
I·
I·
I.
I.
I·
I·
I.
T
X
E F
X
2-
26 IBM 5280 COBOL Programmer's Guide
Figure 2.7
(Part
2 of 2). Keyboard conflicts and compatibilities
Chapter 3. Transaction
I/O
-Writing the COBOL Program
Summary
This chapter provides information on transaction I/O - the
organization in the
data
Subjects covered include:
• A description
•
• How to code the statements needed to obtain
• A coding example
• A coding example showing the use
To use the information given in this chapter, you'll also have to refer to the
following chapters:
•
•
of
COBOL Transaction
This
chapter
program in figure 3.2.
are from
the program:
1.
The program writes a screen in which an operator will enter
employees.
2.
The program checks
updates
writes
The following sections provide a guide to writing a
transaction
discussed in
etc.). For detailed information on the syntax and rules
statements used, see
data
set
IBM
5280
COBOL
between an operator
transaction
CLOSE,
I/O
error processing, with an example
and use
example, codes returned when the operator presses a command key).
Bypass).
Chapter
and how it affects the operations
Chapter
(DDS)
I/O:
READ,
of
the
1,
introduces transaction
2, which describes how to code
that
design the screen and edits
I/O
will explain transaction
the
example in figure 2.3 in
the
employee master file with
an
error message and allows the operator to correct the data.
I/O
and some
the
text
at
a work station and a
and
coding examples
the
FILE-CONTROL
and
WRITE
Status
Key.
of
a program using transaction
Statements
(The
Data
the
data
entered for errors; if no errors
of
the
are
referenced in figure 3.2 with keyed numbers
the
IBM
5280 COBOL Language Reference.
language
statements.
I/O
of
I/O
Definition
Chapter
COBOL
that
permits
COBOL
of
the
I/O
statements needed for
paragraph,
of
an
exception/error
return
of
indicators and
and summarizes the keyboard
your program.
the
Data
Definition
the
operator entries.
using
the
example
Statements
2.)
Here
is
the
data.
If
an error
COBOL
statements used.
of
the
program.
and
the
information (for
I/O.
CHECK(BY)
of
the
used by this program
a brief
summary
data
are
is
found, it
program with
Statements
the
COBOL
exchange
OPEN,
procedure
Statements
COBOL
on new
found, it
(11,6,
of
(for
of
FILE-CONTROL
Paragraph
The entries in the
SELECT file-name ASSIGN
ORGANIZATION
[FILE
[ACCESS
[CONTROL-AREA
STATUS
FILE-CONTROL
IS
IS
MODE
IS
IS
Chapter
TRANSACTION
data-name-3]
SEQUENTIAL]
data-name-4]
TO
3.
Transaction
paragraph
WORKSTATION
I/O
for transaction
- Writing the COBOL Program
[n]
I/O
are:
3-
1
OPEN
WORKSTATION
n
is
an
integer
follows:
480 for
960 for
1920 for
CTNotel:
CTNote
2:
must
be
execute. For example,
systems
specify
480-character
An example
Note
TRANSACTION,
The
this chapter.
"Return
The
results in
with
480,
that
FILE
OPEN
the
that
the
480-character screen.
the
960-character
the
If
you
don't
The
screen size
at
least the
that
support 480-, 960-
the
data
of
the
for transaction
STATUS
The
Information".
statement
the
file being in
1-0
phrase, as shown in figure 3.2
indicates the device
specifies one
1920-character screen.
specify
of
same
if
you specify 1920,
program will execute only on stations
stations.
FILE-CONTROL
and
ACCESS
clause is explained under
CONTROL-AREA
determines
of
screen.
n,
a screen size
the
work station on which a program
size specified by
and
I/O,
ORGANIZATION
an
OPEN
is
a 5280
the three sizes
1920-character
paragraph
is
always
clause
the
availability
mode. You must always open
data
of
of
1920
n.
Otherwise,
the
program will execute on
is
SEQUENTIAL.
"I/O
is
explained
of
at
m.
station.
work station screens as
characters
data
that
shown in
is always
Error
the file, and,
is assumed.
is
to execute
the
program will not
stations;
support
Processing" later in
under
if
you
EJ
in figure 3.2.
the
section
if
successful,
the
file
WRITE
FORMAT
Clause
The
WRITE
in your program generated by
are
copied into
at
II.
3.2
The
format
WRITE
[FROM
[FORMAT
[STARTING
[INDIC
I [INDICATOR
I [INDICATORS
identifier-4]
CTNote: Always specify the above clauses in
syntax
statement
the
of
the
record-name
identifier-1]
IS
[IS
fOf
the
\VRITE
places onto the work station screen a set
Data
Definition Statements.
program
WRITE
literal-2]
AT
statement
LINE
at
compilation,
literal-3]
is as follows:
I ARE]
[IS]]
[ARE]]
statement
are
given in detail in the 5280 COBOL
Language Reference.
The
FORMAT,
explained in
The
FORMAT
Data
Definition
is
not specified, the last specified format
WRITE
specify
statements
the
STARTING
the
next three sections.
clause designates the screen format, as defined by a set
Statements,
is
writing the same format to the screen, you need to
FORMAT
clause only on the first
AT
LINE,
that
is
to be written to the screen.
as
shown in
the
order shown.
and
INDICATOR
is
written to the screen.
WRITE
the
in
the series.
of
data-items
The
statements
example in figure
The
ruies
and
clauses
are
If
FORMAT
If
a series of
of
3-
2 IBM 5280 COBOL Programmer's Guide
In the example,
of
different screen images, as explained below.
At
EI
and
into the program:
PROMPT.
The
Data
m through
COBOL
The
these formats as follows:
•
• The
Lff'Note: A
subsequent
therefore coded
program
WRITE
The
prompting
the
the
"ERRMSG3"
when the program finds an incorrect entry by
READ
FORMAT
II
in figure 3.2, six sets
EMPRECD,
Definition
m.
statements
WRITE
WRITE
fields in which
WRITEs
WRITE
Statements
They
cause
at
compilation.
at
with FORMAT
the
operator to enter employee
with FORMAT
the
with
at
m,
statement
is
issued. In
at
m,
III,
was specified in each
of
ERRMSGl,
that
the
records
m, m,
IS
IS
operator is to
FORMAT
m,
and IB, write error messages to
must be executed
the
1m,
II,
WRITE
Data
Definition
ERRMSG2,
define each
at
EI
IB,
lEI,
"PROMPT"
"EMPRECD"
enter
IS
"ERRMSG1",
example shown in figure 3.2,
and
m·
of
and
II
and
lEI
at
data.
at
employee
after a WRITE
to allow
Statements
ERRMSG3,
the
formats
to be generated into
each reference one
lEI
writes a message
This
is
followed by
lEI.
This
data.
"ERRMSG2"
the
operator.
before a
the
writing
were copied
are
shown
statement
and
the
screen
READs
and
at
the
of
the
writes
are
STARTING AT
INDICATOR Clause
LINE
READ
Clause
The
STARTING
field you specify in the
line on
Field"
In
boolean table
INDICATOR
chapter.
For
see the
"INDICATOR
The
operator. When the operator has completed entry
exit key, control resumes
The
READ
The syntax and rules for writing a
the same as for
Reference
the
for information on how
the
INDICATOR
the
rules to follow in coding
5280 Language Reference manual under
READ
format
file-name
for details.
AT
LINE
clause
is
optional. Together with
Data
Definition
screen
of
the
data
being written. See
the
clause, identifier-4 specifies a data-item which is a
of
one or more elements. For a coding example using the
clause, see the section
the
Clause".
statement
of
the
SEQUENTIAL
is
normally issued when
at
the next
READ
RECORD
statement
[INTO
I/O.
Statements,
starting line is determined.
"INDICATOR
INDICATOR
data
COBOL
is:
identifier-I]
READ
See the 5280 COBOL Language
statement
statement
the
location
it determines
Chapter
"OCCURS
and
2 under "Location
Example"
clause with a data-item,
is
expected from the
pressed
following
for transaction
the
later
Clause"
the
appropriate
the
I/O
starting
in this
and
READ.
are
Chapter
3.
Transaction
I/0
- Writing the COBOL Program
3-
3
Sequence
of
Transaction
I/O
Statements
Don't
issue two
between. A
before a subsequent
The
READ
operator.
must
WRITEs
READ
be issued whether or not a response
in your
must always be issued
WRITE
can
program
be issued.
without executing a
after
a
WRITE
has been issued
is
expected from
READ
in
and
the
Clearing the Screen with
CLOSE
You normally expect a response when one
has been defined for both
Usage field
the
READ
entered by
You normally
for
associated
followed by a
is executed, your
output
the
only.
Data
READ
of
the
operator.
don't
That
Definition
input
and
associated
program
expect a response when all
is,
an
before
Data
can
0 has been specified in
Statements.
another
WRITE
A
WRITE
the
data
default)
by
the
In
m,
Therefore,
The
program. Once a
by your
clears all
being written,
by
example shown in figure 3.2, when
or IB, all information on
the
CLOSE
statement
program
data
and
the
FORMAT
screen with
detaches
transaction
before
again
on
the
screen in lines following
then
writes
clause.
the
lines
the
original
the
file
is
loading
of
output.
WRITE
work
closed,
That
Definition
process
Nevertheless,
the
data
an
that
follow
format
station
it
the
program.
the
fields written to
is, a B has been specified in
Statements.
any
command
of
the
fields have been defined
the
Usage field(s)
the
WRITE
can
be issued.
the
defined
error
is rewritten
cannot
(either
message is written
the
message line
associated with
be opened again
the
After
key codes or
starting
explicitly or
at
BJ.
the
screen
the
of
must
line
at
are
data
the
be
of
m,
erased.
I/O
Error Processing
Status Key
3-
4 IBM 5280
COBOL
This
procedures in handling possible
The
your
TUBE-STAT
It
is recommended
COBOL
errors
destructive
If
neither a Status
later
message in the
format
placed in
See Appendix B for a complete list of
Sta
tus Key and their meanings.
Programmer's Guide
section discusses
Status
Key is a
program
may
in this section)
and
name
in B in figure 3.3
that
program
92nn will
the
check
go undiscovered by
and
difficult to diagnose.
Key nor
status
appear
Status
the
use
of
2-character
in
the
you define a
the
contents
an
EXCEPTION
is
present
line
at
the
in
the
Key
had
it been present.
the
Status
Key
and
Exception/Error
transaction
data-item
FILE
STATUS
later
Status
after
the
program, producing results
and
an
top of
status
line; nn is
I/O
errors.
you define in
clause, as shown for
in this
chapter.
Key for all files
each
I/O
/ERROR
error
occurs,
the
screen. A message identifier in
the
values
the
that
the
code
the
Data
Division
and
that
your
request. Otherwise,
that
are
both
procedure (described
program
that
can be placed in
will display a
would have been
the
of
the
Coding the Status Key
To code the status key:
1.
Relate
below and in
FILE
2.
Code a data-item in Working Storage Section or the Linkage Section as
shown below and
77
FILE
STATUS
fJ
in figure 3.2:
STATUS
TUBE-STAT
and a data-item in the
IS
TUBE-STAT
at
D in figure 3.2:
PIC
XX.
SELECT
clause as shown
After each READ,
posted in the status key shows the outcome of the operation. Your program
can look
The return codes for transaction
SEQUENTIAL
Appendix
Exception / Error Procedures
You can also code a procedure to handle errors using the
EXCEPTION
The procedure,
exception occurs
procedures to diagnose the error, and take subsequent action in consideration
of the error.
is
in open status. Therefore,
has already been closed, or was never opened, then the
EXCEPTION/ERROR
Status
The
EXCEPTION/ERROR
in
Chapter
Example Using Status Key and
In the example in figure 3.3, the procedure
control each time a nonzero return code
procedure displays a message and the value in the status key, and then stops
the run.
WRITE,
at
the status key, and then take the appropriate action.
I/O.
B.
/ERROR
WORK-STATION,
on
SCREEN-FILE-PR3.
The
EXCEPTION/ERROR
Key value
USE
FOR
ERROR
of
92.
DEBUGGING
9.
Procedures
OPEN,
The return codes and their meaning are given in
declarative, as shown
if
procedure
procedures) and other debugging aids
and
CLOSE
I/O
are
the same as those for
at
takes control each time an error or
You can include code in the
procedure
any operation
is
not executed. COBOL will return a
declarative (coded before the
is
attempted against a file which
WORK-STATION
is
placed in the status key. The
operation, a return code
I!I
and and
II
in figure 2.3.
is
used only when a file
are
described
at
I!I
receives
Return
Information
Two different types
after a transaction
• Attribute Data Area, which provides information on the status
terminal which loaded your program. You will probably need this
information only when (1) your installation has different size (1920-,
960-,
and/or
know the size
screen images.
of
information can be returned to a COBOL program
I/O
operation in the following areas:
of
the
480-character) screens and (2) your program needs to
of
the screen
at
the
data
station to which it
is
writing
• Work Station Control Area, which contains a special code when control
is
returned to the COBOL program from the work station. The code
indicates which function or command key the operator pressed. The
command keys and their corresponding codes are given in figure
1.4 in Chapter
1.
Chapter
3.
Transaction
I/0
- Writing the COBOL Program
1.3
and
3-
5
Attribute Data
The
work station control
area
and
the
attribute
data
area
are
optional.
If
used, you code
them
as
data-items
in your
program
according to the guidelines
given in
the
following sections.
You
can
get information on a
terminal
status
after
each transaction
I/O
operations as follows:
1.
Code
an
entry
under
SPECIAL-NAMES
equating
ATTRIBUTE-DATA
to a mnemonic
name
as shown below
and
at
II
in figure 3.2:
ATTRIBUTE-DATA
IS
TERMINAL-INFO.
2.
Code
data
description entries in
the
WORKING-STORAGE
SECTION
with
the
characteristics
shown in
the
example below
and
in figure 3.2
at
g.
01 WSTATION-INFO.
02
TTYPE
PIC
x.
02
SSIZE
PIC
x.
02
LOCATION
PIC
x.
02
ON-OFF-LINE
PIC
X.
02
ALLOC-STATUS
PIC
X.
02
INPUT-STATUS
PIC
X.
02
DATA-STATUS
PIC
X.
02
INQ-STATUS
PIC
x.
Data-item Value returned
Meaning
TTYPE
D
Display
SSIZE
1
1920 Characters (24 x
80)
2
960 Characters (12 x 80)
3
480 Characters (6 x 80)
LOCATION
L
Local
ON-OFF-LINE
0
Online
ALLOC-
A Allocated to this program.
STATIIS
INPUT-
N Input
is
not allowed.
STATUS
DATA-
STATUS
N
No data
is
pending.
INQ-STATUS N
Terminal
is
not
in
inquiry mode.
Figure
3.1. Explanation
of
values
returned
in
the
ATTRIBUTE-DATA
area
3.
At
the
appropriate
point in
the
COBOL
program,
code
an
ACCEPT
statement
to access
the
data.
In
the
example
at
1m,
the following
statement
was coded:
ACCEPT WSTATION-INFO
FROM
TERMINAL-INFO.
The
logic in
the
statements
that
follow
the
ACCEPT
statement
in
the
example causes a message to be issued
and
the
run
to be stopped
if
the
work
station
that
loaded
the
COBOL
program
does not have a 1920-character
display screen. (See
the
section
"FILE-CONTROL
Paragraph"
earlier in
this
chapter
for the rules on specifying screen size.)
3-
6 IBM 5280 COBOL Programmer's Guide
Work Station Control Area
The work station control area tells the COBOL program which command key
the operator pressed; this information
To build a work station control area:
1.
Relate a data-item and
shown below and
CONTROL-AREA
2.
Code an area in the
item as shown below and
01 WSTATION-CONTROL-AREA.
03
03
The value returned in
the record
key, or a number indicating one
1.3
The program
code
is
exited after the operator presses the appropriate system function
and 1.4 in Chapter 1 for a description of these keys.
in
the example shown in figure 3.2 checks the command key
at
m after each READ.
CONTROL-AREA
at
II
in figure 3.2:
IS
WSTATION-CONTROL-AREA
Data
Division using the data-item as a
at
II
COMMAND-KEY
FILLER
COMMAND-KEY
is
provided after a
in the
in figure 2.3:
PIC
PIC
is
either 00 (a normal return) when
of
the COBOL command keys. See figures
READ
SELECT
X(2).
X(10).
operation.
clause as
01
level group
Transaction
I/O
Examples
The examples
• Interactive entry and processing between an operator and a COBOL
• The use
in
this section show:
program. The example shows
coded; explanatory text
of
the
Example: Interactive Entry and Processing
The example in figure 3.2 writes a record to the screen, checks the response
when the subsequent read
employee master file.
The Data Definition Statements for
Chapter 2 under "Example
5280 diskette devices. The chapter provides examples
I/O,
and some considerations you must make in
I/O
routines, namely:
of
the statements
• Choosing a file organization (sequential, relative, or indexed)
• Choosing the access method (sequential or random)
• Assigning
• Sharing files among more
data
sets and devices to file statements in the program
than
one program
• Guidelines and examples in coding routines to create, read, and update
the three types of file organizations
A
COBOL
I/O
operation
that
transmits
data
to or from main storage involves
three elements:
• The COBOL statements
• An access method
• A file on an actual device on which the operation
To perform a diskette
I/O
program to make the operation possible.
• The
FILE-CONTROL
that
define and request the operation
that
performs the operation
is
performed
operation, you must code several statements in your
Some of these statements are:
paragraph, which relates your file to the diskette
device, and describes the access mode, file organization, and other
factors relating to the file.
• The
•
The remainder
OPEN
and
CLOSE
verbs in the Procedure Division.
the environment necessary to transmit
CLOSE
Before attempting to transmit
you should always issue a
an intermediate buffer
READ,
Division
you specify in the
completes all unfinished
CLOSE
is
transferred.
WRITE,
that
REWRITE,
cause records to be transmitted either to or from the files
ASSIGN
of
the chapter provides more detailed information on the items
data,
and
clause.
I/O
you must always issue an
to ensure
DELETE
data
to and from a device;
operations.
that
any
verbs in the Procedure
OPEN
data
remaining in
builds
OPEN;
just summarized.
File Organization and Access Method
You define a file organization and an access method in the
paragraph
of
your program. The types
of
file organizations and access
methods you can define are:
• Sequential, for which one access method
this organization, you specify
the
FILE-CONTROL
ORGANIZATION
paragraph
is
possible: sequential. For
of
your program.
Chapter
5.
Diskette
IS
FILE-CONTROL
SEQUENTIAL
Input/Output
in
5-
1
Random Access Method
Sequential Access Method
Sequential Organization
• Relative, for which two access methods
are
possible: sequential
and
random. For this organization, you specify
ORGANIZATION
IS
RELA
TIVE
in
the
FILE-CONTROL
paragraph
of
your program.
• Indexed, for which two access methods
are
possible: sequential and
random. For this organization, you specify
ORGANIZATION
IS
INDEXED
in the
FILE-CONTROL
paragraph
of
your program.
As stated, you
can
specify one
of
two access methods, depending on the file
organization: sequential
(ACCESS
IS
SEQUENTIAL)
or random
(ACCESS
IS
RANDOM).
For random access,
the
order
of
reference to a record
is
determined by a value
you specify in your program. For records with a relative organization, this
value
is
called a relative key; for records with
an
indexed organization, this
value
is
known as a record key.
For sequential access, the order
of
reference to a record
is
determined by
the
position
of
the record in
the
file.
That
is, records
are
read
or
written serially
as follows:
• For files with a sequential organization, according to their physical
location.
• For files with a relative organization, according to their relative key.
• For files with
an
indexed organization, according to their record key.
In
the
example
that
follows, the
term
current record pointer
(CRP)
is
used to
explain
the
relative position
of
a record in a file
after
an
OPEN
or
READ
verb
is
executed.
The
concept
of
the
CRP
applies when
the
sequential access
method is used for files with sequential, random,
or
indexed organizations.
OPEN
INPUT
READ
Read
record
READ
Read
record
2
•
•
•
Read
record
X
Rewrite
record
X
End-of-file
occurs
CRP=record
CRP=record
2
CRP=record
3
CRP=X+1
CRP=X+1
READ
REWRITE
READ
READ
Fails
(status
Key
94)
No
CRP
In order for a
READ
to be successful, the previous
OrEN
or
READ
for
that
file must have been successful. You can determine whether or not a
READ
or
OPEN
is
successful by examining
the
Status
Key.
(The
Status
Key
is
a
data-item
coded in your program as described under
"Status
Key"
under
"Error
Processing Options"
later
in this
chapter.)
When all
the
records in a file
are
to be processed, using
the
sequential access
method will be faster
than
using the random access method.
In files with a sequential organization, records
are
placed into the
data
set one
after
the other: the first record entered occupies the first position in the file,
5-
2 IBM 5280
COBOL
Programmer's Guide
Relative Organization
the second occupies the second position, and
is
the same order. The first record
read, then the second, and so on.
so
on. Records
are
retrieved in
In files with a relative organization, a relationship exists between records and
of
their positions in the file. The relative position
a record might be equal to a
program counter or a field value. The relative position might also be derived
by a formula or conversion technique.
The following is an example
of
a file with relative organization:
Indexed Organization
Employee
1000
In this example, a company has a maximum
assigned employee numbers
employee
conversion technique
Employee
1001
2
Employee
1002
3
of
1000 through 1999. Record 1 contains
1000, record 2 contains
is
simply to take the employee number and to subtract
Employee
1003
4
of
1000 employees, and they
data
on employee 1001, and
5
Employee
1005
6
so
forth. The
are
data
on
999 to obtain the relative record number.
The file does not need to be created sequentially or read sequentially, although
either
is
quite possible. Notice
either no employee was ever assigned
the company.
In
either case the storage space
that
record 5
that
is
a null record. This
number, or the employee has left
is
unused.
is
because
In indexed files, a relationship exists between a record and a key you designate
in the record. The key for each record must be unique. This allows a program
to refer to each record by its key.
COBOL supports two types
chapter in the section
of
indexed files. They
are
described later in this
"Processing Files with an Indexed Organization".
Record
Formatting
The format
you allocate
CONTAINS
of
The size
the record as defined in the
the
and
record in
data
BLOCK
an
IBM
5280 system
set as described in
CONTAINS
Chapter
clauses
COBOL
of
the
record as allocated must always be the same.
Chapter
data
set
is
determined when
8.
The
RECORD
don't
affect this format.
program and the size
5.
Diskette
Input/Output
of
the
5-
3
FILE-CONTROI~
Paragraph
You describe your file and assign a diskette device in the
paragraph. Here are some
of
the entries you make in this paragraph:
FILE-CONTROL
SELECT
ASSIGN
["device-address1"[
[INDEX
[SIZE
[SHARE I SHARER]
file-name
TO
DISK
["device-address2"[
nnnn]
"[*volid1.]dsname1"]]
"[*volid2.]dsname2"]]]
•
•
•
aNote:
Other
clauses in the
ORGANIZATION,
and
FILE
STATUS
Manual; some
The
INDEX
are
and
shown in
SIZE
"Processing Files with an Indexed
discussed under
"Sharing
The following text describes the entries
assignment-name entries
FILE-CONTROL
ACCESS
MODE,
clauses. They
the
examples given later in this chapter.
clauses
are
Files".
of
the
ASSIGN
section include the
RECORD
are
described in the Language Reference
KEY,
RELATIVE
discussed later in this chapter under
Organization".
SELECT
SHARE
and
clause and the
SHARER
clause.
file-name is the name of the file you specify in the associated File Description
(FD)
Entry.
DISK
tells
COBOL
that
the device is a diskette.
You can optionally specify the following parameters:
device-address 1
address
volidl
of
is
the identification given when the volume was initialized with the
is
the physical address (4000 or 4400, for example) or logical
the device on which the diskette must be mounted.
diskette initialization utility.
dsnamel
is the name given to the
data
set when it was allocated, usually
assigned with the diskette label maintenance utility.
If
you specify only the required (file-name) parameter, the operator must
respond to the following prompt
is
loaded.
that
appears on the screen when the program
KEY,
are
Enter
Dataset
Device
Owner
No
prompt will be displayed under the following conditions:
• You specify device address
• You specify a
Otherwise, the operator can respond to this prompt as described under
"Prompts
5-
4 IBM 5280
COBOL
Programmer's Guide
the
following
name:
address:
id:
VALUE
information
Press
OF
program when the volume
for Diskette Files" in
for
1,
ENTER
volidl
file
and dsnamel.
file-name
owner-id clause (described below) in your
is
protected.
Chapter
8.
FD Entry -VALUE OF OWNER-ID Clause
Sharing Files
You can write a
entry. This clause allows you to control the use
by
the
operator.
The operator must fill in
(2)
if
you don't code a
your program.
Whether
accessibility byte. This byte
the diskette label maintenance utility. See Utilities Reference/Operations
Manual
The
In the above example
initialized with the diskette initialization utility (also described in the
or
for detailed information on how to protect a volume.
VALUE
VALUE
not a volume is protected
OF
owner-id clause
FD
file-name
VALUE
LABEL
OF
OWNER-ID
the
Owner-id field (1) if
VALUE
is
OF
OWNER-ID
OF
set under
RECORDS
the
owner-id
clause in the field description
of
protected diskette volumes
the
volume is protected
owner-id clause under the
is
determined by the setting
the
"modify volume label" option
is
coded as follows:
IS
"BELL"
ARE
STANDARD.
BELL
was specified when the
FD
entry in
of
the
data
set was
Utilities
Reference/Operations Manual).
Sharing files refers to the use
the same time. The ability
as your program depends on how the following
are coded in the two programs:
of
a file
by
more
than
one program executing
of
another program to use a file
COBOL
at
the same time
language statements
(FD)
and
of
at
Unshared Files
Shared Files
• The
• The
In general, you can code your program
• Unshared
•
•
When a file
both for reading and for writing.
file, the requesting program will receive
indicates the file
specifically specify otherwise, as will be shown
When you specify
paragraph, another program can access the file for reading
update
When you specify
be accessed by more
and write to the file.
SHARE
OPEN
INPUT,
Shared
Shared
it.
option in the
verb, in which the modes
or
EXTEND
read
read/write
is
unshared, only the program
is
already opened. Files
SHARER
SHARE
than
SELECT
mode can be coded.
If
another program
(for shared read) in the
(for shared read and shared read/write) files can
one program
clause.
OUTPUT,
so
that
diskette files are:
that
Status
are
always unshared unless you
later
at
a time. All programs can both read
1-0
opens the file has access to it,
attempts
Key value
in this chapter.
FILE-CONTROL
(for update),
to access
of
93. This
data,
but cannot
the
Chapter
5.
Diskette
Input/Output
5-
5
When Files Can Be Shared
LI'Note: You cannot add records to files with indexed organizations if those files
IF
As
the Share
SHARE
SHARE
SHARER
SHARER
Whether or not a second program can access a file that has already been
opened depends on:
The mode
(INPUT,
OUTPUT,
1-0,
or
EXTEN
D)
coded with
OPE'"
the first program.
• The share option (blank,
clause
of
the first program.
• The mode coded with
•
The
share option (blank,
clause
of
the second program.
SHARER,
OPEN
SHARER,
or
SHARE)
in
the second program.
or
SHARE)
coded
in
the
coded in the
SELECT
SELECT
are being shared with other programs.
Figure
OPEN
A PROGRAM USES ...
O~ion:
5.1
shows the combinations
modes when files
~s
the
OPEN
1-0
INPUT
1-0
INPUT
are
Mode: As the Share Option: As the OPEN Mode:
of
the
SHARE/SHARER
to be shared among programs.
OTHER PROGRAMS CAN USE ...
THEN
SHARE
SHARE
SHARE
SHARE
or
SHARER
or
SHARER
1-0
1-0
options and
or
INPUT
or
INPUT
INPUT
INPUT
in
the
Figure 5.1. Valid combinations
When
take
organization,
take
No Sharing with OUTPUT and
The
OUTPUT
exclusive use and cannot be shared while they
subsequently opened in another mode such as
options on the
shared.
I/O
Error
Processing
Four options
detecting and handling
• The
• The
•
• The
This section explains the use of these options; the syntax and rules for coding
these options is given in detail in the
a file
is
opened in the
place.
When
READ,
place.
EXTEND
share options
or
EXTEND.
SELECT
are
available determining the outcome
Status
Key
EXCEPTION
The
Invalid KEY clause
AT
END
a file
is
WRITE,
Modes
are
ignored when
clause are then used to determine how the file will be
I/O
Clause
of
SHARE/SHARER
INPUT
mode, then only
opened in the
REWRITE,
the
1-0
mode, then, depending on
and
OPEN
verb specifies a mode
and
READ
DELETE
OPEN
modes
operations can
the
operations
can
of
Files opened in these modes are always opened for
are
so
opened.
INPUT
of
If
the file
or 1-0, the share
an
I/O
request, and for
is
errors:
/ERROR
Procedure
5280 COBOL Language Reference.
file
then
5-
6 IBM 5280 COBOL Programmer's Guide
Status
Key
The
Status
your program and name in the
figure 5.2,
defined in the
Key
is
a 2-character data-item you define in the
PRINT-FILE-STAT
WORKING-STORAGE
FILE
at
STATUS
II
and
SECTION
Data
clause. In the example in
UPDATE-FILE-STAT
at
II.
Division
at
Bare
of
EXCEPTION / ERROR
Upon return to the COBOL program, the
defines the status
It
is recommended
COBOL program check the contents after each
errors may go undiscovered by the program, producing results
both destructive and difficult to diagnose.
If
neither a
in the next section) is present and an error occurs, the program will display a
message in the
the format 92nn will precede the message;
placed in the
See Appendix B for a complete list of the values
Status
Key, their meanings, and a cross-reference between
and the message identifiers as displayed in the
Status
Status
Status
of
the last request on the file.
that
you define a
Key nor an
Line
Key had it been present.
EXCEPTION/ERROR
at
the top
Status
Status
of
the screen. A message identifier in
Key contains a value
Key for all files
I/O
request. Otherwise,
nn is the code
that
can be placed in the
Status
Line.
and
that
that
procedure (described
that
would have been
Status
Key values
Procedures
You can also code a procedure to handle errors using the
EXCEPTION
an error occurs on
ERROR/EXCEPTION
messages, and stops the run.
The
EXCEPTION
status. Therefore,
already been closed, or was never opened, then the
procedure is not executed. COBOL will return a Status Key value of 92.
/ERROR
declarative. In the example in figure 5.2, each time
The following guidelines apply in reading records from a file with a relative
organization:
1.
Use the
2.
Specify
logic error will occur, setting the
3.
Records in a file with a relative organization can be read sequentially
(ACCESS
randomly
For sequential access, reading a relative file
except only successive, non-null records are returned. Moreover, if you
specify
number will be returned in
For random access, you must place a relative record number in the key
data-item before reading the record. An invalid key condition occurs if
either a null record is found (the
past the end-of-file or the relative key
READ
INPUT
verb to access the records.
or 1-0 mode in the corresponding
IS
SEQUENTIAL
(ACCESS
RELATIVE
Status
is
specified in the
IS
RANDOM).
KEY IS in the
the
relative key data-item.
Status
OPEN.
Otherwise, a
Key to 92.
SELECT
SELECT
is
like reading a sequential file,
clause, the relative record
clause) or
Key is set to 23), or the record
is
0, (the
Status
Key
is
set to 24).
is
Updating a Relative
File
The following guidelines apply in updating records in a file with a relative
organization:
1.
The file
2.
Specify
will occur on a subsequent
Status
3.
Records in a file with a relative organization can be read sequentially
(ACCESS
randomly
For sequential access, updating
always preceded by a READ.
preceding
that
is
to be updated must have previously been created.
1-0
mode in the corresponding
READ,
Key to 92.
IS
SEQUENTIAL
(ACCESS
READ
IS
RANDOM).
statement was unsuccessful, the
OPEN.
WRITE,
is
specified in the
is
done with a
If
there
is
no preceding READ, or the
Otherwise, a logic error
or
REWRITE,
SELECT
REWRITE
REWRITE
setting the
clause) or
or DELETE,
or
DELETE
will fail, setting the Status Key to 92.
For random access, updating
or with a
READ
REWRITE
is
necessary. The following invalid key conditions can occur for
or
is
done only with a
DELETE
WRITE
to a null record,
to an existing record; no preceding
random access:
• No record is found (the
• Duplicate relative record Key (the
when a non-null record
Key in a
WRITE.
• Boundary violation (the
Status
is
Key
found in a file
Status
Key
is
set to 23).
Status
at
is
set to 24).
Key
is
set to 22). This occurs
the location indicated
by
the
Example -Reading
and Updating a
Figure 5.8 shows the required
update a relative file.
5-
18
IBM 5280
COBOL
Programmer's
Guide
Relative
File
input/output
statements needed to read and
•
•
•
SELECT EMPMAS-FILE ASSIGN
ORGANIZATION
MODE
ACCESS
RELATIVE
FILE
STATUS
DATA
DIVISION.
FILE
SECTION.
FD
EMPMAS-FILE
LABEL
RECORDS
COPY
DDS-EMPRECD.
01 EMPRECD.
02
ACREC
02
EMPNO
IS
KEY
IS
ARE
PIC
PIC
•
•
•
WORKING-STORAGE
77
DISK-STAT
77
RKEY
DATA
DIVISION.
SECTION.
•
•
•
OPEN
I-O
EMPMAS-FILE-PR3.
•
•
•
READ-MASTER.
SUBTRACT
READ
INVALID
MOVE
REWRITE
INVALID
1000
EMPMAS-FILE
MOVE 0 TO
MOVE 1 TO
SCREEN-RECORD
EMPRECD
MOVE 1 TO
MOVE 0 TO
FROM
KEY
CONTINUE
KEY
CONTINUE.
•
•
•
CLOSE EMPMAS-FILE.
RELA
TO
DISK
IS
RELATIVE
RANDOM
IS
RKEY
DISK-STAT.
STANDARD.
X(00002).
S9(OS)V.
PIC
XX
VALUE
PIC
9999
EMPNO
GIVING RKEY.
ERROR-FOUND, INVALID-EMPNO.
TO
EMPRECD.
INVALID-EMPNO
VALUE
TIVE
SPACES.
ZERO.
Organization
Figure 5.8. Example
of
processing files with a relative organization
Chapter
5.
Diskette
Input/Output
5-
19
(This page
is
intentionally left blank.)
5-
20
IBM 5280 COBOL Programmer's Guide
Processing Files with an Indexed Organization
Figure 5.9 shows the COBOL statements which can
processing.