File Status Codes

When a CICS file command cannot do what you asked, CICS raises an exceptional condition - the CICS equivalent of a file status code. Your program learns about it through the RESP option, and decides what to do instead of letting CICS abend the task.

The main file exceptional conditions

• NORMAL - the command worked. Always test for this first.
• NOTFND - the record does not exist. Raised by READ, REWRITE, DELETE and by STARTBR/RESETBR when no record matches.
• DUPREC - a record with the specified key already exists. Raised by WRITE, and by REWRITE if an alternate key is duplicated.
• ENDFILE - there are no more records in the browse direction. Raised by READNEXT and READPREV.
• FILENOTFOUND - the file is not defined in the FCT.
• NOTOPEN - the file is defined but not open.
• DISABLED - the file was disabled by a master terminal operator.
• ILLOGIC - a VSAM logical error occurred.
• IOERR - a physical I/O error occurred; RESP2 carries the VSAM feedback code.
• INVREQ - the request is invalid, for example REWRITE without a prior UPDATE read, or READNEXT without STARTBR.
• LENGERR - the record is longer than the file allows (WRITE/REWRITE) or longer than the INTO area (READ).
• NOSPACE - the file has no space left for the record (WRITE/REWRITE).
• NOTAUTH - the user is not authorized for the file.

RESP, RESP2 and DFHRESP

• Code RESP(data-name) on any CICS command. After the command, the field holds a numeric code for what happened.
• Compare it with DFHRESP(condition-name), for example IF RESPONSE-CODE = DFHRESP(NOTFND).
• Code RESP2(data-name) as well when you need extra detail, such as the VSAM reason code behind an IOERR or ILLOGIC.
• The response field is typically defined as PIC S9(08) COMP in working storage.
• If you omit RESP, CICS default handling applies - for most conditions that means abnormally terminating the task. There is also the HANDLE CONDITION command, which routes a named condition to a paragraph, but the RESP pattern keeps the check next to the command and is easier to follow.
• Example of testing file status codes:-
  
  EXEC CICS READNEXT FILE('INVOICE') INTO(INVOICE-RECORD) RIDFLD(INV-INVOICE-NUMBER) RESP(RESPONSE-CODE) END-EXEC. EVALUATE RESPONSE-CODE WHEN DFHRESP(NORMAL) ADD 1 TO INVOICE-COUNT ADD INV-INVOICE-TOTAL TO INVOICE-TOTAL WHEN DFHRESP(ENDFILE) MOVE 'Y' TO INVOICE-EOF-SW WHEN OTHER PERFORM 9999-TERMINATE-PROGRAM END-EVALUATE.