Server Functionality

CICS Server Administration and Operation

Chapter 6: Restrictions

The record-by-record file access services of the Mainframe Access Product Suite attempt to emulate IBM VS COBOL II batch processing whenever possible. For this reason, and because Mainframe Access servers access VSAM data sets, the server processing may differ from the behavior observed when the same program accesses similar files on a workstation or other Micro Focus COBOL supported platform. The purpose of this chapter is to identify areas in which the Mainframe Access servers are known to produce results that are unique to either VSAM data processing or the IBM mainframe environment.

Since the record-by-record file access functionality is a server-only implementation of Fileshare Version 2, and since it is currently restricted to processing MVS data sets, the list of action codes which the record-by-record support can process is restricted. See the chapter Server Functionality for a list of action codes supported by the Mainframe Access servers.

See the appendix Status Codes for a list of status codes that the Mainframe Access servers return either in addition to, or instead of the status codes returned by other Fileshare Version 2 servers.

6.1 Reverse Sequential Processing

Record-by-record file access supports reverse processing for VSAM data sets; however, the order in which records are returned is controlled by VSAM I/O processing and not by the Mainframe Access Server, CICS or MVS itself. When processing a VSAM Key Sequenced Data Set (KSDS) via an alternate index in reverse sequence, the order in which VSAM returns records is not the reverse of the order in which the records are returned when the same data set is processed in a forward sequential manner. To understand why the order differs, you must first understand how VSAM physically stores data for an alternate index.

When defining a KSDS base cluster, you specify the length of the record and the position and length of the key. Each record stored logically consists of the key plus the non-keyed data within that record. When defining an alternate index for a KSDS file, you specify the relative offset and length of the alternate key plus a record length sufficiently large enough to hold the maximum number of occurrences of a non-unique key within the VSAM file. When records are added to the base cluster, a corresponding record is added/updated in the alternate index file. If the base cluster has 10 records with the same alternate index key, the alternate index record will contain the key value plus 10 pointers to the records in the base cluster which contain that key. If the base cluster record has a unique value in the alternate key position, the alternate index file will contain a record with that key plus a single pointer to the base cluster record which has that key value. This pattern is continued until the maximum number of record pointers that an alternate index record can hold is reached, when an error occurs. Keep in mind that record pointers in the alternate index records are stored in a predefined order (that is, in the order in which the record pointers were added to the alternate index record).

When reading a KSDS file via an alternate index in a reverse sequential manner, VSAM reads the last alternate index record and, for each base cluster record pointer within that alternate index record (in the order in which the base cluster record pointers appear from left to right), VSAM returns the associated base cluster record on the next logical read request. See Figure 1 and Figure 2 below for an example.

To illustrate this, consider a simple KSDS file that contains a primary key in the first 5 positions and a secondary key in positions 10-14. The records were loaded in order by primary key. The alternate index key for each record is the reverse order of the first 4 bytes of the primary key.

Key  data AKey<--More Data--------------->
<---><---><--><-------------------------->
A0001.....000A..Record 1
A0002.....000A..Record 2
B0001.....000B..Record 3
B0002.....000B..Record 4
B0010.....100B..Record 5
C0001.....000C..Record 6
C0002.....000C..Record 7

Figure 1: Sample KSDS File with an Alternate Index

When the KSDS file is read sequentially forward via the primary key, the records are returned in the order shown in Figure 1. Before illustrating how records are returned when the alternate index of this file is processed, let's consider how the alternate index records are written for the KSDS file shown above. In Figure 2 below, each row represents an alternate index record with the key in positions 1-4. The base cluster record pointers are represented as 4 byte relative record numbers of the original table; a base cluster record pointer of blanks indicates the end of the base cluster record pointers within that alternate index record.

AKey Base cluster record ptrs (shown as 4 byte RRN values)
<--> <----------------------------------->
000A 0001 0002
000B 0003 0004
000C 0006 0007
100B 0005

Figure 2: Sample Alternate Index for Figure 1

When the KSDS is processed via the alternate index in a forward sequential manner, records are returned in the order: 1, 2, 3, 4, 6, 7, 5. When processed in a reverse sequential manner, the order of the records returned is: 5, 6, 7, 3, 4, 1, 2.

