Appendix B: File Status Codes

Overview

File status codes are two-character values returned by the COBOL runtime after every file I-O operation (OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, START). They provide essential diagnostic information about the success or failure of file operations. Every production COBOL program should check file status codes after each I-O operation.

To use file status codes, declare a two-character data item and associate it with the file using the FILE STATUS clause:

SELECT CUSTOMER-FILE ASSIGN TO CUSTFILE
    FILE STATUS IS WS-CUST-STATUS.

WORKING-STORAGE SECTION.
01  WS-CUST-STATUS    PIC XX.
    88  CUST-STATUS-OK VALUE '00'.
    88  CUST-STATUS-EOF VALUE '10'.

Part 1: QSAM / Sequential File Status Codes

Successful Completion Codes

Code Meaning Common Causes Corrective Action
00 Successful completion The I-O operation completed without error. The record was read, written, or the file was opened/closed as requested. No action required. This is the expected return code for normal operations.
02 Successful completion — duplicate key A READ operation retrieved a record whose alternate key has a duplicate value in the file, or a WRITE/REWRITE operation created a duplicate alternate key. The operation was successful. No corrective action needed if duplicate alternate keys are expected. If unexpected, review data integrity.
04 Successful completion — record length mismatch A READ operation returned a record whose length does not match the fixed-length record description in the FD entry. The record was read, but the length differs from what was defined. Verify the FD record length matches actual data. Check for variable-length record specification. Ensure the DCB parameters match the file definition.
05 Successful completion — optional file not present An OPEN operation completed for a file declared OPTIONAL, but the file was not physically present. For OPEN INPUT, the file is treated as empty. For OPEN I-O or OPEN EXTEND, the file is created. No corrective action for expected optional files. Verify file dataset name and JCL DD statement if the file should exist.
07 Successful completion — no rewind/reel A CLOSE operation with NO REWIND or REEL/UNIT completed successfully for a non-tape file. The clause is ignored. No action required. Consider removing the NO REWIND/REEL clause for clarity if the file is not on tape.

End-of-File Codes

Code Meaning Common Causes Corrective Action
10 End of file reached A sequential READ operation reached the end of the file. No more records are available. This is a normal condition that should always be tested. Process the end-of-file condition. Set an EOF flag and stop reading. This is expected behavior, not an error.
14 Relative file boundary violation A sequential READ on a relative file reached the end of file, or a relative record number exceeds the file size. Verify the relative key value. Ensure the file contains the expected number of records.

Invalid Key Codes (2x)

Code Meaning Common Causes Corrective Action
21 Sequence error A WRITE to a sequentially accessed indexed file has a key value that is not in ascending order, or an attempt was made to change the prime key during a REWRITE. Ensure records are sorted by primary key before writing. Do not modify the primary key before REWRITE. Pre-sort input data if necessary.
22 Duplicate key A WRITE or REWRITE attempted to create a duplicate primary key value, or a duplicate alternate key value where duplicates are not allowed. Verify key uniqueness before writing. Check for duplicate records in input data. Review the file definition for DUPLICATES clause on alternate keys.
23 Record not found A READ, START, or DELETE operation specified a key value that does not exist in the file. For a random READ, the record with the specified key was not found. Verify the key value before the operation. Use a START with a condition check before sequential READ operations. Handle the "not found" condition gracefully.
24 Boundary violation / Disk full A WRITE operation failed because the file boundary has been reached. The disk is full, the maximum number of records for a relative file has been reached, or the space allocation is exhausted. Increase the SPACE allocation in JCL. Delete unnecessary datasets. Contact storage administration to increase available DASD space. For VSAM, extend the file with IDCAMS ALTER.

Permanent I-O Error Codes (3x)

