IBM 5280 Manual

--- -
----
-- ---
- ---
---- -
- -- ---
-----
--_ . -
8L23-0032·1
File No. 85280-24 Licensed
Program
IBM 5280
Distributed Data
System
COBOL
Programmer's Guide
Program Numbers: 5708-CB1(OSIVS)
5708-CB2(DOSIVSE}

--..- -
----
-- ---
- ---
- -. ---
--- ---
-----
--_.-
SL23-0032-1
File No. S52BO-24
Licensed
Program
IBM 5280
Distributed Data
System
COBOL
Programmer's Guide
Program Numbers: 570B-CB1(OS/VS)
570B-CB2(DOS/VSE)

Second Edition (February 1981)
This is a major revision of, and obsoletes, SL23-0032-0.
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 01, modification 00 of the
IBM 5280 COBOL OSjVS Host
Compiler and Library (program number 5708-CB1), and the IBM 5280 COBOL 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 "To The COBOL Programmer".
It is possible that this material may contain reference to, or information about, programming, or
services
that are not announced in your country. Such·references or information must not be
construed to mean
that IBM intends to announce such IBM products, programming, or services
in your country.
Publications are not stocked
at the address below. Requests for copies of IBM publications and
for technical information about the system should be made to your IBM representative or to the
branch office serving your locality.
This publication could contain technical inaccuracies or typographical errors. Use the Readers
Comment Form at the back of this publication to make comments about this publication. If the
form has been removed, address your comments to
IBM Corporation, Information Systems
Division, Dept
26Xj037, 2800 Sand Hill Road, Menlo Park, CA 94025. IBM may use and
distribute any of the information you supply in any way it believes appropriate without incurring
any obligation whatever. You may, ofcourse, continue to use the information you supply.
© Copyright International Business Machines Corporation 1980

To the COBOL Programmer
Before Using This Guide
Scope of the Guide
Before using this guide, you should be aware of the topics covered, the
experience and knowledge you should have to use it, and the other IBM 5280
and host system manuals you will need. It is the purpose of this section to give
you this information; reading the text that follows may save you time.
To use this guide, you should be either experienced or trained in the COBOL
language. The guide is not intended as a tutorial for a beginner wishing to
learn the COBOL language. (The objectives of the guide are given in a later
section.)
The IBM 5280 host compilers for OS/VS and DOS/VSE convert source
programs written in COBOL into load modules executable on an IBM 5280
system.
The information in this guide, together wIth that in the IBM 5280 COBOL
Language Reference, GL23-0031, should provide you with most of the
information you need to write COBOL programs and compile them on the
host system.
The guide also provides information on executing a COBOL program on the
IBM 5280. You will need additional information that is to be found in IBM
5280 publications (in, for example, the Message Manual). A list of these
manuals and their order numbers is at the end of this chapter.
Organization of the Guide
Objectives of the Guide
The information in this guide is presented in the order a 5280 COBOL
program might be coded, compiled, executed, and debugged:
• Chapters 1 through 6 provide rules, guidelines, and examples for writing
transaction I/O, data communications, and printer and other I/O.
• 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 of
a COBOL program; for example: allocating data sets, loading a
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 "Index" for a more detailed listing of topics.
The objectives of the guide and how to use it are given in the sections that
follow.
iii

Writing A Work Station Application
Data Communications
Diskette
I/O
Printer and Other I/O
iv
Three chapters provide information on writing interactive applications using
the 5280 keyboard and other system functions:
• Chapter 1introduces transaction I/O, the Data Definition Statements
(DDS), and the 5280 keyboard. Transaction I/O together with the
formatting and editing capabilities of DDS, provide flexibility and ease
in writing applications that interact with a work station.
• Chapter 2 describes how to implement your screen designs with DDS
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 I/O; these two methods are discussed in Chapter 6.
The exchange of data between two systems over a communications link using
IBM 5280 COBOL programs is called data communications. Chapter 4
covers data communications and has the following information:
• A summary of COBOL data communications capabilities
• The IBM 5280 facilities needed to execute a COBOL program
• The coding information necessary to write a data communications
program.
• An example of a COBOL program using the data communications
facilities
Chapter 5 describes how to write a program using the I/O facilities that allow
the interchange of data between a program and IBM 5280 diskettes. Subjects
covered in this chapter include:
• 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 of
sequential and random access, where applicable, is discussed in relation
to each of the file organizations.
• I/O error processing options
Chapter 6 provides information on:
• Writing data to a printer using SEQUENTIAL I/O
• Using the DISPLAY and ACCEPT verbs in exchanging data between
an operator at a work station screen and a COBOL program
• Using SEQUENTIAL I/O in the exchange of data between an operator
at a work station and a COBOL program.