6.2 Opening an ESDS File for Output Processing

When a VSAM Entry Sequenced Data Set (ESDS) file is opened for output processing by the record-by-record service, the file status returned depends on the status of the file when the open request is received. IBM VS COBOL II returns a file status of '37' (permanent error - file will not support a write operation in the current open mode) if the ESDS file is being opened for sequential output processing and the file already contains data. The servers also return this status code if the file has at least one record in it. If the file does not exist, a status of '35' (permanent error - attempt to open a non-optional file that is not present) is returned.

To contrast this behavior, a PC file opened for sequential output processing will cause the file to be created if it did not previously exist and to be cleared if it previously existed but contained data.

6.3 Attempting to Open a VSAM File in Use

CICS
The IBM VS COBOL II run-time system returns a file status of '93' (VSAM resource is unavailable) when attempting to open a VSAM file and the file cannot be opened in the desired mode because another job or process is using it. The CICS server returns a status of '00' to the Fileshare Client because CICS actually owns the file and not the CICS server.

6.4 Opening an Empty RRDS File

CICS
IBM VS COBOL II run-time processing returns a file status of '35' (permanent error condition - attempt to open a non-optional file that is not present) if a request is made to open a non-optional un-initialized relative record data set for sequential I/O processing and the file is not present. A file status of '05' (file not present at open) is returned if the file is optional.