Code Meaning Common Causes Corrective Action
30 Permanent I-O error A non-recoverable I-O error occurred. This is a catch-all for hardware or system errors that do not fit more specific categories. Check the system log for hardware errors. Verify the physical device is operational. Review the JCL for correct DD statement. Run a file check utility (IEBCOMPR, IDCAMS VERIFY).
34 Boundary violation — record beyond limits A WRITE operation attempted to write a record that would exceed the externally defined file boundaries. Similar to status 24 but specific to sequential files. Increase SPACE allocation in JCL. Specify a secondary extent. Use RLSE option in SPACE to release unused space from other files.
35 File not found An OPEN operation failed because the file does not exist. The file was not declared OPTIONAL, and no dataset is allocated. Verify the JCL DD statement exists and the DSN is correct. Check dataset catalog entries. Ensure the file was created by a prior job step. Declare the file as OPTIONAL if absence is acceptable.
37 File mode conflict An OPEN operation attempted to open a file with attributes incompatible with the file's physical characteristics. For example, opening a file for output that is defined as input-only, or a LRECL/RECFM mismatch. Verify OPEN mode matches the file's intended use. Check DCB attributes in JCL match the FD entry. Ensure file organization in SELECT matches the actual file.
38 File locked An OPEN operation attempted to open a file that has been closed with the LOCK phrase, preventing it from being reopened. Remove the LOCK phrase from the CLOSE statement if the file should be reopenable. Ensure program logic does not close the file with LOCK prematurely.
39 File attribute conflict An OPEN operation detected a conflict between the file attributes specified in the program (FD entry and SELECT clause) and the actual file attributes on the physical file. Verify RECFM, LRECL, BLKSIZE, ORGANIZATION, and KEY specifications match the actual file. Check JCL DCB parameters against the program file definition. Rebuild the file if attributes have changed.

Logic Error Codes (4x)

Code Meaning Common Causes Corrective Action
41 File already open An OPEN was attempted on a file that is already open. Add a check before OPEN to ensure the file is not already open. Review program logic for redundant OPEN statements. Use a file-open flag.
42 File already closed A CLOSE was attempted on a file that is not open. Add a check before CLOSE to ensure the file is open. Review program logic for redundant CLOSE statements. Use a file-open flag.
43 No prior READ for DELETE/REWRITE A DELETE or REWRITE was attempted in sequential access mode without a prior successful READ. In sequential mode, DELETE and REWRITE operate on the last record read. Ensure a successful READ precedes every DELETE or REWRITE when using sequential access. Check that the prior READ returned status '00'.
44 Record length error on REWRITE A REWRITE was attempted with a record whose length differs from the record that was just read, and the file does not support variable-length records, or the new length violates the record length constraints. Ensure the REWRITE record length matches the READ record length for fixed-length files. For variable-length files, ensure the new length is within the minimum and maximum range.
46 READ failed — no valid next record A sequential READ was attempted but the preceding START or READ operation was unsuccessful, or the file position indicator is undefined. Check the status code of the prior START or READ. Reposition the file pointer with a successful START before attempting the next READ.
47 READ/START on file not opened for INPUT/I-O A READ or START was attempted on a file that was not opened with OPEN INPUT or OPEN I-O. Verify the OPEN mode. Change OPEN OUTPUT or OPEN EXTEND to OPEN INPUT or OPEN I-O as appropriate.
48 WRITE on file not opened for OUTPUT/I-O/EXTEND A WRITE was attempted on a file that was not opened with OPEN OUTPUT, OPEN I-O, or OPEN EXTEND. Verify the OPEN mode. Change OPEN INPUT to OPEN OUTPUT, OPEN I-O, or OPEN EXTEND as appropriate.
49 DELETE/REWRITE on file not opened for I-O A DELETE or REWRITE was attempted on a file not opened with OPEN I-O. Change the OPEN mode to I-O to allow both reading and updating of records.

Implementor-Defined Codes (9x)

