IBM 5280 Programmer's 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

Program Numbers:

Guide

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

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

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.

To

the

COBOL

Programmer

Before Using This

Scope of

the

Guide

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

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

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

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

Chapter

2.

Transaction

I/O

- Screen Definition

2-1

Example of Coding 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 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-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

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

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

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

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

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

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

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

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

is

to write the

form, order number GX21-9362 can be used as an aid in coding the specifications. The that

the screen format would look like the

data

definition statements in figure 2.3 were written

data

entry form shown in figure 2.2.

so

Chapter

2.

Transaction

I/0

- Screen Definition

2-

3

IB~

Internationel

Job No

Operator

Sequence

;h

1 2 3 4 5 6 17 9

olllA

13

A

1016

A

1017

jA

0

1

,8

A

115

A

lit

A

l~

A

IA

1 2 3 4 5 6 7 8 9

"Number

of

sheets

BUlineu

Mechlne-s

Corporation

Reserved

£

1

t2131415~

1~

1011121314151617181920

per pad may vary slightly,

IBM 5280

Data~~t

Date

II

Datasetl R

FieldfTable Name

~

.~

~

~i

1920

21

22 23 :1425

Itlll~

i.1.1

I\; U

21

22

ecordl

I~

I

23

2425

DATA

Length

"

~

26272829

pO

~F,1I

t~

26

27

28

2930

DESCRIPTION SPECIFICATIONS

D

III

~

Location

iii

Oleck,=CHECK (code

Auto

Oup

Auto

Skip

Blank OWek -BC

ByPiftl

8yp'\~

0:.1"

IIt"f"

~ta

3132

Line Pos

33

44

ReQlmed

Oup

Dlsa~e

Field

Lo_fease

46 47 48

EXII

Requlf!d

495051

/\

I~

2

ie

1

"ID

1111

PI

,

In

oilll'l

0

ZIIA

u

2tl~

o

51D

.0

v

'0

1'5

'fHI

1

i

It:

iJ::

\/'

i'l'l"

\

:\

IX

31

32

33l<'

35

36

37 38

3940

41424344

45

46

4748

49505152535455565758

~AO

~~Ofy

AS

Mend_tory Fill

RtAdI-Bt.""

"'BY

R'rt

8V

'11

..

OR Self

-DO

-FE

~Jt

-lC

52535455565758

8Y)

E

R R

t:.

R

1\

Ie

R

I

Ie

Q

I

Sowce

,,)

Entfv

10

lJof1

Adl-l~o

Owek

O"M/G

..

ModuluI

~

ItA)

~

c

F)

1::1

Document

~ME

2MF

FlU

-RS

'"Rl

F,II

'RI ""u

i~k(G!-"J

5960

~

~II

FIE~

II

I~

5960

II

Edit~ng

Functions

AUXOUPINlmel AUXSTI".mel

COMP(lteltfldll•

'hter~'

!,,,d'Ulor))

OSPATR

(lam

EOTCOE6cock'tIOllt')

ERROR

(code

EXSR

(subroutine)

l

INSERT

Ifld1

LOOKltabie (index! I

itestcEo.GE,GT.LE.lT,NE lanr-eL.CA.CS.HI.NO.RI.UL

)".,-.-,/

4,hitt-A,O,H.N,V,W.X. Y

61

6263

64

65

I'

1

616263646566

I

('mftU9!'}I

•...

66 67 68

fldn

fldn 'II!!!"'I')

I ..,

67 68

69

70

IU

IV

69707172

PMT

(promptl

RANGEUowh. RANGEl Itabte

RESET(I"TOTnl

SEQI'tal1l

SETOFCindl SETOI\I.,ndl

SHIFT

SUB

("""1

SUeST Itabl

TADOWTOTn) TSU8

XCHKftabhindl:

'11,.,,1'

7172

73

Hllt<l

73

PTlnte4

r"uftJ

WTOTn!

74

747571

..

,

75 76

G>

of

I,

ut

I

I~

Figure 2.3

The figure 2.3 look like

COPY-ID

EMPRECD EMPRECD EMPRECD EMPRECD EMPRECD EMPRECD EMPRECD EMPRECD EMPRECD EMPRECD

Figure 2.4

2-

4 IBM 5280

COBOL

Programmer's Guide

Data

Definition

Statements

statements in figure 2.4 show what

after

they

are

copied and compiled.

A

STMT.*

Data

SEQ.*

~~

""

22

000001

23

000002

24

000004

25

000006

26

000008

27

000010

28

000012

29

000014

30

000016

31

000018

Definition

... B .........

COpy

01 EMPRECD.

02 02 02 02 02 02 02 02 02

Statements

Coding Example

the

Data

Definition

COBOL

SOURCE STATEMENTS

DDS-EMPRECD.

ACREC

EMPNO ENAME STRAD CTYST ZIPCD BEGDT SOSNO

MARST

PIC PIC PIC PIC PIC PIC PIC PIC PIC

X(00002). X( X( X(00020). X( X(00005). X(00006). X( X(OOool).

as compiled by the

Statements

00005)

00020)

00009)

COBOL

in

...

.

compiler

The following text explains some

of

the statements in figure 2.3; later sections

in this chapter give detailed rules for coding each field.

II

The Sequence Number field (columns 1-5). The number in this field appears

in the source listing under the

SEQ.# column, as shown in figure 2.4.

fJ

The Name Type field (column 17). For record description statements, this

field contains an R. For field description statements, this field contains a blank.

II

The Record Name field (columns 19-26 for record description statements) or

the

Field Name field (columns 19-24 for field description statements). These

names

(EMPRECD,

ACREC,

EMPNO,

etc.) will appear as the

01

and 02

level

data

items in

the

COBOL program, as shown in figure 2.4.

II

The Length field (columns 30-34 for field description statements only.) This

field specifies the length

of

the field on the screen, and the size of the 02 level

data-item in

the

COBOL program, as also shown in figure 2.4.

II

The Data Type field (column

35

for field description statements only). This

field defines the

data

type and keyboard positioning, in this example A for

alphabetic shift,

D for digits only, and X for alphabetic only.

m The Decimal Positions field (column

37

for field description statements only).

This field determines whether the corresponding data-item in the

COBOL

program will be compiled as alphanumeric or numeric.

If

blank, the data-item

will be alphanumeric;

if

any number between 0 and 9 (indicating a decimal

position), the data-item will be numeric. In the example, the

Decimal Positions fields all contained blanks. As shown in

figure 2.4, this created alphanumeric (X) data-items for all the fields.

D The Usage field (column 38). This field defines whether or not the operator

can enter

data

in the field.

If

it

is

B (for both input and output) the operator

can enter

data

into the field, and the program can write

data

from the field to

the screen.

If

it

is

0 (for output only), the program can only write

data

to the

screen using literal statements as will be shown later.

aNotel:

You can access in your COBOL program only those fields defined

with usage

B.

As shown in figures 2.3 and 2.4, only B fields

are

compiled as

data-items.

aNote

2:

Wand

I fields (shown on the coding form)

aren't

valid fields for

COBOL programs.

iii The Location field (columns 39-44 for field description statements only). This

field specifies the line and column number where the field

is

to appear on the

screen. The physical line number on the screen where the field will appear depends on

(1) the value you code in columns 39-41 and (2) the value you code in the

STARTING

AT

LINE

clause in the associated

WRITE

statement in your

program.

See the section "Location Field" for

the

rules on how these two

values affect the placement of fields on the screen. The value you code in columns 42-44 determine the horizontal placement

of

the field.

II

The Editing field (columns 45-80). You write the keywords

that

control the

editing, field attributes, and keyboard conditioning in this field.

Some of these keywords used in this example will be explained in the following text. Refer to figure 2.5 while reading the text.

Chapter

2.

Transaction

I/O

- Screen Definition

2-

5

I::

U

Reserved

~-

Sequence

~

g

~

~,h

~]

IBM 5280

DATA

DESCRIPTION SPECIFICATIONS

Dataset/ Record/ Fieldrrable

Name

Keving

Instruction

Length

"i

j

I:~ic

I I I III I I

I Source

Documenl

Location

Olec

ks=CHECK (code

...

)

.......

Ou.

-AD

~OfyE"Hy

-ME

AutoSlup

-AS

""'toryf,1!

·MF

.....

Chod<

·ae

fh

Adt-B'-"k

FlU

-RB

......

'BV

R,thttouft

·RL

B._

onVIf,fy

-av

RtAd,-Z""oF,ll

'RZ

Line

Pos

0

...

R.quued

'DR

S.tf·o.ck

"'"

..

Dup

DIWbIe

'00

O-M/GIQ,ect/Gl'n)

F,.ldE

••

t Required

-FE

JII:.·lIIodulus

,-,-,

en.

=LC

ii

jl

~

Editing

Functions

ADO

,,,.,.,.,

AUXOVP

INrNl

AUXSTI"....I

CO...,

i'tHtfkt1

1

•

I","

htff~'

i.!OdtgtOfjl

DSPATR ,!.nr

I

[OleOE

lc:odI"toIt'l

ERROR

(cock

1'''''"'''11'11

EXSR

(wbroutmel

INSERT

(tldt)

•..

fldn

'hter

..

')

lOOK ItabW!,ndt.!1

'tft1-Eo.GE.GT.LE.l

T,NE

Ilttf-8L.CA.CS,HI.NO,RI,UL

)".,-,-,1

4sh1tt-A.,D,H,N,Y,W.X. Y

GX21-9362I

Printed

in

U.S.~

of

PMTlpromptl

""~Ef'o.h""l

"ANGET Uable f

IndeX

J I

RESETI("TOTnJ

[n.mt\i

seal'.,,)

SETOFhndl

seTO~

Itndl

SHIFT t"1httI1

SUI

I"....'

SUIST

(table1

~21'nded)

TADOff-TOTn]

(""""II

TSU8

II-TOTnl

I".,..,.) I

XCHK

(table

,,...1

inded)

'ht.'"

• 2 3 4 5

87

.,0

11

121314151

•

..

,.

20

21

22 23

2425

32

46

4746 4950

5152

53 54 56 66

57585950

6162

6364

S556

67

68

697071727374757677

78796(

o

l'A

~

B

I~

C;

III

)

12A

~IC

Rl

I'

F;r.<

!"l

III

A

~

)

13

A

Yl

0!4

A

. ill

~D

1,11

1

~~

015

A

.'.

1Il

0

~

U

If

Ii

II K

(IC

IAI)

016

A

r-~~

I~.X

glz

4

RS

o 171A

~';'~

:'

"'D

,.,

~A

E'

u

IrAl1

IAll

ols

jA

I~I'

"I"

l'e

rz~A

IGI~

t

I~B

o 191A

'\

I K

I:

,

II

"

'10

iA

II 1

PI

rz~x

~~

f

,1

f

R8

'1'

iA

11111\

" 111:.

I)

'121A

ililH:

115

111

,e

~IF

F

f)

'131A

10

i\

.llp

,.

I'

IrRl1

ICI~ll

'141A

~D

fI'

411

~f

ft)

'lslA

In

IU

IT

t

I)

IA

~1)~