If the empty RRDS file previously contained data, and a program attempts to open it for sequential output processing, a file status of '37' (open mode is incompatible with the file's attributes) is returned; the 'optional' clause has no affect on this file status. If the program attempts to open this file for extend processing and the file is not optional, a file status of '35' (open attempted for a non-optional file that is not present) is returned; specifying the 'optional' clause will result in a successful open and a file status of '0/0' being returned.

While the CICS server is able to determine if a relative record data set is empty, it cannot determine if the file previously held data that has since been deleted; thus, the CICS server treats all empty RRDS files as un-initialized data sets and so never returns a file status of '37' as described above. File status codes of '00', '05', and '35' are returned depending on the use of the optional clause and the open mode as described above.

6.5 Opening a VSAM File that is Verified During Open Processing

CICS
The IBM VS COBOL II run-time system returns a file status of '97' (open was successful; VSAM file integrity verified) when the VSAM file being opened was not successfully closed by a previous user. For IBM VS COBOL II batch programs, this status should normally be treated as if the file were successfully opened and a file status of '00' returned.

The CICS Mainframe Access server will never return this file status. CICS performs all open requests and does not provide any indication that the file integrity was verified. The CICS server simply indicates whether the file was successfully opened.

6.6 Opening a Path when the Alternate Index was not Built

CICS
Attempting to open the path of a KSDS for which the alternate index was never built (for example, the data set is defined and the VSAM BLDINDEX command failed because no records were loaded into it) results in a file status of '90' (implementation defined condition without any additional information) being returned by the IBM VS COBOL II run-time system. MVS or CICS will not open the path if this particular condition exists; thus, the MFA Server will never return this file status under these circumstances.

MVS
Path files are not stored in the MVS server FSTAB table. The MVS server uses the base file plus the actual index file.

6.7 Updating a KSDS file via a Path

CICS
The IBM VS COBOL II run-time library routines support updating a KSDS via a path using sequential I/O even if the alternate index for which the path is defined permits non-unique keys. File I/O under CICS does not permit the same type of update processing since a read request for a file containing multiple records with the same key always results in the first record with that key being returned when read for update processing; this results in CICS server being unable to read the second or any subsequent record with the same key for update processing.

With the CICS server, records are only updated via the alternate index file if no other records in the file have the same alternate index key. If multiple records have the same alternate index key and the alternate index file is being processed as the result of an OPEN request for the base cluster followed by a START request for the alternate index, the CICS server will read the alternate index sequentially and perform all updates via the base cluster.

6.8 Opening the Path of an Opened Base Cluster

CICS
The IBM VS COBOL II run-time library does not permit the opening (for I/O) of a path associated with an alternate index of a base cluster that was previously opened within the same run-unit (for I/O processing) for which a corresponding CLOSE statement has not yet been executed. The file status returned by the IBM VS COBOL II run-time system under these circumstances is '93' (VSAM resource is unavailable).

Under CICS, the filename of a base cluster can be processed independently from the filename of its alternate indexes. Under the CICS server, the request to open the path is treated as any other request to open a file and the file status returned is set according to the feedback provided by CICS. The CICS server's deadlock detection is managed by CICS.

6.9 KSDS Opened for Output Processing, Write of Duplicate Key

CICS
A file status of '02' is returned by the IBM VS COBOL II and Micro Focus COBOL run-time systems if the addition or modification of a record results in two or more records having identical key values in one or more of the alternate indexes defined on the file. This file status is returned even if the record is updated or added via a base cluster or any alternate index which supports only unique keys (i.e. the duplication occurs while updating other alternate index key records).

Under the CICS server, a file status of '00' is returned after successfully adding/updating a record which may or may not result in multiple records having the same key in one or more alternate indexes.

When attempting to write a record to an indexed file opened for sequential processing for which another record already exists with that key, Micro Focus COBOL (under OS/2) returns a file status of '21' (sequence error), whereas IBM VS COBOL II executing in MVS-batch returns a file status of '22' (duplicate key),

In this instance, the CICS server returns a status of '22'.

6.10 Deleting KSDS Records Via Sequential Read of Alternate Index

CICS
Due to CICS and VSAM locking restrictions, the CICS server may not be able to delete records obtained by sequentially reading an alternate index of a file. If the record obtained for update (delete) processing contains a non-unique key, the CICS server is unable to delete the record while maintaining proper positioning for the next sequential read operation and therefore prohibits the delete request. In this instance, the CICS server returns a file status of 4/3 (delete without successful read)

If the above scenario is used and the CICS server reads a record for which there are no duplicates of an alternate index key, the server terminates the current CICS Browse session, deletes the record using the specified alternate index file, and restarts the browse session using that alternate index for the next sequential record.

6.11 Additional Restrictions

The following additional restrictions apply:

MVS and CICS
This information applies to the CICS and MVS servers.

Alternate indexes must be built with the BLDINDEX function from the IDCAMS utility before being used.
Sparse keys are not supported.
Non-contiguous or split keys are not supported.
Duplicate records for alternate keys are always presented in ascending key order and not the order in which they were written.

The following table defines for record-by-record support the maximum record length supported by file type and organization.

Dataset Organization	File type	Maximum Record Size
F, FB, V, VB	Sequential and PDS member	32,760 bytes (MVS limit)
VS, VBS	Sequential and PDS member	62K (MF COBOL limit)
U	Sequential and PDS member	Not supported by FHREDIR
Spanned	VSAM	62K (MF COBOL limit) 32K(CICS limit)
PDS/E	PDS Extended	unknown
Packed PDS	PDS member	not supported

The following table defines for LSC support the maximum record length supported by file type and organization.

Dataset Organization	File type	Maximum Record Size
F, FB, V, VB	Sequential and PDS member	64,000 bytes
VS, VBS	Sequential and PDS member	not supported
U	Sequential and PDS member	not supported
Spanned	VSAM	64,000
PDS/E	PDS Extended	64,000 bytes
Packed PDS	PDS member	not supported

MVS
This information applies to the MVS server only.

COMMIT and ROLLBACK are not supported.
Alternate index DDNAMEs must take the form ddnamen, where ddname is the DDNAME of the base VSAM cluster and n is a single numeric digit beginning with 1 and incrementing for each additional alternate index. If ddname is 8 characters, the last character must be replaced with the single digit. Numbers must be assigned in the order in which they are defined in the ALTERNATE RECORD KEY clauses in client COBOL programs. The MVS server currently limits the number of pre-allocated alternate indexes that can be specified in this manner to 9.
Dynamic allocation of alternate indexes is accomplished by using the FSTAB macro to associate alternate indexes with a primary (base) cluster. When using FSTAB, the alternate index names specified are the VSAM path names defined in the VSAM catalog. The MVS server does not impose any additional naming conventions for these beyond what VSAM and MVS require. Alternate index references in the FSTAB entry must be in the same order as specified in the ALTERNATE RECORD KEY clauses in the client COBOL programs.

CICS
This information applies to the CICS server only.

Rewrite of alternate key records that change the key field repositions the data set.

Server Functionality

CICS Server Administration and Operation