Code Meaning Common Causes Corrective Action
90 General system error An operating system or runtime error occurred that does not map to a more specific status code. Check the system job log (JESMSGLG) for OS-level messages. Verify file allocation and system resources.
91 VSAM password failure The password provided for a VSAM file is incorrect or missing when the file requires password protection. Provide the correct password. Verify the password has not been changed by a security administrator.
92 Logic error / VSAM internal error A VSAM logical error occurred, such as invalid request or conflicting operations. Review the program I-O logic. Check VSAM return codes in the system log for specifics. Run IDCAMS VERIFY on the file.
93 VSAM resource unavailable A VSAM resource required for the operation is not available. This includes insufficient virtual storage for VSAM buffers or control blocks. Increase the REGION size in JCL. Reduce the number of concurrent files. Check VSAM buffer allocation parameters.
95 Invalid or incomplete file information The file information provided to the runtime is incomplete or invalid. AMS catalog errors or invalid file structure. Verify catalog entries with IDCAMS LISTCAT. Rebuild the catalog if corrupted. Check VSAM cluster definition.
96 No DD statement found The DD statement for the file is missing from the JCL. The file assignment name does not match any DD name. Add the missing DD statement to the JCL. Verify the ASSIGN clause name matches the DD name. Check for spelling errors.
97 OPEN successful — file integrity verified For VSAM files, the file was opened successfully but had been improperly closed previously. VSAM performed implicit verify. No immediate action required, but investigate why the file was improperly closed. Consider adding explicit IDCAMS VERIFY steps to JCL.
98 File locked by another job The file is exclusively allocated to another job or task and cannot be accessed. Wait for the other job to complete. Change DISP from OLD to SHR if shared access is appropriate. Coordinate job scheduling.
99 Record locked by another task In a CICS or multi-user environment, the specific record is locked by another task. Implement retry logic with a brief delay. Use CICS HANDLE CONDITION to manage contention. Ensure records are not held longer than necessary.

Part 2: VSAM-Specific Status Codes

VSAM files return the standard file status codes listed above, plus additional information through the VSAM return code and feedback code. The VSAM-specific codes are accessed through a six-byte extended file status area.

Extended VSAM File Status Structure

01  WS-VSAM-STATUS.
    05  WS-FILE-STATUS          PIC XX.
    05  WS-VSAM-RETURN-CODE     PIC 9(2) COMP.
    05  WS-VSAM-FUNCTION-CODE   PIC 9(1) COMP.
    05  WS-VSAM-FEEDBACK-CODE   PIC 9(3) COMP.

Common VSAM Return Code / Feedback Code Combinations

Return Code Feedback Code Meaning Corrective Action
0 0 Successful operation No action required.
0 2 Duplicate alternate key written Acceptable if duplicates are expected.
0 4 Record length mismatch Verify record length definitions.
4 4 Read past end of file Normal EOF — set EOF flag.
8 8 Duplicate primary key Verify key uniqueness before WRITE.
8 12 Key sequence error Sort records before sequential WRITE.
8 16 Record not found Verify key value; handle not-found case.
8 20 Control interval full (KSDS/ESDS) Reorganize file with larger CI or more free space.
8 24 Volume full / out of space Extend the VSAM cluster or free DASD space.
8 28 Dataset not found in catalog Verify catalog; use IDCAMS DEFINE if needed.
8 36 Key range violation Verify KEYRANGE definitions on the cluster.
8 40 Insufficient virtual storage Increase REGION or reduce buffer allocations.
8 44 Request error — concurrent operations Serialize access; avoid conflicting requests.
8 68 VSAM file not properly closed Run IDCAMS VERIFY before opening.
8 92 Dataset currently allocated to another job Wait for the other job or use share options.
8 96 CI/CA split in progress Retry the operation.
8 100 Change of password required Update the password to a valid value.
8 104 Invalid password Provide the correct password.
12 0 Logical error — invalid request Review program logic for incorrect operations.
12 4 Read to unopened dataset Ensure the file is opened before I-O.
12 8 Attempt to store record with wrong length Match record length to VSAM definition.
12 16 Invalid or missing DD statement Add or correct the DD statement in JCL.
12 64 Insufficient storage for buffers Increase REGION size or reduce BUFND/BUFNI.
16 0 Physical I-O error Check hardware. Restore from backup if needed.
16 4 Read error on data component Run IDCAMS EXAMINE INDEXTEST DATATEST.
16 8 Read error on index component Rebuild the index with IDCAMS BLDINDEX.

VSAM File Status Quick-Diagnosis Guide

When a VSAM error occurs, follow this diagnostic sequence:

  1. Check the two-byte file status code (e.g., '23', '35', '39')
  2. Check the VSAM return code and feedback code for additional detail
  3. Review the system log (JESMSGLG) for IGG and IEC messages
  4. Run IDCAMS LISTCAT to verify the cluster definition
  5. Run IDCAMS VERIFY if the file was improperly closed