"'7

111

~IF

IA

..

In

I'

TI't

,

IA

II

111X

~18

MiF

IA

~

\

"

11'

'1

IA

1234567

8

910111213141.51617181920212223'2425262728293031323334353637383940414243444546474849505152535455565758595061626364655667686970

717273747576777879S(

'Number

of

sheets

per

pad

may

vary 'lightly.

Figure 2.5.

Data

Definition

Statements

Coding Example

II

EMPRECD

is

a record description statement.

1.

The

B in

the

Usage field

is

the

the default for

the

usage field for all

subsequent field statements.

The

B lets all fields in the record be used for

both input and output.

That

is,

the

program can write

data

to the screen

from them, and

the

operator can

enter

data

into them on the screen. The B

can be overridden in a subsequent field description statement, as will be shown.

2.

DSPATR

(for display attribute) assigns two default attributes to

the

field

description statements: all fields will have column separators

(CS)

and will

be underlined

(UL)

unless specifically overridden, as will be shown.

B

ACREC

is a two-byte field

that

will not

appear

on

the

screen.

The statements in the

Editing

field

are

an

example

of

how to suppress a field

not intended for viewing by the operator.

(In

this example,

ACREC

is

used by

the program to determine whether

the

record is current or inactive.) Here's

how this is achieved in the example:

1.

In

the

DSP A TR

keyword,

CA

(for cancel) cancels the underline

(UL)

and

column separators

(CS)

specified in the preceding record description

2-

6 IBM 5280 COBOL Programmer's Guide

statement

(EMPRECD).

ND

(for nondisplay) prevents any

field from appearing on the screen.

2.

CHECK(BY) ACREC immediately

Note later

3.

Because

II

EMPNO

that

in this

is

- BY stands for bypass - causes the cursor to skip the

field

and

be positioned

after

the record

CHECK(BY)

chapter

the

field

is

must be specified in a secondary line as explained

under

nondisplay, it wasn't necessary to specify a location.

at

the

start

is

written to the screen.

"Coding

Conventions" and shown in figure 3.3.

of the next field

a five-digit field for the employee number.

the specifications:

1.

The

D in

the

Data Type field allows the operator to enter only digits.

operator tries to enter nondigits, the keyboard will lock and

appear

will refer to the

in

the

status

line

5280 Messages

at

the

Manual

top

of

the screen. The operator

for an explanation

the recommended action to correct the error.

2.

The

01

in

the

Location field indicates

appear

on the screen in relation to

discussed earlier.

The

number J J causes the field to

the

STARTING

relative line number the field

the screen.

3.

The

DR

(for

data operator must exiting appear

RZ

The

enter

the

field. Otherwise, the keyboard will lock and

in the

status

(for right adjust with zeros) creates two conditions:

operator must press

the exit key

is

pressed, all digits are shifted to the rightmost positions; any

required) following the

at

least one

character

line.

the

Field Exit key to go to the next field and (2) when

CHECK

(in this example, a digit) before

unused positions to the left are filled with zeros.

II

The

logic

of

the

as for

- The

EMPNO

RB

following

specifications for

with the following exceptions:

CHECK

ENAME,

STRAD,

causes a right adjust with blanks instead

zeros.

- The

Data Type field for

ENAME

and

X in

the

to enter only alphabetic characters.

- The

The fields with an can be used for in write

G'Note

2.

3.

4.

A in the Data Type field for

and

digits

single quotes ( , ) in the

data

alphabetic characters.

0 specified in

output

only.

That

Editing

into the fields on the screen.

the following:

1.

The

Field

Name

field for

output

The fields needn't have a field location specified; they will screen

after

the

preceding field.

The

CA

(for cancel)

the underline

and

parameter

column separator

As shown in figure 2.4, output fields do not

STRAD

the

Usage field (column 36)

allows the operator to enter both

is, the program can write the

field to

the

screen,

fields must be blank.

following the

attributes

DSPATR

for these fields.

appear

source listing.

B

Note

the effect

MARST

1.

FE forces the operator to press the Field Exit key to exit the

BEG

DT

2.

Together, operator to fill all available positions

fields:

fields.

DR

of

CHECK

(for

parameters

data

required) and

on the

ZIPCD,

MF

(for

mandatory

in

each field before

place as follows:

Here

is a summary

of

the message

AT

LINE

start

in column

keyword means

an

and

CTYST

allows the operator

but

the operator cannot

keyword cancels

as data-items in

BEGDT,

an

data

in the

(EMPNO)

If

an

error

code

can

clause as

lIon

that

error

code will

(l)

the

is

the same

of

are

fields

that

data

enclosed

appear

on the

the

SOSNO,

ZIPCD

and

fill) force the

exit

can

take

of

the

then

and

is

the

and

to

Chapter

2.

Transaction

I/0

- Screen Definition

2-

7

-

DR

specifies

field.

-

MF

specifies

all positions

If

the

operator

characters

specified in

error code will

that

must

attempts

appear

at

least one non blank

if a character

be filled.

to exit

the

Data Type field,

in

the

field without filling the positions with the

status

line

character

must be

is entered into one position

the

at

keyboard will lock

the

top

of

the

screen.

entered

of

the field,

and

an

in

the

2-

8 IBM 5280 COBOL Programmer's Guide

Coding

Conventions

Primary, Continuation, and Secondary Lines

You

can

code two different types

• A primary line, which contains the fields, both required

columns 1-44 and, contains keywords, keyword parameters,

•

One

or more continuation lines, which extend

a preceding primary or continuation line).

The

primary line, or continuation line

continuation line,

nonblank character. The next section explains

these characters.

Field description statements

BY

parameter,

just

primary

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

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

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

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

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

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

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

3.

You must leave the Field

WRITE

output

data

character

statement.

Name

(you

enter

an 0 in the Usage field):

into the field.

any

Editing

character

1

iter

field starting in

in the

al').

string must be coded twice ( ,

The

COBOL

use

of

literals is shown in figure 2.2.

program issues an

field (columns 19-24

description statement) blank.

Here's

an

example

of

a field description

statement

defining a field for

only:

----+----1----+----2----+----3----+----4----+----5----+----6----+

A 0 'ENTER USER

For those fields defined for both input and output (you

enter

field):

1.

A literal

2. The operator can enter statements unless you specify CHECK

3.

The operator

is

not allowed in the statement.

data

on the screen in fields defined by the

CHECK(BY)

keyword is explained

can

duplicate

data

later

from

in

the

editing field.

in this chapter.)

the

corresponding positions in the preceding record by pressing the Duplicate key, unless you specify CHECK(DD).

4.

Data

can be automatically duplicated in the field when the operator has

the

Auto

pressed keyword

and

Dup/Skip

parameter description statement. correspondingpositions-in

key,

and

you have coded

in the editing field

The

data

is

automatically duplicated from

the

previous record when flie cursor enters the

of

the

the associated field

field.

aNote:

the

The

field as it appears on the screen will not contain the same digits

COBOL

program changes its contents before writing

screen. Here's

input and

an

example and

of

a field description

output; the field,

EMPNO,

statement

that

defines a field for both

will accept only digit

characters in length; each time a record appears on the screen,

the

contain

same digits as were in the corresponding field in

record:

EBCDIC

set and

Any single quote

').

of

the field

output

IO'

a B in the Usage

(The

CHECK(AD)

the

record to

data

up to five

EMPNO

the

preceding

if

the

will

----+----1----+----2----+----3----+----4----+----5----+----6----+

A

EMPNO

50

B CHECK(AO)

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

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

in

1.

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)

2

3

Blank

1 3 2 3 Blank

1

4

5

4

5

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

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

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

----+----1----+----2----+----3----+----4----+----5----+----6----+

appear

(CS)

A R EMPFILE A

following

screen with a

on line 5, column

will be placed in line 4, column 80:

EMPNO

Data

Definition

STARTING

1.

A control

5D

Statements,

AT

LINE

character

B 01

01DSPATR(CS)

after

the field

must

the field begins in

of

attributes

are

the

screen.)

that

value

If

(RI,

assigned

these positions

EMPFILE

of

5, causing

for column

be

UL,

are

can

has

Chapter

2. Transaction

I/0

- Screen Definition

2-

23

Assume, using the following subsequently written to the screen with a

greater, and line

PRTNO

the

----+----1----+----2----+----)----+----4----+----5----+----6----+

A

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

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

MODE

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

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

"ERRMSG3"

when the program finds an incorrect entry by

READ

FORMAT

II

in figure 3.2, six sets

EMPRECD,

Definition

m.

statements

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

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

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

is

in the earlier section

INDICATOR

is

executed, and

of

Coding

how

transaction

clauses, complete with explanatory text.

if

no error

EMPRECD

Data

Definition Statements."

I/O

statements

of

this chapter.

is

found, updates the

at

m are explained in

are

Chapter

3.

Transaction

I/O

- Writing the COBOL Program

3-

7

IDENTIFICATION PROGRAM-ID. ADD-NEW-EMPLOYEES. AUTHOR.

ENVIRONMENT CONFIGURATION

SOURCE-COMPUTER. OBJECT-COMPUTER.

SPECIAL-NAMES.

EI

INPUT-OUTPUT

FILE-CONTROL.

II

DATA

FILE

FD

01 SCREEN-RECORD

FD

II

01

001 002 004 006 008 010 012 014 016 018

WORKING-STORAGE

II

01

001

II

01

001

II

01

001

II

01

001

01 LAST-RECORD-SAVE

0'

B

A

ATTRIBUTE-DATA

SELECT

ORGANIZATION ACCESS FILE CONTROL-AREA

SELECT

ORGANIZATION ACCESS RELATIVE

FILE DIVISION. SECTION.

SCREEN-FILE-PRJ

EMPMAS-FILE VALUE LABEL

COPY

EMPRECD. ACREC

02

EMPNO

02 02

ENAME

STRAD

02

CTYST

02

ZIPCD

02

BEGDT

02 02

SOSNO

02

MARST

COpy DDS-ERRMSG1.

ERRMSG1

COpy DDS-ERRMSG2.

ERRMSG2

COpy DDS-ERRMSGJ.

ERRMSGJ

COPY

PROMPT

WSTATION-INFO.

02

TTYPE

02

SSIZE

02

LOCATION

02

ON-OFF-LINE

ALLOC-STATUS

02 02

INPUT-STATUS

DATA-STATUS

02

INQ-STATUS

DIVISION.

NAME.

DIVISION.

SECTION.

IBM-J70. IBM-S280.

IS

SECTION.

SCREEN-FILE-PRJ

IS IS

MODE

KEY

ARE

PIC PIC PIC PIC PIC PIC PIC PIC PIC

SECTION.

PIC

IS

SEQUENTIAL

TUBE-STAT

IS

LABEL

PIC

X(00002).

X(OOOOS). X(00020). X(00020).