Compiling a COBOL Program on the Host System
Chapter 7 describes the procedures available for compiling a source program;
it also provides information that can be used for modifying the procedures at
your installation if necessary. Information is given on the data sets required,
the related job control language, and the options available for compilation.
Executing a COBOL Program on an IBM 5280 System
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 data sets
• 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 execution errors
Executing Jobs in Sequence on an IBM 5280 System
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 DE/RPG
program, an assembler program, a system utility program, etc.). You achieve
this linkage with a CALL to a COBOL library routine as described in Chapter
10.
Together with the PROMPT /NOPROMPT option described in Chapter 7,
this facility permits you to control linkage among several programs with little
or no operator action.
Debugging COBOL Programs
Related Publications
Chapter 9 discusses procedures and the facilities provided by the compiler and
the COBOL languages for debugging COBOL programs. Coded examples of
some of the debugging facilities provided by COBOL are included.
You should have the following publications available for reference when
preparing and running COBOL applications:
Referencesfor Coding and Debugging COBOL Programs
• IBM 5280 COBOL Language Reference, GL23-0031
• IBM 5280 COBOL Host Compilers Problem Determination Manual,
SL23-0043
CodingAidsfor Transaction I/O
• Data Description Specifications, GX21-9362 (a pad of coding forms)
• IBM Printer/Display Layout, GX21-9174 (a pad of layout forms)
y

Referencesfor 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 Referencesfor IBM 5280 System Information
• IBM 5280 General Information, GA21-9350
• IBM 5280 Planning and Site Preparation Guide, GA21-9351
• IBM 5280 Master Index, GA21-9356
• IBM 5280 User's Setup Procedures, GA21-9365
• IBM 5280 Machine Verification Manual, GA21-9357
• IBM 5280 System Control Programming Reference/Operations
Manual, GC21-7824
Compilation Under OS/VSl
• OS/VS 1 JCL Reference, GC24-5099
• OS/VSl JCL Services, GC24-5100
Compilation Under OS/VS2
• OS/VS2 JCL, GC28-0692
Compilation Under DOS/VSE
• DOS/VSE System Control Statements, GC33-5376
vi

Contents
To the COBOL Programmer iii
Before Using This Guide iii
Scope of the Guide iii
Organization ofthe 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 ofData 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
Chapter
2. Transaction I/O -Screen Definition 2-1
Example ofCoding Data Definition Statements 2-1
Coding Conventions 2-9
Primary, Continuation, and Secondary Lines 2-9
Continuation Characters 2-9
Keywords 2-9
Constants 2-10
Comment Statements 2-10
Record Description Statements 2-11
Sequence Number Field (Columns 1 through 5) 2-11
Form Type Field (Column 6) 2-11
Name Type Field (Column 17) 2-11
Record Name Field (Columns 19 through 26) 2-11
Usage Field (Column 38) 2-11
Editing Field (Columns 45 through 80) 2-12
CHECK(DD) 2-12
DSPATR(attributes) 2-13
Field Description Statements 2-15
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 ofCOBOL Transaction I/O Statements 3-1
FILE-CONTROL Paragraph 3-1
OPEN 3-2
WRITE 3-2
READ 3-3
Sequence ofTransaction
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 ofData 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 A. Direct Communications Support A-I
Before Running a Data Communication Program A-I
Functions Supported A-I
TIN IT Routine A-2
TTERM Routine A-3
TOPEN Routine A-3
TCLOZ Routine A-3
TREAD Routine A-4
TWRT Routine A-4
TCTL Routine A-5
Appendix B.
Status Key Return Codes B-1
Appendix C. Compiler Limitations C-I
Appendix D. Compiler Return Codes D-I
Appendix E.
Storage Estimates for OSjVS E-I
Appendix F. Storage Estimates for DOSjVSE F-I
Index X-I
Contents ix