Part 3: DB2 SQLCODE Reference

DB2 SQL operations return a status code in the SQLCODE field of the SQL Communications Area (SQLCA). Positive values indicate warnings, zero indicates success, and negative values indicate errors.

Successful and Warning Codes

SQLCODE Meaning Common Causes Corrective Action
0 Successful execution The SQL statement completed without error or warning. No action required.
+100 Row not found / No more rows A SELECT INTO or FETCH returned no rows, or an UPDATE/DELETE affected no rows. For cursors, this indicates the result set is exhausted. For FETCH, close the cursor and continue processing. For SELECT INTO, handle the "not found" condition in application logic.
+304 Value truncated on assignment A host variable received a value that was truncated because the host variable is too small to hold the full value. Increase the size of the host variable. Verify PICTURE clause matches the column definition.

Common Error Codes (Negative SQLCODEs)

SQLCODE Meaning Common Causes Corrective Action
-180 Invalid date/time/timestamp value A string representation of a date, time, or timestamp is not in a valid format. For example, '2024-13-01' is invalid because month 13 does not exist. Validate date values before inserting. Use proper format: DATE 'YYYY-MM-DD', TIME 'HH.MM.SS', TIMESTAMP 'YYYY-MM-DD-HH.MM.SS.NNNNNN'.
-204 Object not defined to DB2 The table, view, alias, or synonym referenced in the SQL statement is not defined in the DB2 catalog. Verify the object name and schema. Ensure the object has been created (CREATE TABLE). Check for misspellings. Qualify with the correct schema name.
-206 Column not in specified table A column name referenced in the SQL statement does not exist in the specified table or view. Verify the column name against the table definition. Check for spelling errors. Use the correct table qualifier if multiple tables are referenced.
-305 Null value without indicator variable A null value was retrieved into a host variable, but no indicator variable was specified. DB2 cannot store a null in a host variable without an indicator. Add an indicator variable to the host variable declaration. Example: INTO :HV-NAME :HV-NAME-IND. Check the indicator variable for -1 (null) before using the value.
-530 Foreign key constraint violation on INSERT/UPDATE An INSERT or UPDATE attempted to set a foreign key value that does not exist as a primary key in the parent table. Referential integrity would be violated. Ensure the parent row exists before inserting the child row. Verify the foreign key value is correct. Insert parent records before child records in batch processing.
-532 Foreign key constraint violation on DELETE A DELETE attempted to remove a parent row that has dependent child rows, and the delete rule is RESTRICT. Delete child rows before deleting the parent row. Consider changing the referential constraint to CASCADE or SET NULL if appropriate.
-803 Duplicate key on INSERT or UPDATE An INSERT or UPDATE attempted to create a row with a primary key or unique index value that already exists. Check for duplicate key values before INSERT. Use SELECT to verify uniqueness. Consider using MERGE (upsert) logic instead of plain INSERT.
-805 DBRM or package not found The application plan could not find the DBRM (Database Request Module) or package required to execute the SQL. The program was not properly bound. Rebind the plan or package. Verify the DBRM is included in the plan. Ensure the BIND was successful. Check the collection and package names.
-811 Multiple rows returned for SELECT INTO A SELECT INTO statement returned more than one row. SELECT INTO expects exactly one row; multiple rows violate this requirement. Add a more restrictive WHERE clause to return only one row. Use a cursor (DECLARE CURSOR, OPEN, FETCH) if multiple rows are expected. Verify primary key is used in the WHERE clause.
-818 Timestamp mismatch between plan and DBRM The precompiler timestamp in the DBRM does not match the timestamp in the bound plan. The program was recompiled but not rebound. Rebind the plan or package after recompiling. Ensure the build process includes both compile and bind steps. Verify the correct DBRM library is used.
-904 Resource unavailable A resource required by DB2 is unavailable. This can be a tablespace in STOP or COPY-pending status, a database that is stopped, or unavailable buffer pools. Check the status of the database and tablespace with -DIS DB(dbname) command. Restart stopped resources. Resolve copy-pending status with an image copy.
-911 Deadlock or timeout — rollback occurred The current unit of work was rolled back because of a deadlock with another application, or a lock/claim timeout was exceeded. DB2 chose this application as the victim. Implement automatic retry logic (typically 3 retries with brief delays). Design programs to access tables in a consistent order. Keep transaction duration short. Commit frequently.
-913 Deadlock or timeout — no rollback A lock or claim timeout occurred, but DB2 did not roll back the unit of work. The application must decide whether to commit or roll back. Issue a ROLLBACK and retry the transaction. Review program logic for long-running locks. Increase the IRLMRWT (lock timeout) value if timeouts are frequent.
-922 Authorization failure The authorization ID does not have the required privilege to execute the SQL statement. This includes SELECT, INSERT, UPDATE, DELETE, and EXECUTE privileges. GRANT the required privilege to the authorization ID or a role/group it belongs to. Verify the correct authorization ID is being used. Contact the DBA.
-924 DB2 connection error A connection to the DB2 subsystem could not be established, or the connection was lost. DB2 may not be active, or there may be a communication failure. Verify DB2 is started. Check the DB2 subsystem name. Verify RRS or RRSAF attachment facility is active. Restart DB2 if necessary. Check network connectivity for distributed access.