X(00020). X( X(00006).

X(00009). X(00001).

X.

MODE

STATUS

EMPMAS-FILE ASSIGN

STATUS

OF

OWNER-ID

RECORDS

DDS-EMPRECD.

DDS-PROMPT.

TERMINAL-INFO.

ASSIGN

TRANSACTION

WSTATION-CONTROL-AREA.

RELATIVE

RANDOM

RKEY

DISK-STAT.

RECORDS

X(88).

IS

"BELL"

STANDARD.

00005)

PIC

PIC PIC

PIC PIC PIC PIC PIC PIC

TO

.

X(88)

X. X. X.

X. X. X. X. X.

TO

WORKSTATION

DISK

ARE

OMITTED.

VALUE

SPACES.

1920

Figure 3.2. Example of transaction

3-

8 IBM 5280 COBOL Programmer's Guide

I/O

statements

(Part

1 of 5)

01 WSTATION-CONTROL-AREA.

m

B

II

a

III

03

COMMAND-KEY

FILLER

03

01 SWITCHES.

STOP-RUN

02 02

CONTINUE

INVALID-EMPNO

02

ACTIVE-RECORD

02 02

ERROR-FOUND

WRONG-FUNC-KEY

02

77

TUBE-STAT

77

DISK-STAT RKEY

77 PROCEDURE DECLARATIVES. DEBUG-SECTION

USE

FOR DISPLAY "READ-MASTER ENTERED". DISPLAY "REKEYDISPLAY

IO-ERROR

USE AFTER

WORK-STATION.

DISKETTE-IO-ERROR

DISKETTE.

END EXECUTE CHECK-TERMINAL-ROUTINE.

MAIN-ROUTINE.

DISPLAY DISPLAY DISPLAY "RUN

STOP RUN.

USE

AFTER

DISPLAY "ERROR DISPLAY DISPLAY STOP RUN.

DECLARATIVES.

PERFORM

ACCEPT WSTATION-INFO IF

SSIZE

DISPLAY DISPLAY DISPLAY "CLOSING MOVE 1 TO

PERFORM PERFORM STOP RUN.

PIC

DIVISION.

SECTION.

DEBUGGING

"EMPNO- "

SECTION.

ERROR

SECTION.

OPENS.

NOT

"YOUR "THIS

WORK-STATION-READS UNTIL STOP-RUN CLOSES.

XX.

ON

PROCEDURE

"ERROR

"FILE

STATUS

STOPPED.".

SECTION.

PROCEDURE

"FILE "RUN

STATUS

STOPPED."

EQUAL

SCREEN PROGRAM

STOP-RUN.

xC

PIC

PIC PIC 9 VALUE

PIC PIC PIC PIC 9 VALUE

PIC PIC

READ-MASTER.

" RKEY.

EMPNO.

ON

TO

DOWN"

2).

xC

10)

9

VALUE

9 9

VALUE

9

XX.

99999.

ON

SCREEN-FILE-PR3.

WORK

STATION

IS " TUBE-STAT.

ON

EMPMAS-FILE.

DISKETTE

IS " DISK-STAT.

.

FROM

TERMINAL-INFO.

"1"

IS

TOO

REQUIRES 1920-CHARACTERS SCREEN"

.

O.

1. O. O.

O.

I/o".

SMALL."

1.

Figure 3.2. Example

of

transaction

Chapter

3.

Transaction

I/O

statements

(Part 2 of

I/O

- Writing the COBOL Program

5)

3-

9

m

m m

m

1m

m m

WORK-STATION-READS .

••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

•

THIS

PARAGRAPH

WRITES A

RECORD

TO

THE

SCREEN,

CHECKS

THE

•

• RESPONSE

WHEN

THE

SUBSEQUENT

READ

IS

EXECUTED,

AND,

IF

NO

•

ERROR

IS

FOUND, UPDATES

THE

EMPLOYEE

MASTER

FILE.

•

• •

•

THE

LOGIC

FOLLOWED

UPON

ENTRY

IS

AS

FOLLOWS: •

• •

•

1.

ON

THE

FIRST

ENTRY, WRITES

THE

FIRST

SCREEN,

AND

ISSUES

•

A

READ

TO

CHECK

THE

ENTRY

BY

THE

OPERATOR. •

•

IF

AN

ERROR

ISN'T

FOUND,

THE

EMPLOYEE

MASTER

RECORD

IS

•

UPDATED.

IF

AN

ERROR

IS

FOUND,

THE

APPROPRIATE SWITCH

IS

•

SET,

AND

WORK-STATION-READS

IS

AGAIN

EXECUTED

AS

DESCRIBEn.

•

IN

(2)

BELOW.

•

• •

•

2.

ON

THE

SECOND

OR

SUBSEQUENT ENTRY, DETERMINES

IF

AN

•

ERROR

WAS

FOUND

ON

THE

PREVIOUS ENTRY. •

•

IF

AN

ERROR

WAS

FOUND, A

MESSAGE

IS

WRITTEN

AND

THE

PREVIOUS SCREEN REWRITTEN.

OTHERWISE, WRITES A SCREEN

IN

WHICH

THE

OPERATOR

CAN

ENTER FRESH DATA.

•

••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

IF

INVALID-EMPNO = 1

WRITE SCREEN-RECORD

FROM

ERRMSG1

FORMAT

IS

"ERRMSG1"

STARTING

AT

LINE

3

READ

SCREEN-FILE-PR3

ELSE

IF

ACTIVE-RECORD = 1

WRITE SCREEN-RECORD

FROM

ERRMSG2

FORMAT

IS

"ERRMSG2"

STARTING

AT

LINE

3

READ

SCREEN-FILE-PR3

ELSE

IF

WRONG-FUNC-KEY =

WRITE SCREEN-RECORD

FROM

ERRMSG3

FORMAT

IS

"ERRMSG3"

STARTING

AT

LINE

3

READ

SCREEN-FILE-PR3.

IF

ERROR-FOUND = 0

MOVE

SPACES

TO

SCREEN-RECORD

WRITE SCREEN-RECORD

FORMAT

IS

"PROMPT"

STARTING

AT

LINE

3

READ

SCREEN-FILE-PR3

ELSE

IF

ERROR-FOUND = 1

MOVE

LAST-RECORD-SAVE

TO

SCREEN-RECORD .

••••••••••••••••

**.******************************

•

IF/ELSE

ENDS

HERE

•

.************************************************

Figure 3.2. Example of transaction

I/O

statements

(Part 3 of

5)

3~

10

IBM

5280

C()80L

Programmer's

Guide

WRITE SCREEN-RECORD FORMAT STARTING

READ

MOVE

PERFORM PERFORM IF

CONTINUE = 1 PERFORM

IF

CONTINUE = 1

PERFORM

READ-MASTER.

MOVE SUBTRACT

READ

INVALID

IF

CONTINUE = 1

IF

ELSE

UPDATE-MASTER.

MOVE

REWRITE

INVALID

HI OPENS.

OPEN

CLOSES.

CLOSE

fa

COMMAND-KEY-CHECK.

IF

COMMAND-KEY = "00"

MOVE 1 TO

ELSE

IF MOVE 1 TO MOVE 0 TO

MOVE 1 TO

ELSE

SET-SWITCHES.

MOVE 0 TO

MOVE

IS

"EMPRECD"

AT

LINE

6.

SCREEN-FILE-PR3

EMPRECD

EMPNO

EMPMAS-FILE

MOVE 0 TO MOVE 1 TO

ACREC MOVE 1 TO MOVE 0 TO

MOVE

SCREEN-RECORD

MOVE 1 TO MOVE 0 TO

1-0

EMPMAS-FILE

SCREEN-FILE-PR3.

COMMAND-KEY = "02"

MOVE 1 TO MOVE 0 TO

TO SET-SWITCHES. COMMAND-KEY-CHECK.

UPDATE-MASTER.

1000

EMPRECD

SCREEN-FILE-PR3

EMPMAS-FILE.

ACTIVE-RECORD, INVALID-EMPNO,

WRONG-FUNC-KEY, STOP-RUN, ERROR-FOUND.

TO

CONTINUE.

LAST-RECORD-SAVE.

READ-MASTER.

TO

RKEY. FROM

KEY

CONTINUE

ERROR-FOUND, INVALID-EMPNO.

NOT

EQUAL ACTIVE-RECORD, ERROR-FOUND CONTINUE

"A"

TO

ACREC.

KEY

INVALID-EMPNO CONTINUE.

CONTINUE

STOP-RUN CONTINUE

WRONG-FUNC-KEY

ERROR-FOUND CONTINUE.

RECORD

RKEY

GIVING RKEY.

TO

EMPRECD.

INTO EMPRECD.

"F"

Figure 3.2. Example of transaction

Chapter

3.

Transaction

I/O

statements

I/O

(Part

4 of 5)

- Writing the COBOL Program

3-

11

o

01A 02A 03A 04A 05A 06A 07A 08A 09A 10A 11A 12A 13A 16A 17A 18A 19A 20A 21A

o

1A 02A 02A

o

1A 02A 02A

o

1A 02A 02A

o

1A 02A 02A

R

EMPRECD ACREC

EMPNO

ENAME

STRAD

CTYST

ZIPCD

BEGDT

SOSNO

MARST

R

ERRMSG1

R

ERRMSG2

R

ERRMSG3

R

PROMPT

2

5D

B

DDS

SOURCE

LISTING

DSPATR(CS UL)

Ell

DSPATR(CA

ND)

CHECK(BY)

01 11CHECK(DR RZ)

o 'EMPLOYEE

NUMBER'

DSPATR(CA)

20X

02

11CHECK(DR RB)

o 'EMPLOYEE

NAME'

DSPATR(CA)

20A

03

11CHECK(DR RB)

o

'STREET

ADDRESS' DSPATR(CA)

20X

04

11CHECK(DR RB)

o

'CITY,

STATE'

DSPATR(CA)

5D

05

11CHECK(DR

MF

FE)

o

'ZIP

CODE' DSPATR(CA)

6D

06

11CHECK(DR

MF

FE)

o 'BEGINNING DATE' DSPATR(CA)

9D

07

11CHECK(DR

MF)

o

'SOCIAL

SECURITY

NUMBER'

DSPATR(CA)

1X

08

11CHECK(DR MF)

o

'MARITAL STATUS - M

OR

s'

DSPATR(CA)

B

DSPATR(RI

HI

BL)

Ell

o 01 02'EMPLOYEE

NUMBER

INCORRECT.

MUST

BE-

MORE

THAN

1000

OR

LESS

THAN

2000.'

DSPATR(RI

HI

BL)

Ell

o 01 02'EMPLOYEE

NUMBER

WRONG.

ALREADY

ASS-

IGNED

TO

ANOTHER

EMPLOYEE.'

DSPATR(RI

HI

BL)

Ell

o 01

02'yOU

HIT

WRONG

COMMAND

KEY.

ONLY

EN-

TER,

02,

AND

03

ALLOWED.'