x IBM 5280 COBOL Programmer's Guide

Figures Figure 1.1. Steps
in preparing and compiling display screen formats 1-3
Figure 1.2 The data entry keyboard 1-5
Figure 1.3. COBOL command keys and codes for data entry keyboards 1-6
Figure 1.4. COBOL command keys and codes for typewriter keyboards 1-6
Figure 2.1. Sample form used
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 ofvalues returned in the ATTRIBUTE-DATA area 3-6
Figure 3.2. Example oftransaction
I/O statements 3-8
Figure 3.3. Example ofindicators and conditional bypass 3-14
Figure 4.1. The COBOL library routines that perform data Communications 4-3
Figure 4.2. Return codes from the COBOL communication library routines
4- 4
Figure 4.3. Options available with the Close routine 4-5
Figure 4.4. Coding example: data communications 4-7
Figure 5.1. Valid combinations of
SHARE/SHARER and OPEN modes 5-6
Figure 5.2. COBOL statements for Status Key and
EXCEPTION/ERROR routine 5
Figure 5.3. COBOL statement execution with
AT END and INVALID 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 COBOL statements used for printer
I/O 6-2
Figure 6.2. Example of statements used for DISPLAY
6-3
Figure 6.3. Example of statements used for sequential I/O to a work station 6-6
Figure 7.1 Job Control Procedure for the 5280 COBOL OS/VS compiler 7-3
Figure 7.2. Required parameter for allocating COBOL data sets 7-4
Figure 7.3 Example of using a COBOL compile procedure 7-4
Figure 7.4. Sample job control statements for a
DOS/VSE compilation 7-5
Figure 7.5 List of options available at compilation 7-10
Figure 7.6. Sample listing with MAP option 7-12
Figure 7.7. Sample listing with
OPTIONS specified 7-13
Figure 7.8. Sample listing -source program 7-15
Figure 7.9. Sample listing with -Data Definition Statements 7-16
Figure 7.10. Sample listing with
XREF specified 7-17
Figure 8.1. Possible methods of host-5280 data exchange 8-2
Figure 8.2. Layout of 5280 screen information 8-10
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 I/O is an IBM extension to COBOL that gives flexibility in
writing
data to and reading data from a display screen. The purpose of this
chapter
is to introduce transaction I/O and provide some rules that must be
followed in writing transaction
I/O applications. Subjects covered include:
• Statements used to define display screens and what they can do in
formatting the screen and editing data entered by an operator
• How the statements are compiled with the COBOL source program
• Steps to follow in writing an interactive application
• A summary ofthe 5280 keyboard and how some of the keys interact
with your COBOL program
Defining Display Screens
The statements which you code to define display screens are called Data
Definition Statements (DDS). The Data Definition Statements for a screen
consist ofone record description statement followed by one or more
field
description statements.
Uses of Data Definition Statements
Here are some examples of what you can do with the Data Definition
Statements:
• Define the layout of the screen: the position ofthe fields that are to
appear on the screen, the data,
if any, that is to appear in the fields, and
how the characters appear on the screen (highlight, blink, reverse image,
underline, nondisplay, and column separators).
• Cause the data to be edited as the operator enters it. For example, you
can define a field
so that only alphabetic characters can be entered. If
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, so that it shifts
either to the lower symbol or to the upper symbol automatically as the
cursor enters each position in the field
The Copy Library and Data Definition Statements
The coded Data Definition Statements must be library text in a COBOL
library. At compilation, the COBOL compiler brings them into your program
and converts them into COBOL source statements.
The COBOL library
is allocated by the facilities of the host system. The rules
for defining the library for each of the host compilers are given
in Chapter 7.
Chapter 1. Transaction I/O -Introduction 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
DDS Coding
Form
Compiler
COBOL
Source
Program
COBOL Librarv
Source listing. Contents determined
by the options specified at
compilation (see Chapter 7). Can
include:
• Source statements, with DDS-
generated code and COpy
code, if present
• DDS
• Diagnostic
messages
• Maps and cross-reference list
Object
Module
1.
2.
Arrange fields on the layout sheet (order number
GX21-9174) just as they will appear on the display
screen.
Use
the completed layout sheet as a guide for filling
out the DDS coding sheet (order number
GX21-9362).
3. Enter the DDS in a COBOL library.
4.
5.
Code source program; write COpy DDS statements
as appropriate. Enter the COBOL source program.
Compile
the source program.
Figure 1.1. Steps in preparing and compiling display screen formats
Chapter 1. Transaction I/O -Introduction 1- 3