SQLCODE Quick-Reference by Category

Data Errors: | Range/Code | Category | |------------|----------| | -180 to -183 | Date/Time format errors | | -301 to -312 | Host variable errors | | -401 to -408 | Data type comparison/conversion errors | | -530 to -536 | Referential integrity violations | | -803 | Duplicate key violations |

Object/Definition Errors: | Range/Code | Category | |------------|----------| | -199 to -206 | Object not found errors | | -250 to -270 | DRDA/Distributed errors | | -805, -818 | Plan/Package binding errors |

Resource and Authorization: | Range/Code | Category | |------------|----------| | -904 to -913 | Resource/locking errors | | -922, -923 | Authorization errors | | -924 | Connection errors |

Best Practices for Error Handling

EVALUATE SQLCODE
    WHEN 0
        CONTINUE
    WHEN +100
        SET END-OF-CURSOR TO TRUE
    WHEN -803
        DISPLAY 'DUPLICATE KEY: ' WS-KEY-VALUE
        PERFORM 9000-DUPLICATE-ERROR
    WHEN -911
        ADD 1 TO WS-RETRY-COUNT
        IF WS-RETRY-COUNT <= 3
            PERFORM 9100-RETRY-LOGIC
        ELSE
            PERFORM 9999-ABEND-HANDLER
        END-IF
    WHEN OTHER
        DISPLAY 'SQL ERROR: ' SQLCODE
        DISPLAY 'SQLERRM: ' SQLERRMC
        PERFORM 9999-ABEND-HANDLER
END-EVALUATE

Quick Lookup: File Status at a Glance

Status Short Description Severity
00 Success OK
02 Success — duplicate alternate key OK
04 Success — length mismatch Warning
05 Success — optional file absent OK
07 Success — no rewind for non-tape OK
10 End of file Normal
14 Relative record boundary Normal
21 Sequence error Error
22 Duplicate key Error
23 Record not found Error
24 Disk full / boundary Error
30 Permanent I-O error Severe
34 Sequential boundary violation Error
35 File not found Error
37 Mode conflict Error
38 File locked (CLOSE LOCK) Error
39 Attribute conflict Error
41 Already open Logic Error
42 Already closed Logic Error
43 No prior READ Logic Error
44 Length error on REWRITE Logic Error
46 No valid next record Logic Error
47 READ but not open INPUT/I-O Logic Error
48 WRITE but not open OUTPUT/I-O Logic Error
49 DELETE/REWRITE not open I-O Logic Error
90 General system error Severe
91 VSAM password error Severe
92 VSAM logic error Severe
93 VSAM resource unavailable Severe
96 No DD statement Error
97 OPEN OK — implicit verify Warning
98 File locked by another job Error
99 Record locked by another task Error

Always check file status codes after every I-O operation. A program that ignores file status codes will encounter unpredictable results and will be extremely difficult to debug in production.