B

DSPATR(RI

HI)

Ell

o 01

02'ENTER

INFORMATION

ON

NEW

EMLOYEE.-

Figure 3.2. Example of transaction

I/O

statements (Part 5 of 5)

3-

12

IBM 5280 COBOL Programmer's Guide

Indicator Example

An example

3.3. (See the Clause" and INDICATOR

The logic

• The program writes four fields to the screen on succeeding lines in the following order:

• The operator enters the employee name, street address, city and state, and employment number in the designated fields and presses the Enter

• The program checks whether or not the employee number entered by the operator

•

If

and writes a fresh screen format.

•

If

message to the screen indicating cursor bypasses the

in the first position of the

The use of indicators allows the program to control whether or not STRAD, how this is achieved:

1.

The indicators 51, 52, and statements secondary lines follow immediately to be bypassed.

2.

The indicator numbers 51, 52, and data-item defined

3.

Before an error message

4.

The which writes the new screen format and causes the cursor the bypass the ENAME,

of

the use

5280 COBOL Language Reference manual under

"INDICATOR

clause with a data-item.)

of

the program shown in figure 3.3

appears in the first position of the first field,

key.

is

the employee number

(2) writes a screen format with the information previously entered. The

and

CTYST

WRITE

of

transaction

Clause" for detailed rules on coding the

ENAME,

valid.

is

ENAME,

are bypassed by the cursor. The following text explains

at

II, II, and

statement

STRAD,

at

II.

and

II

is

at

CTYST

I/O

and indicators

is

as follows:

STRAD,

valid, the program updates

not valid, (1) the program writes an error

EMPNO

53

with the

written, the indicators

II

contains the related

CTYST,

ENAME.

that

the number entered isn't valid and

STRAD,

are coded on secondary lines

and

CTYST

field.

CHECK(BY)

after

the lines

53

are associated with a boolean

fields.

is

shown in figure

and

EMPNO.

EMPMAS-FILE

fields and appears

keyword. The

that

define the fields

are

set to on

INDICATOR

"OCCURS

The cursor

ENAME,

of

the

at

D.

clause

Chapter

3.

Transaction

I/O

- Writing the COBOL Program

3-

13

0001 0002 0005 0008 0011

IDENTIFICATION

DIVISION. PROGRAM-ID. INDICATORS. AUTHOR. A

NAME.

ENVIRONMENT

DIVISION.

CONFIGURATION

SECTION.

SOURCE-COMPUTER.

IBM-370

WITH

DEBUGGING

MODE.

OBJECT-COMPUTER.

IBM-5280.

INPUT-OUTPUT

SECTION.

FILE-CONTROL.

SELECT

SCREEN-FILE-PR3

ASSIGN

TO

WORKSTATION

1920

ORGANIZATION

IS

TRANSACTION

ACCESS

MODE

IS

SEQUENTIAL

FILE

STATUS

IS

TUBE-STAT

CONTROL-AREA

IS

WSTATION-CONTROL-AREA.

SELECT EMPMAS-FILE ASSIGN

TO

DISK

ORGANIZATION

IS

RELATIVE

ACCESS

MODE

IS

RANDOM

RELATIVE

KEY

IS

RKEY

FILE

STATUS

IS

DISK-STAT.

DATA

DIVISION.

FILE

SECTION. FD 01 01 FD

01

SCREEN-FILE-PR3

LABEL

RECORDS

ARE

OMITTED.

SCREEN-RECORD

PIC

X(65).

SCREEN-RECORD-CLEAR

PIC

X(65). EMPMAS-FILE LABEL

RECORDS

ARE

STANDARD.

COpy

DDS-INDIC.

EMPRECD.

02

ENAME

02

STRAD

02

CTYST

02

EMPNO

PIC

X(00020).

PIC

X(00020).

PIC

X(00020).

PIC

X(00005).

WORKING-STORAGE

SECTION.

II

01

IFIELDS.

02

INDCATOR-FIELD

PIC 1 OCCURS

3 TIMES

INDIC

51.

01 INDCATOR-ON

PIC

XXX

VALUE'

111'.

COpy DDS-ERRMSG1.

0001

01

ERRMSG1

PIC

X.

01 WSTATION-CONTROL-AREA.

03

COMMAND-KEY

PIC

X(2)

VALUE

'00'.

03

FILLER

PIC

X(10).

01 SWITCHES.

02

STOP-RUN

02

CONTINUE

PIC 9 VALUE

O.

02

INVALID-EMPNO

02

ERROR-FOUND 77 TUBE-STAT 77

DISK-STAT

77

RKEY

PROCEDURE

DIVISION. DECLARATIVES. DEBUG-SECTION

SECTION.

PIC

PIC PIC PIC PIC

PIC

9

VALUE

9

VALUE

9

VALUE XX. XX.

9999.

USE

FOR

DEBUGGING

ON

READ-MASTER.

DISPLAY 'READ-MASTER

ENTERED'. DISPLAY 'REKEY= ' RKEY. DISPLAY 'EMPNO= '

EMPNO.

1.

O.

Figure 3.3. Example

of

indicators and conditional bypass

(Part 1 of

3)

3-

14

IBM 5280 COBOL Programmer's Guide

IO-ERROR

USE

AFTER

WORK-STATION.

DISKETTE-IO-ERROR

USE

AFTER

DISKETTE.

END

DECLARATIVES. EXECUTE MAIN-ROUTINE.

PERFORM

STOP WORK-STATION-READS.

IF

INVALID-EMPNO = 1 WRITE SCREEN-RECORD FORMAT STARTING READ

fJ

II

MOVE

WRITE SCREEN-RECORD

ELSE

MOVE MOVE WRITE SCREEN-RECORD

READ

PERFORM IF

CONTINUE = 1 PERFORM

IF

CONTINUE = 1

PERFORM

SECTION.

ERROR

DISPLAY 'ERROR DISPLAY DISPLAY 'RUN STOP RUN.

ERROR

DISPLAY 'ERROR DISPLAY DISPLAY 'RUN STOP RUN.

SECTION.

OPENS. WORK-STATION-READS UNTIL STOP-RUN CLOSES.

RUN.

SCREEN-FILE-PR3

INDCATOR-ON

EMPRECD

FORMAT

STARTING INDICATORS

IF

ERROR-FOUND = 0 SPACES ZEROS

FORMAT STARTING SCREEN-FILE-PR3

SET-SWITCHES.

UPDATE-MASTER.

PROCEDURE

'FILE

IS

AT

IS

TO

IS

READ-MASTER.

ON

STATUS

STOPPED.'.

SECTION.

PROCEDURE

ON

STATUS

STOPPED.'

'ERRMSG1'

LINE

TO

SCREEN-RECORD

'EMPRECD'

AT

LINE

ARE

TO

SCREEN-RECORD-CLEAR

IFIELDS

'EMPRECD'

AT

LINE

ON

SCREEN-FILE-PR3.

WORK

STATION

IS ' TUBE-STAT.

ON

EMPMAS-FILE.

DISKETTE

IS ' DISK-STAT.

FROM

4

RECORD

IFIELDS

6

INDCATOR-FIELD

4.

RECORD

I/o'.

.

ERRMSG1

INTO EMPRECD.

I/o'.

1.

Figure 3.3. Example of indicators and conditional bypass

Chapter

3.

Transaction

I/0 --Writing the COBOL Program

(Part

2 of 3)

3-

15

READ-MASTER.

MOVE

EMPNO SUBTRACT READ

EMPMAS-FILE

INVALID

MOVE 0 TO

UPDATE-MASTER.

OPENS.

CLOSES.

SET-SWITCHES.

MOVE 1 TO

MOVE

SCREEN-RECORD

REWRITE

OPEN

CLOSE EMPMAS-FILE

MOVE 0 TO

MOVE

EMPRECD

INVALID

MOVE 1 TO MOVE 0 TO

I-O

SCREEN-FILE-PR3.

TO

DDS

TO

RKEY.

1000

FROM

RKEY

GIVING RKEY.

KEY

CONTINUE

ERROR-FOUND, INVALID-EMPNO.

TO

EMPRECD.

KEY

INVALID-EMPNO

CONTINUE.

SCREEN-FILE-PR3

EMPMAS-FILE.

INVALID-EMPNO, STOP-RUN, ERROR-FOUND. CONTINUE.

SOURCE

LISTING

01A 02A 03A 04A 05A OGA 07A OSA

9A 10A 11A 12A

o

1A 02A 02A

51

52

53

R

EMPRECD ENAME

STRAD

CTYST

EMPNO

R

ERRMSG1

B

5D

01

0

02

0

03

0

04

0

B

01

0

20X

20A

20X

Figure 3.3. Example

DSPATR(CS UL)

11CHECK(DR RB)

CHECK(BY)

'EMPLOYEE

11CHECK(DR RB)

CHECK(BY)

'STREET

11CHECK(DR RB)

CHECK( BY)

'CITY,

11CHECK(DR RZ)

'EMPLOYEE

DSPATR(RI

02

'EMPLOYEE

MORE

of

indicators and conditional bypass

II

NAME'

DSPATR(CA)

m

ADDRESS' DSPATR(CA)

iii

STATE'

THAN

DSPATR(CA)

NUMBER'

HI

BL)

NUMBER

1000

DSPATR(CA)

INCORRECT.

OR

LESS

THAN

MUST

2000.

(Part

BE-

,

3 of 3)

3-

16

IBM 5280 COBOL Programmer's Guide

Chapter 4. Data Communications Programming with COBOL

Uses

This chapter provides the information necessary to code the statements communications link; throughout this chapter and book, this exchange of

is

called data communications.

Also, the chapter has the following information:

• A summary

• The COBOL

control over all communication facilities See Appendix A for a description

To execute a communications environment must be established using utilities. Information on this subject can be found in the

that

IBM

also provides suppor·t

COBOL program using

Reference Manual.

of

Data Communications Programs

You might want to write a COBOL

• When you want to interact with an operator within one system and need to access

When you want to process

allow

data

exchange between two systems over a

of

COBOL

5280 facilities needed to execute a

data

in a remote system.

data

communications capabilities

of

data

communications giving more direct

than

as described in this chapter.

of

direct

data

communications, the proper

data

communications program:

data

online as it

COBOL

communications support.

program

the

preparation

Communications

is

received from the host.

data

• When you want to match your 5280 communications program with a host application program.

• When the IBM 5280 needs. receiving batch data, and sending inquiries and receiving replies. Complete information on the functions them

The

functions provided by these utilities

is

given in the Communications Reference Manual.

Data

Communications Utilities don't meet your

of

the utilities and how to use

Eligible Systems

The systems with which a those for an assembler language program. See the chapter Communications with Assembler Language" in the Communications

Reference Manual under

and

"SNA

systems.

Programming with Assembler Language" for a list of the eligible

COBOL

"BSC

program can communicate

Programming with Assembler Language"

COBOL Programs and the Communications Access Method

A

COBOL transfer data. must code the others in your

