IBM - VisualAge Cobol for Windows Programming Guide
634 pág.

IBM - VisualAge Cobol for Windows Programming Guide


DisciplinaCobol25 materiais168 seguidores
Pré-visualização50 páginas
attempt.
For VSAM, STL, and Btrieve files, in addition to the file status key, you can code a
second identifier in the FILE STATUS clause to get more detailed information on file
system input or output requests.
You can use the status key alone, or in conjunction with the INVALID KEY option, or
to supplement the EXCEPTION or ERROR declarative. Using the status key in this way
gives you precise information about the results of each input or output operation.
\u201cExample: file status key\u201d
\u201cExample: checking file system return codes\u201d on page 131
RELATED TASKS
\u201cUsing file system return codes\u201d on page 131
Example: file status key
This COBOL code performs a simple check on the status key after opening a file.
IDENTIFICATION DIVISION.
PROGRAM-ID. SIMCHK.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT MASTERFILE ASSIGN TO AS-MASTERA
FILE STATUS IS MASTER-CHECK-KEY
. . .
DATA DIVISION.
. . .
WORKING-STORAGE SECTION.
01 MASTER-CHECK-KEY PIC X(2).
. . .
PROCEDURE DIVISION.
. . .
130 Programming Guide
OPEN INPUT MASTERFILE
IF MASTER-CHECK-KEY NOT = \u201c00\u201d
DISPLAY \u201cNonzero file status returned from OPEN \u201d MASTER-CHECK-KEY
. . .
Using file system return codes
Often the two-character FILE STATUS code is too general to pinpoint the disposition
of a request. You can get more detailed information about VSAM file system input
and output requests by coding a second status area:
FILE STATUS IS data-name-1 data-name-2
The variable data-name-1 specifies the two-character COBOL file status key. The
variable data-name-2 specifies a data item that contains the file system return code
when the COBOL file status key is not zero. data-name-2 is at least 6 bytes long.
STL and Btrieve file systems
If data-name-2 is 6 bytes long, it contains the return code. If it is longer than 6
bytes, it also contains a message with further information. For example:
01 my-file-status-2.
02 exception-return-value PIC 9(6).
02 additional-info PIC X(100).
Suppose you tried to open a file with a different definition than the one with
which it was created; return code 39 would be returned in exception-return-
value, and a message telling what keys you need to perform the open would be
returned in additional-info.
VSAM file system
You must define data-name-2 as PICTURE X(n) and USAGE DISPLAY attributes, where
n is 6 or greater. The PICTURE string value represents the first n bytes of the VSAM
reply message structure. If the size of the reply message structure, m, is less than n,
only the first m bytes contain useful information.
\u201cExample: checking file system return codes\u201d
RELATED REFERENCES
\u201cSTL file system\u201d on page 97
Example: checking file system return codes
This COBOL code does the following actions:
v Reads an indexed file (starting at the fifth record)
v Checks the file status key after each input or output request
v Displays the VSAM codes when the file status key is not zero
This example also illustrates how output from this program might look if the file
being processed contains six records.
IDENTIFICATION DIVISION.
PROGRAM-ID. EXAMPLE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT FILESYSFILE ASSIGN TO FILESYSFILE
ORGANIZATION IS INDEXED
ACCESS DYNAMIC
RECORD KEY IS FILESYSFILE-KEY
FILE STATUS IS FS-CODE, FILESYS-CODE.
DATA DIVISION.
FILE SECTION.
Chapter 9. Handling errors 131
FD FILESYSFILE
RECORD 30.
01 FILESYSFILE-REC.
10 FILESYSFILE-KEY PIC X(6).
10 FILLER PIC X(24).
WORKING-STORAGE SECTION.
01 RETURN-STATUS.
05 FS-CODE PIC XX.
05 FILESYS-CODE PIC X(6).
PROCEDURE DIVISION.
OPEN INPUT FILESYSFILE.
DISPLAY \u201cOPEN INPUT FILESYSFILE FS-CODE: \u201d FS-CODE.
IF FS-CODE NOT = \u201c00\u201d
PERFORM FILESYS-CODE-DISPLAY
STOP RUN
END-IF.
MOVE \u201c000005\u201d TO FILESYSFILE-KEY.
START FILESYSFILE KEY IS EQUAL TO FILESYSFILE-KEY.
DISPLAY \u201cSTART FILESYSFILE KEY=\u201d FILESYSFILE-KEY
\u201c FS-CODE: \u201d FS-CODE.
IF FS-CODE NOT = \u201c00\u201d
PERFORM FILESYS-CODE-DISPLAY
END-IF.
IF FS-CODE = \u201c00\u201d
PERFORM READ-NEXT UNTIL FS-CODE NOT = \u201c00\u201d
END-IF.
CLOSE FILESYSFILE.
STOP RUN.
READ-NEXT.
READ FILESYSFILE NEXT.
DISPLAY \u201cREAD NEXT FILESYSFILE FS-CODE: \u201d FS-CODE.
IF FS-CODE NOT = \u201c00\u201d
PERFORM FILESYS-CODE-DISPLAY
END-IF.
DISPLAY FILESYSFILE-REC.
FILESYS-CODE-DISPLAY.
DISPLAY \u201cFILESYS-CODE ==>\u201d, FILESYS-CODE.
Coding INVALID KEY phrases
You can include INVALID KEY phrases on READ, START, WRITE, REWRITE, and DELETE
requests for VSAM indexed and relative files. The INVALID KEY phrase is given
control if an input or output error occurs because of a faulty index key.
Use the FILE STATUS clause with INVALID KEY to evaluate the status key and
determine the specific INVALID KEY condition.
INVALID KEY and ERROR declaratives
INVALID KEY phrases differ from ERROR declaratives in these ways:
v INVALID KEY phrases operate for only limited types of errors, whereas the ERROR
declarative encompasses all forms.
v INVALID KEY phrases are coded directly onto the input or output verb, whereas
ERROR declaratives are coded separately.
v INVALID KEY phrases are specific for a single input or output operation, whereas
ERROR declaratives are more general.
132 Programming Guide
If you code INVALID KEY in a statement that causes an INVALID KEY condition,
control is transferred to the INVALID KEY imperative statement. Here, any ERROR
declaratives you have coded are not performed.
NOT INVALID KEY
A NOT INVALID KEY phrase that you code is performed only if the statement
completes successfully. If the operation fails because of a condition other than
INVALID KEY, neither the INVALID KEY nor the NOT INVALID KEY phrase is
performed. Instead control passes to the end of the statement after the program
performs any associated ERROR declaratives.
\u201cExample: FILE STATUS and INVALID KEY\u201d
Example: FILE STATUS and INVALID KEY
Assume you have a file containing master customer records and need to update
some of these records with information in a transaction update file. The program
reads each transaction record, finds the corresponding record in the master file,
and makes the necessary updates. The records in both files contain a field for a
customer number, and each record in the master file has a unique customer
number.
The FILE-CONTROL entry for the master file of customer records includes statements
defining indexed organization, random access, MASTER-CUSTOMER-NUMBER as the
prime record key, and CUSTOMER-FILE-STATUS as the file status key. The following
example shows how you can use FILE STATUS with the INVALID KEY to more
specifically determine why an input or output statement failed.
.
. (read the update transaction record)
.
MOVE \u201cTRUE\u201d TO TRANSACTION-MATCH
MOVE UPDATE-CUSTOMER-NUMBER TO MASTER-CUSTOMER-NUMBER
READ MASTER-CUSTOMER-FILE INTO WS-CUSTOMER-RECORD
INVALID KEY
DISPLAY \u201cMASTER CUSTOMER RECORD NOT FOUND\u201d
DISPLAY \u201cFILE STATUS CODE IS: \u201d CUSTOMER-FILE-STATUS
MOVE \u201cFALSE\u201d TO TRANSACTION-MATCH
END-READ
Handling errors when calling programs
When a program dynamically calls a separately compiled program, the called
program might be unavailable to the system. For example, the system could run
out of storage or it could be unable to locate the load module. If you do not have
an ON EXCEPTION or ON OVERFLOW clause on the CALL statement, your application
might abend.
Use the ON EXCEPTION clause to perform a series of statements and to perform your
own error handling. For example:
MOVE \u201cREPORTA\u201d TO REPORT-PROG
CALL REPORT-PROG
ON EXCEPTION
DISPLAY \u201cProgram REPORTA not available, using REPORTB.'
MOVE \u201dREPORTB\u201c TO REPORT-PROG
CALL REPORT-PROG
END-CALL
END-CALL
If program REPORTA is unavailable, control will continue with the ON EXCEPTION
clause.
Chapter 9. Handling errors 133
The ON EXCEPTION clause applies only to the availability of the called program. If
an error occurs while