2. Define the screens with Data Definition Statements, placing them in a
COBOL library. The rules for coding data definition statements are given
in detail in Chapter 2.
3. Code the COBOL source program that is to read and write the screens.
Information on
the COBOL statements that perform transaction I/O is
given in Chapter 3.
4. Compile the program. Information on compiler options and host job
procedures is given in Chapter 7.
1- 4 IBM 5280 COBOL Programmer's Guide

The Keyboard
I
I
I
The Keyboard
This section describes the function and command keys, and their interaction
with
COBOL programs and the IBM 5280 system. The chapter is intended
primarily for the COBOL programmer. For a tutorial, with a detailed
explanation
of the use of each key, the operator should look at the Operator's
Guide.
Figure 1.2 shows a data entry keyboard.
The relative positions of most
of the keys on the other keyboards available
with IBM 5280,
are the same as on the data entry keyboard. For a detailed
description of all keyboards, see the Operator's Guide.
For descriptive purposes, the keys can be classified as data keys,junction
keys, and command keys.
• Data keys, when pressed, cause entered data to be processed by your
COBOL program or the system.
• Function keys, when pressed, cause the IBM 5280 system to take some
action.
• Command keys, when pressed, give control to your COBOL program. A
code showing which key was pressed
is passed to a control area, if
specified, in the program.
Figure 1.2 The data entry keyboard
In general, the function keys shown in figure
1.1 are colored dark, and the
data keys are white. The operator presses a function key to enter the desired
data or execute a desired function. Additionally, the top row of data keys can
also be used as function keys or command keys. The next two sections
describe the use
of these keys and how they affect your COBOL programs.
Command and Function Key Codes
The following codes are returned in the work station control area (described
under
"Work Station Control Area" in Chapter 3) to your program when it
receives control from the work station:
• 0 when either the Enter or Record Advance key is pressed.
• 99 when any other function key is pressed.
Chapter I. Transaction I/0 -Introduction 1- 5

• One of the codes shown in figures 1.3 and 1.4 when the indicated
command key
is pressed. (Twenty-one (21) command keys are available
for use with your COBOL programs.)
Command keys can make interaction between an operator and the program
easier and more efficient. For example,
in 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
COBOL command key by (1) adjusting the shift to
either lower case (alpha) or upper case (numeric), (2) pressing the
CMD key,
and (3) then pressing the desired command key.
The command keys as they appear on the
data entry keyboard and the
typewriter keyboard
are shown in figures 1.3 and 1.4. The code passed to the
program when each key
is pressed is shown in the figure. The code is inserted
in a data-item you define in your program. You relate the data-item to the
CONTROL-AREA clause as described under "Work Station Control Area"
in Chapter 3.
ALPHA SHIFT NUMERIC SHIFT
KEY CODE KEY CODE
@ 1 #
13
% 2 $
15
* 3
16
< 4
CORR
17
CORR
5
DUP
18
, 7
19
-
/ 8 0 20
~
9
RELADV 22
RECADV
10
~
22
~I 11 SEL FMT 24
SEL FMT
12
Figure 1.3. COBOL command keys and codes for data entry keyboards
LOWERCASE. UPPERCASE.
I
I
KEY CODE KEY
co~
I
2 1 @
13 I
3 2 $ 15
4 3 %
16 I
5 4 17
6 5 & 18
8 7 *
19
9 8 20
0 9
22
10 + 23
11
f--
24
f-- 12
Figure 1.4. COBOL command keys and codes for typewriter keyboards
1- 6 IBM 5280 COBOL Programmer's Guide

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