program works with the communications access method

Part

of

the tasks in communicating

Chapter

COBOL

4.

Data

program.

Communications Programming with

are

sending batch data,

"Data

is

done by

CAM;

are

the same as

(CAM)

you

COBOL

to

4-

I

COBOL Program Responsibilities

A

COBOL

program

interfaces to

CAM

with a series

of

library routines.

The

COBOL

compiler places these library routines in your object module

at

compilation. You

initiate

a desired communications

task

(reading records, for

example) by initiating the

appropriate

library routine from your program, in

which you code

the

following information:

•

CALL

verbs, which initiate

the

COBOL

library routines

that

open

and

close

data

sets,

and

read

and

write records.

•

Data

items, which designate input

and

output

areas

in your

COBOL

program

and

other

information needed by the library routines.

•

Data

items, in which

the

library routines

put

status

information

after

they

complete execution.

Your

program

can look

at

this

return

information to decide upon subsequent action.

Details on how to code

the

above information follows

after

the

next section.

System Requirements for Communication Programs

To

write

and

execute a

COBOL

data

communications program, you need:

•

The

IBM

5280 Communications Utilities licensed program, which

contains

the

communications access

method

(CAM)

and

the utilities

that

prepare

the

communications environment

• A communications

adapter

•

When

using

SNA,

the

elapsed time

counter

feature

• A

partition

with sufficient storage to

run

the

COBOL

program.

(The

amount

of

storage required by

the

program

is printed on

the

compiler

output

listing

if

either

the

LOAD

or

the

LIST

option is in effect

during

compilation.

See

Chapter

7 for information on specifying compiler

options.)

For

the

minimum

size

of

the

partition

required by

CAM,

see

Chapter 1 of

the

5280 Communications Reference Manual.

Before Running a

Data

Communication Program

Before running a

data

communication

program,

you

must

ensure

that

the

proper communications environment exists for your program.

The

communications environment

is

established with two

of

the

IBM

5280

Data

Communication

Preparation

Utilities:

•

The

Communications Configuration Utility, to which the

communications environment

is

described;

the

utility places this

information in a

communications configuration record.

•

The

Communications

Load

Utility, which loads

the

communications

access method

(CAM)

into main storage.

See

the

IBM

5280 Communications Reference Manual, for detailed

information on these two utilities.

Writing COBOL Communication Statements

COBOL

provides four routines which handle communications; their names

and

functions

are

shown in

the

following table:

4-

2 IBM 5280 COBOL Programmer's Guide

Routine

Function

AVCHOPEN

Open routine.

Prepares

for

read

and

write operations between two

systems.

AVCHCLOZ

Close routine. Provides

three

options: (1) ends communications

operations or (2) signals an end-of-file to

the

receiver

and

the

beginning

of

a new file

or

(3)

turns

around

the direction

of

transmission from send

to receive.

AVCHREAD

Read

routine.

Reads

a record into a

buffer

in

the

COBOL

program

from

the

sending station.

AVCHWRT

Write

routine.

Writes

a record from a buffer in

the

COBOL

program

to

the

receiving station.

Figure 4.1.

The

COBOL

library routines

that

perform

data

communications

These routines

are

invoked in the

COBOL

program with

CALL

statements.

The following sections explains how to code

the

CALL

statements, the

parameters you must supply, and

the

information returned to your program

after

the routines have executed.

Communication Routine Parameters

In each

CALL

to a communications routine, you point to a

parameter

list in

either

the

Working Storage Section or

the

Linkage Section

of

your program

(the

detailed layouts

of

these areas

are

given in the routine descriptions

that

follow).

Communication Program Example - Explanation

Open Routine

Figure 4.4

at

the end

of

the

chapter

gives an example

of a COBOL

program

using

data

communications, both sending and receiving data; the program in

the example:

1.

Reads records from a diskette file containing information for updating an

employee master file on line

at

another system.

2.

Transmits the records to

the

remote system.

3.

After

sending all the update records, reads records sent by the remote

system confirming receipt and giving diagnostics,

if

any.

The text in the following section will refer to this example by numbered keys

in

explaining

the

pertinent

COBOL

statements.

The following

is

the format

of

the

CALL

statement used to initiate the Open

routine:

CALL"AVCHOPEN"USINGparameter-1buffer-2

parameter-l points to a status area you code in either the Working Storage

Section or the Linkage Section in the

Data

Division

of

your program in the

following format: 01

parameter-1

02

return-code

02

FILLER

02

buffer-size

PIC

99.

PIC

9999.

PIC

9999.

Chapter

4.

Data

Communications

Programming

with

COBOL

4-

3

Close Routine

return-code

is

a two-digit completion code returned by the Open routine

after

execution;

the

codes

that

can

be returned

and

their meanings

are

given

in

figure 4.2.

buffer-size

is

the length in bytes

of

the records to be read or the

maximum

length

of

records to be written.

buffer-2

is a 01

level

data-item

which you define in the

Data

Division of your

program for the area from which

data

is

to be sent or in which

data

is

to be

received. An example

of

the statements used to call the Open routine

is

shown

at

m in

figure 4.4.

Note

that

the

CALL

statement

points to the

parameter

list

OPEN-READ-WRITE-PARAMS

at

fJ

and

the buffer

EMPRECD

at

II,

defined in the

Data

Division.

