CICS allows you to access file data in a variety of ways. In an online system, most file accesses are random, because the transactions to be processed aren’t batched and sorted into any kind of order. Therefore CICS supports the keyed access method provided by VSAM. It also allows you to access data using a variety of database managers.
This book covers only VSAM Key-Sequenced Data Sets (KSDS) that are accessed by supplying a key. Other VSAM data set format types—Entry-Sequenced Data Sets (ESDS) and Relative-Record Data Sets (RRDS) are described in more detail in the CICS Application Programming Guide. CICS also supports sequential access to keyed files in several forms; one of these, browsing, is covered in the next section.
The most important information kept for each file is the symbolic filename (normally the MVS DDNAME) or the data set name. When a CICS program makes a file request, it always uses a symbolic filename. CICS looks up this name in the FCT, and from the information there it makes the appropriate request of the operating system. This technique keeps CICS programs independent of the specific resources on which they are operating.
In the examples that follow, we’ll use the symbolic filename ACCTFIL for the account file and ACCTNAM for the name file which is actually a path to the same data set via an alternate index on the last name (surname).
There are three READ commands:
Reads a record from a file.
Reads the next record during a browse of a file.
Reads the previous record during a browse of a file.
The sample application uses the first two: READ and READNEXT as seen in Browsing a File, later in this chapter.
The command to read a single record from a file is:
EXEC CICS READ FILE(filename) INTO(data-area) LENGTH(data-area) RIDFLD(data-area)optionsEND-EXEC
The options for this command are:
Specifies the name of the file that you want to access. It is required in all READ commands. The entry in the CICS File Control Table (FCT) is used to find out the characteristics of the data set and whether it is on a local or remote system. Filenames can be up to eight characters long and, like any parameter value, should be enclosed in quotes if they are literals.
Specifies the name of the data area into which the record retrieved from the data set is to be written. When INTO is specified, LENGTH must be specified or must be capable of being deduced from the INTO option. INTO is used in the sample application associated with this book.
Specifies the maximum number of characters where the record is to be put. The LENGTH parameter is required for access to variable record length files. After the READ command is completed, CICS replaces the maximum value you specified with the true length of the record. For this reason, you must specify LENGTH as the name of a data area rather than a literal. For the same reason, you must re-initialize this data area if you use it for LENGTH more than once in the program. An overlong record raises an error condition. For the uses of the READ command we’re covering in this book, the LENGTH option is not required because it is a fixed length file and can always be deduced from the INTO parameter.
Specifies the record identification field. The contents can be a key, a relative byte address (RBA for an ESDS), or relative record number (RRN for RRDS). This parameter is also required.
Immediately upon completion of the command, the RIDFLD data area is available for reuse by the application program, even if UPDATE was specified.
Any of the following options which apply to this command can be used. Note that multiples of these may be used. Except where noted, you can use them in any combination.
Means that you intend to update the record in the current transaction. Specifying UPDATE gives your transaction exclusive control of the requested record (possibly over a whole group of records known as a control interval if you are not using VSAM’s Record Level Sharing (RLS) facility). Consequently, you should use it only when you actually need it; that is, when you are ready to modify and rewrite a record.
Means that you are going to handle all exceptional conditions that CICS may raise when processing your request. Modern usage is to use RESP and RESP2 instead.
Means that you are going to handle all exceptional conditions that CICS may raise when processing your request. This is an alternative to the older NOHANDLE option and requires a separate data area into which CICS places the value indicating success or otherwise in addition to the standard EIBRESP field in the EIB CICS that is always used. The EIB is explained in more detail in The EXEC Interface Block (EIB) in Chapter 11.
Returns a value that may further qualify the RESP response; the data-area value mirrors the EIBRESP2 value in the EIB.
In program NACT02, we need to find out whether the requested record is there. The command we use is shown in Example 5-1.
Example 5-1. The EXEC CICS READ Command in the Sample Application
EXEC CICS READ FILE(WS-LITS-FILES-ACCOUNT)
INTO(NACTREC-DATA)
RIDFLD(ACCTDO IN NACTREC-DATA)
RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXEC
IF CA-CRUD-RESP NOT DFHRESP(NORMAL)
* We may have a problem and the RESP2 field may contain more information
END-IFThe major return code will be placed in CS-CRUD-RESP and a qualifier may be supplied in CA-CRUD-REAS.
In this command, the record is placed in the data area named NACTREC-DATA so it should be a data structure corresponding to the account file record. You could define this structure directly in the program, but you’ll also need it in several other programs. So instead you should put the record definition into a library in NACCTREC and copy it into the NACCRUD copybook, which is then copied into the NACT02 program.
In NACCCRUD:
10 NACTREC-DATA.
COPY NACCTREC.In NACT02:
01 DFHCOMMAREA
COPY NACCCRUD.Here ACCTDO IN NACTREC-DATA is where the account number was passed by the frontend that called the program. NACTREC-DATA is the location where the data is to be passed back to the frontend program.
In any application, it is a good idea to keep your record layouts in a library and copy them into the programs that need them. Even in the simplest of applications, the same record is usually used by several programs. This procedure prevents multiple programs from using different definitions of the same thing.
This argument applies equally well to any structure used in common by multiple programs. Map structures are a prime example, as are parameter lists and communication areas, which we’ll discuss later. Apart from its value in the initial programming stage of an application, this technique greatly reduces the effort and hazards associated with any change to a record or map format. You can make the changes in just one place (your library) and then simply recompile all the affected programs. Example 5-1 also introduces the method of testing the major CICS return code. The CICS translator replaces the DFHRESP(condition) with the numeric return code so programmers are able to write intelligible code.
Example 5-2 shows the COBOL record definition we need of the account file in the sample application. Its fields are described beginning at the 20 level in order to allow it to be used within other structures.
Example 5-2. Record Definition for the Account File
20 ACCTDO PIC X(5). //Account number20 SNAMEDO PIC X(18). //Last/surname20 FNAMEDO PIC X(12). //First name20 MIDO PIC X. //Middle initial20 TTLDO PIC X(4). //Title e.g., Mr./Mrs.20 TELDO PIC X(10). //Telephone number20 ADDR1DO PIC X(24). //Address line 120 ADDR2DO PIC X(24). //Address line 220 ADDR3DO PIC X(24). //Address line 320 AUTH1DO PIC X(32). //Additional Authorized Card User 120 AUTH2DO PIC X(32). //Additional Authorized Card User 220 AUTH3DO PIC X(32). //Additional Authorized Card User 320 AUTH4DO PIC X(32). //Additional Authorized Card User 420 CARDSDO PIC X. //Number of cards issued to Customer20 IMODO PIC X(2). //Month card issued20 IDAYDO PIC X(2). //Day card issued20 IYRDO PIC X(2). //Year card issued20 RSNDO PIC X. //Reason code for card issued20 CCODEDO PIC X. //Card status coded e.g. G for Gold20 APPRDO PIC X(3). //Code of card issue approvers20 SCODE1DO PIC X. //Additional privilege code 120 SCODE2DO PIC X. //Additional privilege code 220 SCODE3DO PIC X. //Additional privilege code 320 STATDO PIC X(2). //Account status20 LIMITDO PIC X(8). //Customer Account Credit Limit20 PAY-HIST OCCURS 3. //Pay History first of last three25 BAL PIC X(8). //Account Balance25 BMO PIC 9(2). //Month25 BDAY PIC 9(2). //Day25 BYR PIC 9(2). //Year25 BAMT PIC X(8). //Amount of balance25 PMO PIC 9(2). //Payment month25 PDAY PIC 9(2). //Payment day25 PYR PIC 9(2). //Payment year25 PAMT PIC X(8). //Payment mmount
The record format is already fixed and used by batch programs. Our online CICS sample program must use the same record definition.
When you search by name using NACT05, you need to be able to point to a particular record in the file, based on end-user input which maybe anywhere in the file. Then you can start reading the file sequentially from that point on. The need for this combination of random and sequential file access—called browsing—arises frequently in online applications. Consequently, CICS provides a special set of EXEC CICS browse commands to make this job easier, namely: STARTBR, READNEXT, READPREV, and ENDBR.
Before looking at these commands, a few words about the performance implications of browsing. Transactions that produce lots of output screens can monopolize system resources. A file browse is often guilty of this. Having a long browse can put a severe load on the system, delaying other transactions and increasing overall response time.
The CICS default design model assumes the end user initiates a transaction that accesses a few data records, processes the information, and returns the results to that user. This process may involve numerous I/O waits that allow CICS to schedule and run other tasks. However, CICS is not an interrupt-driven multitasking system—tasks that involve small amounts of I/O relative to processing are able to monopolize the system regardless of priority.
The STARTBR (start browse) command gets the process started. It tells CICS where in the file you want to start browsing. The format is:
EXEC CICS STARTBR FILE(filename) RIDFLD(data-area) options END-EXEC
The FILE and RIDFLD parameters are described in the READ command. The options allowed are EQUAL and GTEQ; you cannot use them both. They are defined as follows:
Specifies that the search is satisfied only by a record having the same key (complete or generic) as that specified in the RIDFLD option.
Specifies that, if the search for a record having the same key (complete or generic) as that specified in the RIDFLD option is unsuccessful, the first record having a greater (higher in the collating sequence) key satisfies the search.
Starting a browse does not make the first eligible record available to your program; it merely tells CICS where you want to start when you begin issuing read commands. To get the first record, and for each one in sequence after that, you use the READNEXT command:
EXEC CICS READNEXT FILE(filename) INTO(data-area) LENGTH(data-area) RIDFLD(data-area) END-EXEC
The FILE, INTO and LENGTH parameters are defined in the same way as they are in the READ command. You need the FILE parameter because CICS allows you to browse several files at once, and the FILE parameter tells which one to read.
You cannot execute a READNEXT command for a file unless you’ve first executed a successful STARTBR command for that file. The RIDFLD parameter is used in a somewhat different way. On the READ and STARTBR commands, RIDFLD carries information from the program to CICS; on READNEXT, the flow is primarily in the other direction: RIDFLD points to a data area into which CICS will “feed back” the key of the record it just read. Make sure that RIDFLD points to an area large enough to contain the full key; otherwise any adjacent fields in storage will be overwritten. Don’t change it, either, because you’ll interrupt the sequential flow of the browse operation. Note that this area must be the same one used in the STARTBR command.
There is a way to do what is called “skip sequential” processing in VSAM by altering the contents of this key area between READNEXT commands. Although we won’t be covering this here, we mention it only to explain why you should not inadvertently change the contents of the data-area in RIDFLD while browsing the file.
When you’ve finished reading a file sequentially, terminate the browse with the ENDBR command:
EXEC CICS ENDBR FILE(filename)
END-EXECHere FILE functions as it did in the READNEXT command; it tells CICS which browse is being terminated, and obviously must name a file for which a successful STARTBR has been issued earlier.
The first thing you have to do is construct a key that starts the browse in the right place. The key of the name file consists of the last name (surname). The idea is to build a key that consists of the characters the user keyed in as the last name (surname). Then you can use the GTEQ option on our STARTBR command to get the first qualifying record. For example:
05 WS-LIMIT-NAMES.
10 WS-BROWSE-SNAME PIC X(18) VALUE SPACES.
10 WS-MAX-SNAME PIC X(18) VALUE SPACES.
10 WS-MIN-FNAME PIC X(12) VALUE SPACES.
10 WS-MAX-FNAME PIC X(12) VALUE SPACES.You can then set up the parameters for the search limits. This data comes from the area passed to the NACT05 program which performs this name search. You also need to know where to stop the browse.
Certainly this stops when you overflow the capacity of the data passing area, but you may run out of eligible names before that. So you need to construct a last name value that is the highest alphabetically that could meet your match criteria. If the last name in the record exceeds this value, you know that you’ve read all the (possibly) eligible records. This limiting value is named WS-MAX-SNAME.
Finally, as you read, you need to test whether the forename matches sufficiently to return the record to the caller or not. If you define WS-MIN-FNAME as the smallest allowable value and WS-MAX-FNAME as the largest, then you need the following code to set up all of the relevant areas:
B-010.
MOVE SNAMEDO IN CA-BRWS-ENTRY (1) TO WS-PASSED-SNAME
WS-BROWSE-SNAME
WS-MAX-SNAME
*
INSPECT WS-MAX-SNAME REPLACING ALL SPACES BY HIGH-VALUES
*
MOVE FNAMEDO IN CA-BRWS-ENTRY (1) TO WS-PASSED-FNAME
WS-MAX-FNAME
WS-MIN-FNAME
*
INSPECT WS-MAX-FNAME REPLACING ALL SPACES BY HIGH-VALUES
INSPECT WS-MIN-FNAME REPLACING ALL SPACES BY LOW-VALUESSNAMEDO IN CA-BRWS-ENTRY(1) is where the input last name is passed to the program. Similarly FNAMEDO IN CA-BRWS-ENTRY(1) is where the input forename is passed to the program.
So we can now look at how the code is put together with these commands. But we need to introduce a couple of controlling values:
05 WS-AVAILABILITY-IND PIC X.
88 SOME-AVAILABLE VALUE 'Y'.
88 NONE-AVAILABLE VALUE 'N'.WS-AVAILABILITY-IND is used to control the reading loop. Also we need to note a part of the area passed to the program:
10 CA-BRWS-FOUND PIC 9(4).
88 CA-BRWS-NONE-FOUND VALUE ZERO.
10 CA-BRWS-MORE PIC 9(4).
10 CA-BRWS-MORE-X REDEFINES CA-BRWS-MORE
PIC X(4).
88 CA-BRWS-NO-MORE VALUE '0000'.CA-BRWS-FOUND indicates how many matches were found for the criteria supplied. CA-BRWS-MORE indicates if there were more matches than the number allowed for. These are copied into NACT05 from copybook NACCBRWS. Example 5-3 shows the copybook. It is also found on the CD-ROM in \Cobol Application\PC\source\copy.
Example 5-3. Sample of the NACCBRWS Copybook
* The interface to the Browse program is described in a copy book
* in order to ensure consistency. The values in this area designed
* to be in character format to enable ease of translation when the
* program is invoked from a remote system which uses a different
* encoding scheme (e.g., ASCII) than the EBCDIC of the mainframe.
*
* This is the working storage version of the interface to the
* Browse program.
*
05 WS-BRWS-COMMAREA.
*
* This is an "Eyecatcher" and integrity check field.
*
10 WS-BRWS-VERSION PIC XXX VALUE SPACES.
88 WS-BRWS-CORRECT-VERSION VALUE 'V1A'.
*
* Only two functions are provided by the Browse program:
* initiation of a Browse and Continuation of a previously
* initiated browse.
*
10 WS-BRWS-FUNCTION PIC X VALUE SPACE.
88 WS-BRWS-REQ-BROWSE VALUE 'B'.
88 WS-BRWS-REQ-CONTINUE VALUE 'C'.
88 WS-BRWS-VALID-REQUEST VALUE 'B' 'C'.
*
* The response field is designed to conform to the CICS EIBRESP
* characteristics which always contains a numeric value. There
* are also architected values to indicate errors detected by the
* Browse program itself. If there was an interface error, this
* contains a special value of 'FRMT'.
*
10 WS-BRWS-RESP PIC 9(4) VALUE ZERO.
10 WS-BRWS-RESP-X REDEFINES WS-BRWS-RESP
PIC X(4).
88 WS-BRWS-NO-ERROR VALUE '0000'.
88 WS-BRWS-BAD-FORMAT VALUE 'FRMT'.
*
* The reason field is designed to conform to the CICS EIBRESP2
* characteristics which always contains a numeric value. There
* are also architected values to indicate errors detected by the
* Browse program itself. If there was an interface error, this
* contains 'VERE' for Version Error, 'LENE' for Length Error (if
* possible), 'REQE' for Request Error, 'LIME' for Limit Error or
* 'MORE' for More Error (only occurs for a continuation request).
*
10 WS-BRWS-REAS PIC 9(4) VALUE ZERO.
10 WS-BRWS-REAS-X REDEFINES WS-BRWS-REAS
PIC X(4).
88 WS-BRWS-VERSION-ERROR VALUE 'VERE'.
88 WS-BRWS-LENGTH-ERROR VALUE 'LENE'.
88 WS-BRWS-REQUEST-ERROR VALUE 'REQE'.
88 WS-BRWS-LIMIT-ERROR VALUE 'LIME'.
88 WS-BRWS-MORE-ERROR VALUE 'MORE'.
*
* If the response contains a numeric value, this contains the
* character representation of the EIBFN value giving rise to
* the exception condition.
*
10 WS-BRWS-CICS-FUNCTION PIC 9(5) VALUE ZERO.
10 WS-BRWS-CICS-FUNCTION-X
REDEFINES WS-BRWS-CICS-FUNCTION
PIC X(5).
*
* In order to prevent excessive searches, the caller must specify
* the maximum number of matches (s)he is prepared to handle.
* Also because a COMMAREA is limited to a maximum of approximately
* 32,000 bytes, the maximum limit has been set at 80.
*
10 WS-BRWS-LIMIT-TO-GET PIC 9(4) VALUE ZERO.
10 WS-BRWS-LIMIT-TO-GET-X REDEFINES WS-BRWS-LIMIT-TO-GET
PIC X(4).
*
* The Browse program indicates the number of matches found.
* The range is zero to the limit.
*
10 WS-BRWS-FOUND PIC 9(4) VALUE ZERO.
88 WS-BRWS-NONE-FOUND VALUE ZERO.
*
* After satisfying the limit, the Browse program will place
* either '0000' in here if there are no more records satisfying
* the search criteria or a number if there are more. On a
* continuation request this number must be returned to the Browse
* program since it is used to reposition the request.
*
10 WS-BRWS-MORE PIC 9(4) VALUE ZERO.
10 WS-BRWS-MORE-X REDEFINES WS-BRWS-MORE
PIC X(4).
88 WS-BRWS-NO-MORE VALUE '0000'.
*
* The records found on file for a match. Input is in the
* surname and first name fields of the first Entry.
*
10 WS-BRWS-MATCHES.
15 WS-BRWS-ENTRY OCCURS 80.
*
* The description of the account record is placed in a copy book.
*
COPY NACWTREC.The code shown in Example 5-4 initializes the browse of the file using the STARTBR command and sets the availability indicator based on the possibility of a match.
Example 5-4. Sample Showing the Start of the Browse Procedure
C-START-BROWSE SECTION.
*
*
* This routine initializes the browse of the file via the
* STARTBR command and sets the availability indicator based
* on the possibility of a match.
*
SET CA-BRWS-NONE-FOUND TO TRUE
*
EXEC CICS STARTBR FILE(WS-LITS-FILES-NAME)
RIDFLD(WS-BROWSE-SNAME)
RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC
*
EVALUATE RESPONSE
WHEN DFHRESP(NORMAL)
SET SOME-AVAILABLE TO TRUE
WHEN DFHRESP(NOTFND)
SET NONE-AVAILABLE TO TRUE
SET CA-BRWS-NO-MORE TO TRUE
*
* If any other condition other than success or NOTFND
* occurs, then a serious problem has occurred, so the
* error handler is invoked.
*
WHEN OTHER
PERFORM Z-ERROR-HANDLER
END-EVALUATE
*
END-C-START-BROWSE.
EXIT.The code shown in Example 5-5 attempts to read a record from the file and sets the availability indicator based on its success.
Example 5-5. Sample Showing a Read of a Record
Y-READ-ONE SECTION.
*
* This code attempts to read a record from the file and
* sets the availability indicator based on its success.
*
* This section is performed from the following sections -
* D-FILL-IN-MATCHES
* E-CONTINUE-BROWSE
*
Y-010.
EXEC CICS READNEXT FILE(WS-LITS-FILES-NAME)
INTO(AN-ACCTREC)
RIDFLD(WS-BROWSE-SNAME)
RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC
EVALUATE RESPONSE
*
* If either condition occurs, it means a record was read.
*
WHEN DFHRESP(NORMAL)
WHEN DFHRESP(DUPKEY)
*
* But it may not match the full criteria.
*
IF SNAMEDO IN AN-ACCTREC > WS-MAX-SNAME
SET NONE-AVAILABLE TO TRUE
ELSE
SET SOME-AVAILABLE TO TRUE
ADD 1 TO WS-RECORDS-READ
END-IF
*
* If we have exhausted the file, then there
* are obviously no more matches.
*
WHEN DFHRESP(ENDFILE)
SET NONE-AVAILABLE TO TRUE
*
* If any other condition occurs, then a serious problem
* has occurred, so the error handler is invoked.
*
WHEN OTHER
PERFORM Z-ERROR-HANDLER
END-EVALUATE
*
END-Y-READ-ONE.
EXIT.
EJECT.The code shown in Example 5-6 terminates the browsing operations against the file.
There are three file output commands:
The REWRITE command updates the record you’ve just read. You can use it only after you’ve performed a “read for update” by executing a READ command for the same record with UPDATE specified. REWRITE looks like this:
EXEC CICS REWRITE FILE(filename) FROM(data-area) RESP(data-area) RESP2(data-area) END-EXEC
The options for this caommand are:
The same meaning as in the READ command: it is the CICS name of the file you are updating. This parameter is required.
The name of the data area that contains the updated version of the record to be written to the file. This parameter is required.
The length of the (updated) version of the record. You must specify length, as in a READ command for variable length records, but for fixed length records as in this book, the LENGTH option is not required.
The WRITE command adds a new record to the file. The parameters for WRITE are almost the same as for REWRITE, except that you have to identify the record with the RIDFLD option. (You do not do this with the REWRITE command because the record was identified by the previous READ UPDATE operation on the same data set.) The format of the WRITE command is:
EXEC CICS WRITE FILE(filename) FROM(data-area) LENGTH(data-value) RIDFLD(data-value) RESP(data-area) RESP2(data-area) END-EXEC
The key option for this command is:
The data area containing the key of the record to be written. If the key is located at the front of the record, its argument will be the same as the FROM argument.
The DELETE command deletes a record from the file, and looks like this:
EXEC CICS DELETE FILE(filename) RIDFLD(data-area) RESP(data-area) RESP2(data-area) END-EXEC
The parameters are defined in the same way as for the WRITE and REWRITE commands. You can delete a record directly, without reading it for update first. When you do this you must specify the key of the record to be deleted by using RIDFLD. Alternatively, you can decide to delete a record after you’ve read it for update. In this case, you must omit RIDFLD.
Program NACT02 uses all three of the file output commands. For add requests, it issues the command:
EXEC CICS WRITE FILE(WS-LITS-FILES-ACCOUNT)
FROM(NACTREC-DATA)
RIDFLD(ACCTDO IN NACTREC-DATA)
RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXECACCTDO IN NACTREC-DATA is where the frontend program passed the data of the record to be added.
For a modification, the program first reads the record in question, with UPDATE specified:
EXEC CICS READ FILE(WS-LITS-FILES-ACCOUNT) UPDATE
INTO(OLD-ACCTREC)
RIDFLD(ACCTDO IN NACTREC-DATA)
RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXECThen it merges this old data with the new version of the record, again at ACCTDO IN NACTREC-DATA. Finally, it replaces the old record with the new one, in the command:
EXEC CICS REWRITE FILE(WS-LITS-FILES-ACCOUNT)
FROM(NACTREC-DATA)
RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXECFor a deletion, the program issues the command without reading it for update. Therefore the key (RIDFLD) is required in the DELETE command, which is:
EXEC CICS DELETE FILE(WS-LITS-FILES-ACCOUNT)
RIDFLD(ACCTDO IN NACTREC-DATA)
RESP(CS-CRUD-RESP) RESP2(CS-CRUD-REAS)
END-EXECIf you have created a lock with a READ UPDATE command and then decide that you don’t need it, you use an EXEC CICS UNLOCK FILE(fileName) RIDFLD(key) command to release it.
A wide variety of conditions can arise when using file commands. Here are some of the conditions passed to your program in the RESP field that can arise when you use the file commands that have just been described. A mapping between the response value and the following name can be found in the NACT04 program:
Occurs if a file is disabled. A file may be disabled because:
It was initially defined as disabled and has not been enabled since.
It has been disabled by an EXEC CICS SET command or by the CEMT[2] transaction.
Means that if a VSAM record is retrieved by way of an alternate index with the NONUNIQUEKEY attribute; another alternate index record with the same key follows. It does not occur as a result of a READNEXT command that reads the last of the records having the non-unique key.
Means that there is already a record in the file with the same key as the one that you are trying to add with a WRITE command. This condition may result from a user error or may be expected by the program. In either of these cases, there should be specific code to handle the situation. This condition is handled in the NACT02 program when dealing with the locking file, since this could mean another user has already locked the account.
It can also fall into the should-not-occur category. In this case no special code is required beyond logging information that may help find the problem, cleaning up if necessary, and identifying the problem to the user.
Means that you’ve attempted to read sequentially beyond the end of the file in a browse (using the READNEXT command). This is a condition that you should program for in any browse operation. In the example application, for instance, a search on “Zuckerman” or a similar name might cause ENDFILE, and you code for it explicitly as shown in Example 5-4 in the C-START-BROWSE SECTION in the browse program, NACT05.
Means that the symbolic filename in a file command cannot be found in the File Control Table. This is often a coding error; look for a difference in spelling between the command and the FCT entry. If it happens after the program is put into actual use (“in production”), look for an accidental change to the definition for that file. The file may be on another system or it hasn’t been created; there are any number of possibilities that could cause this response.
Is a catch-all class for errors detected by VSAM that don’t fall into one of the other categories that CICS recognizes. The RESP2 value will tell you the specific error.
Means that CICS regards your command as an invalid request for one of the following reasons:
You requested a type of operation (write, update, browse, and so on) that wasn’t included in the “service requests” of the definition for the file in question.
You tried to REWRITE a record without first reading it for update.
You issued a DELETE command without specifying a key (RIDFLD), and without first reading the target record for update.
You issued a DELETE command specifying a key (RIDFLD) for a VSAM file when a read for update command is outstanding.
After one read for update, you issued another read for update for another record in the same file without disposing of the first record (by a REWRITE, UNLOCK, or DELETE command).
You issued a READNEXT, READPREV or an ENDBR command without first doing a STARTBR on the same file.
Means that the operating system is unable to read or write the file, presumably because of physical damage. This can happen at any time, and there is usually nothing to do in the program except to abend the transaction and inform the user of the problem.
Means that the remote system indicates a failure which does not correspond to a known condition.
Is usually caused by a coding error and could result from one of the following reasons:
The length you specified on a WRITE or REWRITE operation was greater than the maximum record size for the file. (See the description of the LENGTH option in the CICS Application Programming Reference.)
You indicated a wrong length on a READ, READNEXT, WRITE or REWRITE command to a file containing fixed-length records.
Means that there’s no space in the file to fit the record you’ve just tried to put there with a WRITE or REWRITE command. This doesn’t mean that there’s no space at all in the data set; it simply means that the record with the particular key you specified will not fit until the file is extended or reorganized. Like IOERR, this may occur at any time, and should be handled accordingly.
Means that a resource or command security check has failed.
Means that there is no record in the file with the key specified in the RIDFLD, parameter on a READ, READNEXT, READPREV, STARTBR, or DELETE command. NOTFND may result from a user error, may be expected by the program, or may indicate an error in the program logic:
IF NOT WS-CRUD-BAD-LOCK
EVALUATE WS-CRUD-RESP
WHEN DFHRESP(NORMAL)
CONTINUE
WHEN DFHRESP(NOTFND)
IF NOT CA-SENT-MENU
PERFORM TA-BAD-CRUD-RESPONSE (Handle abend)
END-IF
WHEN OTHER
PERFORM TA-BAD-CRUD-RESPONSE
END-EVALUATE
END-IFWhen adding:
EVALUATE TRUE
**
* when this account already exists, the user must be informed
*
WHEN WS-CRUD-NO-ERROR
SET MSG-DUPLICATE TO TRUE
MOVE-1 TO ACCTML
MOVE DFHBMBRY TO ACCTMA
SET WS-BB-ERROR-PRESENT TO TRUE
.
.
.
END-EVALUATEIn program NACT01, when you check to see if the requested account record is on file, you expect NOTFND if the request is to add a record. The actual work was done in NACT02. However, it shows a user error (in the account number) if it happens on any other type of request. For both these cases, you need to provide recovery code.
The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a close request has been received against an OPEN ENABLED file and the file is no longer in use.
The requested file is still open and in use by other requests, but a close request against the file has been received. Existing users are allowed to complete.
This condition can occur only during the execution of the following commands: READ, WRITE, DELETE, or STARTBR. Other commands cannot raise this condition because they are part of an active request.
This condition does not occur if the request is made to either a CLOSED, ENABLED file or a CLOSED, DISABLED file. In the first case, the file is opened as part of executing the request. In the second case, the DISABLED condition is raised.
As you have probably gathered from this description, NOTOPEN usually results from an operations problem, and you may want to notify the operations staff of the problem, or send a message to the user to do so.
Means that the SYSID option specifies either a name of a CICS system that is not defined in the intersystem table or a system to which the link is closed.
Before leaving the topic of file commands, we’ll list some of the other facilities that are available. You can find guidance information on using file control in the CICS Application Programming Guide, and a full list of commands, options, and exceptional conditions in the CICS Application Programming Reference. Both of these books are part of the CICS library and are found on the CD-ROM.
[2] CEMT is a CICS-supplied transaction that enables administrators to query and alter the state of CICS resources.