[J'

For

SNA

users:

If

the

host requires logon

data,

the

first 80 bytes

of

buffer-2

must

contain

the

data

when

the

Open routine

is

invoked in

the

program.

[J'

For switched line users: A timeout may occur which causes a line drop

if

data

transfer

doesn't

take

place within a specified

amount

of

time. You might

want

to prompt

the

operator with a

STOP

statement,

as

is

shown

at

II

in

figure 4.4, to ensure

the

stations

are

connected.

For BSC, a line connection with

the

remote station should be

made

immediately before

the

first

READ

or

WRITE;

for

SNA,

before the

OPEN.

Code

Meaning 00 Execution was successful. 04 For the Read routine only.

End

of

data. Successful completion.

08

Exception condition. Conditions on the line or

at

the remote station

caused an unsuccessful completion

of

the last message, but there

is

no

error in the COBOL program.

12

Application error. An error in the logic of the COBOL communication

statements. For example: the program attempted to call the Read

routine without having previously called the

Open routine.

16

Permanent error. An unrecoverable error in,

for

example, the hardware,

CAM, the line, etc., has been found.

Figure 4.2.

Return

codes from the

COBOL

communication library routines.

The

format

of

a call to the Close routine

is:

CALL"

AVCHCLOZ" USING

parameter-1

parameter-l points to a

status

area

you code in

either

the Working

Storage

Section

or

the Linkage Section in the

Data

Division

of

your program in the

foliowing format:

01

parameter-1 02

return

code

02

FILLER

PIC

99.

PIC

9999.

02

close-option

PIC

A.

4-

4 IBM 5280 COBOL Programmer's Guide

Terminating Without Close

Read Routine

return-code

is

a two-digit completion code returned by

the

Close routine

after

execution; the codes

that

can

be returned and their meanings

are

shown in

figure 4.2.

close-option is a one-character code

that

can cause one

of

three conditions by

the Communications access method

(CAM).

The actions and the subsequent

action taken by

the

user program are shown in the following figure:

close-option

CAM/User

Action

F

Terminates communications operations. To resume communications, the Open routine must again be called.

E

Sends end-of-file indication to receiver. (A return code

of

04

is

posted if the receiver

is

using IBM 5280

COBOL

data

communications.) The sender can then begin transmission

of

another file to the receiver. Don't call the Open routine

after

a

close with the E option.

R Turns around the line direction from

transmit

(through the

Write

routine) to receive (through

the

Read routine). An error in

the

return-code field

after

execution

of

a close with

the

R option means

the

turn-around was not successful.

Don't

call

the

Open routine

alter

a close with

the

R option.

Use

of

the

R option between transmit

and

receIve uperations is

optional.

Any

character

F option assumed.

other than the above

Figure 4.3. Options available with the Close routine An example

of

the

statements used to call the Close routine

is

shown

at

II

and

1m.

At

II, the R close option

is

used, because the line direction

is

changed

from transmit to receive.

At

1m,

the F close option

is

used to end the

communica tions link. Note

that

the

CALL

statement

points to the

parameter

list CLOSE-PARAMS

at

II.

aNote:

don't

call the Close routine if,

after

receiving

data

using

the

Read

routine, you want to indicate an error condition found by your program.

If

the

Close routine is not executed before stopping the

COBOL

program with a

STOP

RUN

verb, a negative response will be sent to

the

sending station.

At

II

in the example shown in figure 4.4, the run

is

stopped

if

either a disk error or printer error occurs without calling the Close routine, thus informing the sending program

that

the

run was not successful.

The format

of

a call to the Read routine

is:

CALL

"AVCHREAD"

USINGpararneter-1

parameter-l points to a status

area

you code in either the Working Storage

Section or the Linkage Section in the

Data

Division

of

your program in the

following format:

01

pararneter-1 02

return-code

PIC

99.

02

FILLER

~IC

9999.

Chapter

4.

Data Communications Programming with

COBOL

4-' 5

return-code

is

a two-digit completion code returned by the Read routine

after

execution; the codes

that

can be returned and their meanings

are

shown

in

figure 4.2.

An example

of

the statements used to call the

Read

routine

is

shown

at

0 in

Figure 4.4. The

statement

points to the

parameter

list fJ

OPEN-READ-WRITE-PARAMS in the

Data

Division.

Padding Unused Bytes in Read Buffer

Write Routine

If

the record read

in

is

smaller

than

the buffer-size (defined in the Open

routine), the remaining bytes will be padded with blanks.

The

format

of a Write

statement

is:

CALL

"AVCHWRT"

USINGparameter-1

parameter-l points to a

status

area

you code in either the Working

Storage

Section

or

the Linkage Section in the

Data

Division

of

your program in the

following format:

01

parameter-1 02

return-code

PIC

99.

02

FILLER

PIC

9999.

02

record-size

PIC

9999.

return-code

is

a two-digit completion code returned by the

Write

routine

after

execution; the codes

that

can

be

returned

and

their meanings

are

shown in

figure 4.2.

record-size

is

the length in bytes

that

of

the records you want to send.

It

cannot be more

than

the

buffer-size value you specify in

the

Open routine.

An

example

of

the

statements

used to call

the

Write

routine is shown in

II

in

Figure 4.4.

Communication Program Example - Listing

The

following

is

a listing

of

the

COBOL

communications program described

earlier in this

chapter

under

"Example

of

COBOL

Communications

Program".

Note

that

all information

that

normally appears to the left

of

the

statement

numbers

(the

COpy

ID

column) has been

truncated

for this

example.

4-

6 IBM 5280 COBOL Programmer's Guide

..

0001 0002 0004 0006 0008 0010 0012 0016 0018 0020

B

IDENTIFICATION

DIVISION. PROGRAM-ID. SEND-RECEIVE. AUTHOR. A NAME. ENVIRONMENT

DIVISION.

CONFIGURATION SECTION.

SOURCE-COMPUTER.

IBM-370.

OBJECT-COMPUTER.

IBM-S280. INPUT-OUTPUT SECTION. FILE-CONTROL.

SELECT

PRINT-FILE

ASSIGN

TO

PRINTER

ORGANIZATION

IS

SEQUENTIAL

ACCESS

IS

SEQUENTIAL

FILE

STATUS

IS

PRINT-FILE-STAT.

SELECT UPDATE-FILE ASSIGN

TO

DISK

ORGANIZATION

IS

RELATIVE

ACCESS

IS

SEQUENTIAL

RELATIVE

KEY

IS

RKEY

FILE

STATUS

IS

UPDATE-FILE-STAT.

DATA

DIVISION.

FILE

SECTION.

FD

UPDATE-FILE LABEL

RECORDS

ARE

STANDARD.

COpy

DDS-EMPRECD.

01

EMPRECD.

02

ACREC

PIC

X(00002)

.

02

EMPNO

PIC

X(OOOOS).

02

ENAME

PIC

X(00020)

.

02

STRAD

PIC

X(00020).

02

CTYST

PIC

X(00020)

.

02

ZIPCD

PIC

X(OOOOS).

02

BEGDT

PIC

X(00006).

02

SOSNO

PIC

X(00009).

02

MARST

PIC

X(00001).

FD

PRINT-FILE LABEL

RECORDS

ARE

STANDARD.

01 PRINT-RECORD.

OS

RCDCD

PIC

X(88).

WORKING-STORAGE

SECTION.

01 SWITCHES.

02

COMM-ERROR

PIC

9

02

OPEN-ERROR

PIC

9

02

CLOSE1-ERROR

PIC

9

02

CLOSE2-ERROR

PIC

9

02

WRITE-SEND-ERROR

PIC

9

02

READ-RECEIVE-ERROR

PIC

9

02

STOP-READS

PIC

9

02

STOP-WRITES

PIC

9

VALUE VALUE

VALUE

VALUE VALUE VALUE

77 UPDATE-FILE-STAT

PIC

XX.

77

PRINT-FILE-STAT

PIC

XX.

77

RKEY

PIC

99999.

O. O.

O. O. O.

O.

77

RCOUNTER

PIC

99999

VALUE

77

CAUSE

PIC

X(

8)

VALUE

01 OPEN-READ-WRITE-PARAMS.

02

RETURN-CODE

PIC

9(2)

VALUE

02

FILLER

PIC

9

(4)

.

02

RECORD-SIZE

PIC

9

(4)

VALUE

O.

SPACES.

O.

88.

Figure 4.4. Coding example:

data

communications

(Part 1 of

3)

Chapter

4.

Data

Communications Programming with COBOL

4-

7

II

01 CLOSE-PARAMS.

02

CRETURN-CODE

02

FILLER

02

CLOSE-OPTION

PROCEDURE

DIVISION.

DECLARATIVES.

PIC

9(2)

VALUE

O.

PIC

9 ( 4 ) .

PIC A VALUE

SPACES.

II

DISK-ERROR

SECTION.

USE

AFTER

ERROR

PROCEDURE

ON

UPDATE-FILE.

DISKX.

DISPLAY "ERROR

ON

UPDATE-FILE

I/O

DURING

SEND".

DISPLAY

"FILE

STATUS

IS " UPDATE-FILE-STAT.

DISPLAY "TRANSMISSION STOPPED.

RUN

STOPPED.".

STOP RUN.

PRINT-ERROR

SECTION.

USE

AFTER

ERROR

PROCEDURE

ON

PRINT-FILE.

II

PRINTERX.

DISPLAY "ERROR

ON

PRINTER-FILE

I/O

DURING

WRITE".

DISPLAY

"FILE

STATUS

IS " PRINT-FILE-STAT.

DISPLAY "TRANSMISSION STOPPED.

RUN

STOPPED.".

STOP RUN.

END

DECLARATIVES.

EXECUTE

SECTION.

MAIN-ROUTINE.

PERFORM

OPEN1.

B STOP

"ENSURE

LINE

CONNECTED

TO

REMOTE

STATION &

HIT

ENTER.".

IF

COMM-ERROR

IS

EQUAL

TO

0

PERFORM

REMOTE-STATION-WRITES

UNTIL STOP-WRITES

IS

EQUAL

TO

1.

IF

COMM-ERROR

IS

EQUAL

TO

0

PERFORM

CLOSE1.

IF

COMM-ERROR

IS

EQUAL

TO

0

DISPLAY

RCOUNTER

"

RECORDS

SENT SUCCESSFULLY:

NOW

AWAITING RESPONSE"

PERFORM

OPEN2.

IF

COMM-ERROR

IS

EQUAL

TO

0

PERFORM

REMOTE-STATION-READS

UNTIL STOP-READS

IS

EQUAL

TO

1.

IF

COMM-ERROR

IS

EQUAL

TO

1

PERFORM

ERROR-ROUTINE

ELSE DISPLAY

"SESSION

COMPLETED

SUCCESSFULLY.".

PERFORM

CLOSE2.

STOP RUN.

REMOTE-STATION-WRITES.

READ

UPDATE-FILE

RECORD

AT

END MOVE 1 TO

STOP-WRITES.

IF

STOP-WRITES

IS

EQUAL

TO

0

IF

ACREC

IS

EQUAL

TO

"A"

ADD 1 TO

RCOUNTER

III

CALL

"AVCHWRT"

USING OPEN-READ-WRITE-PARAMS.

IF

RETURN-CODE GREATER

THAN

0

MOVE 1 TO

WRITE-SEND-ERROR, COMM-ERROR,

STOP-WRITES.

Figure 4.4. Coding example:

data

communications (Part 2

of

3)

4-

8 IBM 5280

COBOL

Programmer's Guide

REMOTE-STATION-READS.

CALL

IF

RETURN-CODE MOVE 1 TO

ELSE

MOVE 1 TO

IF

STOP-READS

WRITE PRINT-RECORD

D OPEN1.

OPEN INPUT CALL

"AVCHOPEN" USING OPEN-READ-WRITE-PARAMS EMPRECD.

IF

STOP

"PRESS

II

CLOSE1.

CLOSE MOVE

"R"

CALL

"AVCHCLOZ" USING CLOSE-PARAMS.

IF

OPEN2.

OPEN INPUT

OUTPUT

Il!I

CLOSE2.

CLOSE MOVE

"F"

CALL

"AVCHCLOZ" USING CLOSE-PARAMS.

IF

ERROR-ROUTINE.

IF

OPEN-ERROR MOVE

ELSE

IF

MOVE

ELSE

IF

MOVE

ELSE

IF

MOVE

ELSE

IF

MOVE DISPLAY "TRANSMISSION DISPLAY "ERROR DISPLAY "RETURN CODE- " RETURN-CODE.

"AVCHREAD" USING OPEN-READ-WRITE-PARAMS.

IS

EQUAL

IF

RETURN-CODE

MOVE 1 TO

UPDATE-FILE.

TO

CRETURN-CODE GREATER MOVE 1 TO MOVE 1 TO

UPDATE-FILE.

TO

CRETURN-CODE GREATER MOVE 1 TO

MOVE 1 TO

"OPEN"

CLOSE1-ERROR

"CLOSE1" CLOSE2-ERROR "CLOSE2" WRITE-SEND-ERROR "WRITE" READ-RECEIVE-ERROR

"READ"

STOP-READS

RETURN-CODE GREATER

COMM-ERROR,

READ-RECEIVE-ERROR,

STOP-READS.

IS

EQUAL

UPDATE-FILE.

GREATER

COMM-ERROR,

OPEN-ERROR.

ENTER

TO

CLOSE-OPTION.

COMM-ERROR CLOSE1-ERROR.

UPDATE-FILE

PRINT-FILE.

CLOSE-OPTION.

COMM-ERROR CLOSE2-ERROR.

IS

EQUAL

TO

CAUSE

TO

CAUSE

TO

CAUSE

TO

CAUSE

TO

CAUSE.

FOUND

TO

4

THAN

TO

0

FROM

EMPRECD.

THAN

CONTINUE".

THAN

TO

1

IS

EQUAL

IS

EQUAL

INTERRUPTED"

DURING"

IS

EQUAL

IS

TO

EQUAL

CAUSE

4

0

TO

"RUN

STOPPED."

Figure 4.4. Coding example:

Chapter

data

communications (Part 3

4.

Data

Communications Programming with

of

3)

COBOL

4-

9

4-

10

IBM 5280

COBOL

Programmer's

Guide

Chapter 5. Diskette Input/Output

Input-Output Summary

Diskette IBM you write to perform diskette

writing

Input/Output

(I/O)

is

the transfer of

data

between a program and

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

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

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

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

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

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 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

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

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

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

UPDATE-FILE

routine

/ERROR

if

any operation

or

PRINT-FILE,

at

II

or

EJ

receives control, displays some

procedure

is

used only when a file

is

attempted against a file which has

an

EXCEPTION

is

in open

/ERROR

that

your

may be

Chapter

5.

Diskette

Input/Output

5-

7

II

EJ

II

IDENTIFICATION PROGRAM-ID.

SEND-RECEIVE.

•

INPUT-OUTPUT FILE-CONTROL.

SELECT

ORGANIZATION ACCESS

FILE

SELECT

ORGANIZATION ACCESS

FILE

SECTION.

PRINT-FILE

IS

STATUS

UPDATE-FILE

IS

STATUS

•

WORKING-STORAGE

77

UPDATE-FILE-STAT PRINT-FILE-STAT

77

•

PROCEDURE DECLARATIVES. DISK-ERROR

USE AFTER

DISKX.

PRINT-ERROR

USE AFTER

PRINTERX.

END EXECUTE

MAIN-ROUTINE.

PERFORM

DIVISION.

SECTION.

ERROR

DISPLAY "ERROR DISPLAY DISPLAY "TRANSMISSION STOPPED. STOP RUN.

SECTION.

ERROR

DISPLAY "ERROR DISPLAY DISPLAY "TRANSMISSION STOPPED. STOP RUN.

DECLARATIVES.

SECTION.

OPEN

•

DIVISION.

ASSIGN

IS

SEQUENTIAL

SECTION.

SEQUENTIAL

IS

PRINT-FILE-STAT.

ASSIGN

IS

SEQUENTIAL

IS

UPDATE-FILE-STAT.

PROCEDURE

ON

"FILE

STATUS

PROCEDURE

"FILE

1 .

ON

STATUS

TO

PRINTER

TO

DISK

PIC

XX.

PIC

XX.

ON

UPDATE-FILE.

UPDATE-FILE

IS " UPDATE-FILE-STAT.

ON

PRINTER-FILE

IS " PRINT-FILE-STAT.

I/O

RUN

PRINT-FILE.

I/O

RUN

DURING

SEND".

STOPPED.".

DURING

STOPPED.".

WRITE".

Figure 5.2. routine

The

INVALID

KEY

Clause

When using the random access method, you can specify an

clause with

an indexed or relative organization.

statements you want executed each time an invalid key An

EXCEPTION

If

the

to indicate the condition.

5-

8 IBM 5280 COBOL Programmer's Guide

FILE

COBOL

READ,

jERROR

STATUS

statements for

WRITE,

REWRITE,

procedure,

clause

is

specified, a value

Status

Key

and

EXCEPTION

and

DELETE

The

clause consists of a set

if

specified, will not be executed.

is

verbs for files having

is

found.

placed in the

/ERROR

INVALID

of

COBOL

Status

KEY

Key

TheAT

END

Clause

You can specify an When the end-of-file that

will not be executed.

If

the

to indicate the condition.

Error Handling Considerations

Figure 5.3 shows the actions taken for all the combinations of INY digit of the

tffNote

• The

•

AT

END

is

detected, control

follows

ALID

FILE

AT

END.

STATUS

KEY, and

Status

Key.

An

EXCEPTION

clause

EXCEPTION

the following:

return

is

always to the next verb unless the request

error contained an

EXCEPTION

AT

END

jERROR

the open status.

If

an

AT

END

or

INY

ALID

EXCEPTION

jERROR

these two conditions occur.

clause with a

is

specified, a value

or

procedure is executed only

READ

is

passed to the imperative statement

jERROR

in sequential access mode.

procedure,

is

placed in the

if

AT

jERROR

procedure based on the first

that

INY

ALID

KEY clause.

if

specified,

Status

END,

caused the

the file

KEY clause is present, an

procedure will not be executed when either

Key

is

in

of

Chapter

5.

Diskette

Input/Output

5-

9

First Digit

of

Status

Key

EXCEPTION/ERROR

No

AT

END/INVALID

KEY

Procedure

No AT END

KEY KEY

/INV

ALID

AT

EXCEPTION/ERROR

With

END

/INV

ALID

No

Procedure

AT

END

/INV

KEY

ALID

0 The verb after the AT See Note 1 and Note

END

(lNV

condition)

(Other

1.

2.

ACCESS

1

condition)

2

ALID

KEY

3

9

errors) request executes. request executes.

The

AT

The

INVALID

IS

(A T

(Permanent error) request executes.

Note otherwise, the compiler issues a severe error message and makes the object module unexecutable.

Note and unexecutable.

END

or

INVALID

clauses executes. clause executes.

The AT

END

executes.

The

INVALID

clause executes. clause executes.

The verb

The

END

phrase must be specified when

KEY phrase must be specified when

RANDOM

after

verb after the

are specified; otherwise, the compiler issues a severe error message and makes the object module

KEY

clause See Note

KEY See

the

I/O

Note

The verb request executes.

The verb after the

ACCESS

1.

2.

after

the

I/O

is

sequential, when no

ORGANIZATION

The verb after the AT The verb after the

2. END

or

INVALID

The AT

END

executes.

The

INVALID

The verb after the The INV

ALID

KEY or

END

clause executes.

The verb after the INV

ALID

KEY or AT

END

clause executes. executes, followed by the

EXCEPTION/ERROR

IS

INDEXED

KEY request executes.

clause

KEY

or

ORGANIZATION

The ERROR executes, followed by the verb after the

AT

ERROR executes, followed by the verb after the

The

ERROR

verb

routine is specified;

EXCEPTION

procedure

I/O

EXCEPTION

procedure

I/O

EXCEPTION

procedure

I/O

EXCEPTION

procedure

after

the

I/O

IS

RELATIVE,

I/O

/

request.

/

request.

/

request.

/

request.

Permanent

5-

10

IBM 5280 COBOL Programmer's Guide

I/O

Errors

Figure 5.3. COBOL statement execution with

If

an

I/O

error occurs while accessing a file, COBOL will set the Status Key to 30. COBOL will not accept additional following an the file.

I/O

error. Therefore, if an

It

may be necessary to create the file again.

READ

I/O

AT

END

and

INVALID

or

WRITE

requests

error occurs, you should

KEY

CLOSE

Processing Files with Sequential File Organization

The table in figure 5.4 summarizes the COBOL statements used for reading, writing and updating a sequential file.

SEQUENTIAL Organization

ASCII

File Processing

Creating a Sequential File

Division

Environment

Division

Procedure OPEN

Division READ

Reading Writing

SELECT

ASSIGN

STATUS

FILE ACCESS IS ACCESS IS

SEQUENTIAL SEQUENTIAL

INPUT

OPEN

1-0

CLOSE CLOSE

SELECT SELECT ASSIGN ASSIGN FILE STATUS

OPEN OUTPUT OPEN OPEN EXTEND READ WRITE REWRITE

Updating

FILE STATUS

ACCESS IS

SEQUENTIAL

1-0

CLOSE

Figure 5.4. Statements used with sequential file organizations

You can process ASCII-encoded files with a sequential organization by specifying the The rules for coding the

CODE-SET

clause in the file description entry

clause are given in in the 5280 COBOL

(FD

entry).

Language Reference.

If

ASCII

files

are

to be processed, your 5280 system must have included

support when it was installed.

The following guidelines apply in creating a file with a sequential

organiza tion:

1.

Use

WRITEs

to create a sequential file.

Reading from a Sequential File

2.

Specify error will occur, setting the

After

OUTPUT

the

OPEN

mode in the corresponding

Status

Key to 92.

OUTPUT,

any

data

formerly present in the file

OPEN.

Otherwise, a logic

is

no

longer accessible.

3.

If

the end

occurs, setting the

"COBOL

See apply when allocating

of

the extent

is

Status

Requirements for

data

sets for your program.

reached on a diskette file, a boundary error

Key to 34.

Data

Sets"

in

Chapter

8 for the rules

that

The following guidelines apply in reading records from a file with a sequential organiza tion:

1.

Use the

2.

INPUT

Otherwise, a logic error will occur, setting the

3.

The records the end

READ

or

of

verb to access the records.

1-0

mode must be specified in the corresponding

are

read in the order in which they appear on the file. When

file is reached, the

Status

Key

is

set to 10.

Chapter

Status

5.

Diskette

OPEN.

Key to 92.

If

the file does not

Input/Output

5-

II

contain request.

Updating a Sequential File

The sequential organization:

1.

Use a

2.

The

3.

If

unsuccessful,

4.

The

logic

92.

Multivolume Record Processing

The

1.

Only files with

volumes.

2.

A file multivolume indicator field.

3.

To you will use the

4.

To volumes you will be using. volume

multivolume this field will have been set by

5.

For reading or

be mounted. assumes

any

records,

the

Status

Key is also set to 10 on

the

first

READ

following guidelines apply in updating records from a file with a

REWRITE

record to be rewritten

there

was no preceding

1-0

mode

error

will occur on a subsequent

following rules

is

a multivolume file

create

a multivolume file, you must allocate

to replace an existing record in a file.

must

have been

the

Status

must

be specified in

READ,

Key

or

is

set to 92.

if

the preceding

the

corresponding

REWRITE,

and

guidelines apply to multivolume files:

SEQUENTIAL

and

the

first volume you

organization

if

the

Header

1 label contains a

mount

the

last record read.

READ

OPEN.

setting

can

reside on multiple

the

data

must

contain a

was

Otherwise, a

the

Status

'C'

or

set on all volumes

'C'

or

multivolume indicator.

(The

multivolume indicator

the

data

with

set

maintenance

can

be set when

utility

the

data

set is allocated

as

described in the Utilities

Reference/Operations Manual.)

For multivolume diskette

the next volume is requested;

OUTPUT

after

files, when end-of-volume is found,

the

volume

is

mounted,

the

is done. COBOL

indicator field

When a CLOSE

last volume

EXTEND

will

mark

each volume with a

and

set

the

appropriate

verb is issued,

COBOL

('L').

a multivolume file, you must allocate the

The

first volume you mount

of

the

original

HDRI

data

set which is being extended,

indicator field.

If

you

'C'

in

the

sequence

will

mark

created

HDRI

number

that

data must

('L')

the

file using

multivolume for

that

volume as

set on all

be

the

in

the

COBOL.

When

end-of-voiume is found,

the

mounted,

•

COBOL

Write

will

multivolume

•

If

the

starting

COBOL

will assign

is done,

mark

indicator

volume had a sequence

the

next voiume is requested;

each volume with a

field.

the

appropriate

sequence

'C'

in

number

after

the

HDRI

assigned to it,

number

to all

subsequent volumes.

•

When a CLOSE

verb is issued,

COBOL

will

mark

that

volume as

the last volume.

updating

If

the

that

the first volume

a multivolume file,

HDRI

sequence

is

mounted.

number

If

the

first volume

is blank,

it

is

not blank,

then

of

the

COBOL

Key to

'L'

in the

'L'

for

WRITE

volume.

the

last

COBOL,

it

is

file must

will

5-

12

IBM 5280 COBOL Programmer's Guide

SeQUENTIAL Organization

Example

ensure mount

that the

first volume if it

If

end-of-volume

the

first volume

is

mounted and will prompt

is

not.

recognized during execution

the

of a READ and logical end-of-file has not been reached, the following actions taken:

1.

The

2.

next volume

After

the volume is mounted, the first

is

requested.

data

record on it

is

available.

If

sequence checking is being performed, as indicated by a nonblank sequence number field in the first volume, then all subsequent volumes

will be prompted to mount

are

mounted in their proper order.

the

correct volume

COBOL

if

one is mounted out

order.

The

program example in figure 5.5 updates

INPUT-FILE INPUT-EMPLOYEE-NUMBER

replaces

IDENTIFICATION PROGRAM-ID. UPDATE-SEQUENTIAL. ENVIRONMENT

CONFIGURATION

SOURCE-COMPUTER. OBJECT-COMPUTER. SPECIAL-NAMES. CONSOLE INPUT-OUTPUT FILE-CONTROL.

DATA

FILE

FD

01 INPUT-RECORD.

FD 01

WORKING-STORAGE

01

and

the

I-O-FILE

the

original record in

DIVISION.

SECTION.

SELECT

DIVISION. SECTION.

INPUT-FILE

05 05 05 05 05 I-O-FILE I-O-RECORD. 05 05 05 05 05

DISP-RECORD. 05 05 05

INPUT-FILE

ASSIGN

FILE

TO

I-O-FILE

TO

STATUS

LABEL

INPUT-EMPLOYEE-NUMBER INPUT-EMPLOYEE-NAME INPUT-EMPLOYEE-CODE INPUT-EMPLOYEE-SALARY

FILLER

I-O-EMPLOYEE-NUMBER I-O-EMPLOYEE-NAME I-O-EMPLOYEE-CODE I-O-EMPLOYEE-SALARY FILLER

OP-NAME PICTURE FILLER SK

I-O-FILE

IBM-370. IBM-5280.

DISK.

DISK

IS

SK.

RECORD

LABEL

SECTION.

PICTURE

and

until a

I-O-EMPLOYEE-NUMBER.

IS

RECORDS

I-O-FILE.

match

with

SCREEN.

STANDARD.

PICTURE PICTURE PICTURE

PICTURE

X(

5).

XX

VALUE

XX

VALUE

It

is

found between

INPUT-RECORD.

PICTURE PICTURE PICTURE PICTURE

PICTURE

SPACE.

9

X(28)

9. 9(6)V99.

X.

9(6). X(28).

9.

9(6)V99.

X.

"zz".

reads

(6)

operator to

statement,

are

made

will ensure

The

operator

It

then

.

that

of

Figure 5.5. Example

of

processing files with a sequential organization

Chapter

5.

Diskette

Input/Output

(Part 1 of

5~

13

2)

PROCEDURE OPEN-FILES.

OPEN

PERFORM PERFORM

UPDATE-TEST-LOOP.

DIVISION.

INPUT

IF

SK

MOVE PERFORM GO

IF

INPUT-EMPLOYEE-NUMBER = I-O-EMPLOYEE-NUMBER

PERFORM GO

I~'

INPUT-EMPLOYEE-NUMBER GREATER

PERFORM GO

INPUT-FILE

NOT

=

"00"

"OPEN"

ERROR-OUT-1

TO

STOP-RUN. READ-INPUT. READ-UPDATE.

I-0-REWRITE-1

TO

UPDATE-TEST-LOOP.

READ-UPDATE

TO

UPDATE-TEST-LOOP.

* I-O-EMPLOYEE-NUMBER *

NO

MATCH

HAS PERFORM DISPLAY INPUT-RECORD MOVE

SPACES PERFORM GO

CLOSE-FILES.

STOP-RUN.

ERROR-OUT-1.

I-0-REWRITE-1.

READ-INPUT.

READ-UPDATE.

TO

CLOSE

STOP RUN.

DISPLAY DISP-RECORD

REWRITE

IF

SK MOVE PERFORM

PERFORM PERFORM

READ

INPUT-FILE

READ

I-O-FILE

PERFORM

BEEN

ERROR-OUT-1.

TO

DISP-RECORD.

READ-INPUT.

UPDATE-TEST-LOOP.

INPUT-FILE

I-O-RECORD

NOT

=

"00"

"RWRTE"

READ-INPUT. READ-UPDATE.

ERROR-OUT-1

TO

ERROR-OUT-1.

AT

TO

OP-NAME

IS

FOUND

I-O-FILE.

UPON

FROM

OP-NAME

AT

END

GO

1-0

I-O-FILE.

GREATER

SO

UPON

GO

MOVE

TO

THAN

PUT

OUT

SCREEN.

INPUT-RECORD.

TO

CLOSE-FILES.

"NOT

CLOSE-FILES.

THAN

I-O-EMPLOYEE-NUMBE

INPUT-EMPLOYEE-NUMBER

ERROR

FOUND"

MESSAGE

TO

DISP-RECORD

Figure 5.5. Example

5-

14

IBM 5280

COBOL

Programmer's

Guide

of

processing files with a sequential organization

(Part 2 of

2)

Processing Files with a Relative Organization

The table in figure 5.6 shows the file processing.

COBOL

RELA

TIVE

Statements

Organization

available for relative

Division

Environment

Division

Procedure

Division

Reading Writing Updating

SELECT ASSIGN ORGANIZA

IS RELATIVE

RELA TIVE

FILE

ACCESS IS

SEQUENTIAL

ACCESS IS

RANDOM

OPEN OPEN READ CLOSE CLOSE

TION

KEY

STATUS

INPUT

1-0

SELECT

ASSIGN ASSIGN ORGANIZA

IS RELATIVE RELA TIVE KEY FILE STATUS FILE STATUS ACCESS IS ACCESS IS

SEQUENTIAL SEQUENTIAL ACCESS IS ACCESS IS

RANDOM

OPEN WRITE

TION

OUTPUT

SELECT

ORGANIZA

IS RELATIVE

RELA TIVE KEY

RANDOM

For ACCESS IS

SEQUENTIAL

OPEN READ REWRITE DELETE CLOSE

For

ACCESS IS

RANDOM

OPEN READ WRITE REWRITE DELETE CLOSE

TION

1-0

Creating a Relative File

Figure 5.6. Statements used with relative file organizations

The following guidelines apply in creating a file with a relative organization:

1.

Use

2.

Specify the opened in

WRITE

statements to create a relative file.

OUTPUT

mode in the corresponding

mode,

data

formerly present in the file

OPEN.

When a file

is

no longer

accessible.

3.

If

you specify

desired number

be inserted from the last record written, to Null records

which

is

contain the

ACCESS

of

are

.empty records represented by the characters

IS

SEQUENTIAL,

records. A subsequent

inserted in the first byte

5280 delete

character

you can first write the

CLOSE

the

of

each record. Null records also

specified when the

causes null records to

end-of-extent.

data

set was

x'FF',

allocated.

4.

If

you specify

be inserted

5.

Your program will never receive a null record. When you use the

ACCESS

in

the entire file.

IS

RANDOM,

the

OPEN

causes null records to

sequential access mode, only non-null records are returned; when you

Chapter

5.

Diskette

Input/Output

5-

is

15

use the random access mode, the Status Key record cannot be found.

6.

Relative files must be on single volumes.

See "Allocating Data Sets for Program Files" apply when allocating

data

sets for your program using IBM 5280 facilities.

is

set to 23, indicating the

in

Chapter 8 for the rules

that

Contents

of

Relative Key

When issuing a written will have relative record number one, the second two, the third three, and

so

on.

the number of the record just written.

WRITE

Status

When issuing a

record number in the relative key data-item before issuing the

Invalid Key conditions after a

• A non-null record already exists. The

• The record number

request is executed, an invalid key condition will occur, setting the

Key to 24 (boundary error).

duplicate record).

set to

Example - Creating a Relative File

The

program example in figure 5.7 creates a master file Employee numbers from number field

WRITE

If

a relative record key was specified, it will be updated to contain

WRITE

24

(for boundary condition).

(EMPNO).

with the sequential access mode, the first record

If

the end

with the random access mode, place the desired

WRITE

is

outside the extent of the file. The Status Key

1001

through 2001 are entered in the employee

occur when:

of

Status

extent

Key

is

reached when a

WRITE.

set to 22 (for

of

employee records.

is

5-

16

IBM 5280 COBOL Programmer's Guide

RELA

riVE

Organization

10 11 12 13 14 14 14 14 14 15 16

17

17 18 18

19 20 21 22 23 24 25 26 27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

2

4 5 6 8

000001 000002 000004 000006 000008 000010 000012 000016 000018 000020

IDENTIFICATION PROGRAM-ID. LOADIT. ENVIRONMENT

CONFIGURATION

SOURCE-COMPUTER.

OBJECT-COMPUTER.

SPECIAL-NAMES.

CONSOLE INPUT-OUTPUT FILE-CONTROL.

SELECT EMPMAS-FILE ASSIGN

ORGANIZATION ACCESS RELATIVE FILE

DATA

DIVISION.

FILE

SECTION.

FD

EMPMAS-FILE LABEL

COPY

DDS-EMPRECD.

01

WORKING-STORAGE 77 STATUS-KEY 77 77 PROCEDURE BEGIN.

FIN.

LOAD.

EMPRECD.

02

ACREC

EMPNO

02

ENAME

02 02

STRAD

02

CTYST

02

ZIPCD

02

BEGDT

02

SOSNO MARST

02

RKEY

PIC

DEMPNO

OPEN OUTPUT EMPMAS-FILE.

MOVE MOVE

DISPLAY

"EMPLOYEE

PERFORM DISPLAY

"MASTER

CLOSE EMPMAS-FILE. STOP RUN.

ADD

RKEY

MOVE

DEMPNO

WRITE

DIVISION.

SECTION.

IBM-370. IBM-5280.

IS

SCREEN.

SECTION.

MODE

KEY

STATUS

RECORDS

PIC PIC PIC PIC PIC PIC

PIC

PIC PIC

SECTION.

PIC

9(5)

PIC

9(5)

DIVISION.

SPACES "F"

TO

MASTER

UPON

SCREEN.

LOAD

1000

FILE

UPON

SCREEN.

1000

TO

EMPRECD DISPLAY " DISPLAY " DISPLAY " DISPLAY " GO

TO

FIN.

IS

ARE

X(2).

VALUE

CREATED.

GIVING

EMPNO.

INVALID

IS

RELATIVE

SEQUENTIAL

IS

RKEY

STATUS-KEY.

STANDARD.

X(00002). S9(05)V. X(00020) X(

00020) X(00020) X(00005) X(00006) X(00009). X(00001).

1.

VALUE

TO

ACREC.

FILE

O.

EMPRECD.

BEING CREATED."

TIMES.

READY

DEMPNO.

KEY

EMPLOYMENT

INVALID

DEMPNO

STATUS

IS " DEMPNO.

KEY

TO

. . . . .

KEY

DISK

FOR

UPDATE

NUMBER

IS

" RKEY.

" STATUS-KEY.

RECORDS"

" EMPNO.

Figure 5.7. Creating a relative file

Chapter

5.

Diskette

Input/Output

5-

17

Reading

from a Relative

File

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

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

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.

INDEXED

be

used for indexed file

Organization

Division Reading

SELECT ASSIGN ASSIGN ASSIGN ORGANIZA TION ORGANIZA TION

IS INDEXED

Environment

Division

Procedure

Division

RECORD FILE STATUS FILE STATUS ACCESS IS ACCESS IS ACCESS IS

SEQUENTIAL SEQUENTIAL SEQUENTIAL

ACCESS IS ACCESS IS ACCESS IS

RANDOM RANDOM

OPEN

INPUT

OPEN

1-0 READ CLOSE CLOSE

Writing Updating

SELECT SELECT

IS INDEXED

KEY RECORD KEY RECORD KEY

OPEN OUTPUT

WRITE SEQUENTIAL

ORGANIZA TION

IS INDEXED

FILE STATUS

RANDOM

ACCESS IS

OPEN 1-0 READ REWRITE DELETE CLOSE

For ACCESS IS

RANDOM

OPEN

1-0 READ WRITE REWRITE DELETE CLOSE

Two

Types

of

Indexed Files

Figure 5.9. Statements used with indexed file organizations

COBOL supports two types of indexed files. In one type, an entry for each

record

is

stored in a separate data set called an index data set. The entry

consists of the record's key and the record's location. Accessing this data set

is

similar to the key indexed access method described

Concepts

manual.

In the other type of indexed organization supported are kept in sequence in the file

by

the system each time Accessing this type of organization with the random access method equivalent of using the

direct by key access method described in the 5280

in

the 5280 System

by

COBOL, the records

you

add or delete one.

is

the

System Concepts manual.

Chapter

5.

Diskette Input/Output

5-

21

IBM 5280 Programmer's Manual

Specifications and Main Features

Frequently Asked Questions

User Manual