Work Area Format Description

The first field is the length of the work area and is set by the user to tell CSI how much data can be returned.

The second field is the minimum required length for a catalog entry and one entry's worth of returned data. If the minimum length is greater than the work area length, then the work area length must be increased to at least as much as the minimum length. If this is not done, and a resume condition occurs, the user program will appear as if in an endless loop because the same information will be returned for each resume until the first length is increased to contain the entire entry. A generation data group (GDG) with all of its associated generation data sets (GDS), or a nonVSAM data set or user catalog connector with thousands of associated aliases is seen by the CSI as one record. Thus the required length for these entries is apt to be large.

The third field is the amount of space that was used in the work area. CSI always returns a full entry. If the last entry will not fully fit in the remaining work area space, the resume flag is set and the space at the end of the work area is unused. The unused space will usually be small.

Next follows the number of field names plus 1.

A catalog name entry is returned for every catalog processed. A catalog entry may be identified because its type is x'F0'. This is an artificial type invented so that the next catalog entry can be found. The catalog entry is always followed by return information. The return code portion will be zeroes if no problems were encountered while processing the catalog during the call.

Following the catalog entry is one or more entries contained in the catalog that match the search criteria (filter key). Each entry has flags, followed by its type and name. If the flags indicate, a module id, reason code and return code follow the entry name; otherwise, the field information for the entry follows.The flag byte in front of the entry type will also indicate possible errors that were encountered.

The "MODULE ID / RSN / RC" returned in the work area is returned when an error is detected by Catalog Management. This field only exists when the flag CSIENTER is set for this entry; otherwise, it is not present. See the previous section entitled "Return Codes", subsection "Return Code 4", for a description of this information.

If no errors or messages occurred, then field information for the entry is returned as a set of lengths and then the data corresponding to the lengths.

The first length field is the length of all of the returned data for this entry. It is the total of the length of the field itself, all of the length fields following it (one per fieldname supplied in CSIFLDNM), and the length of the actual data returned for this entry. The total length field is two bytes long, unless CSIOPTNS was specified as F, in which case this length field (and all remaining length fields) are four bytes long. The reserved field following this total length is also two or four bytes long.

Next is a set of lengths corresponding to the number of fields passed in.The length fields are two bytes long if CSIOPTNS is blank and four bytes long if CSIOPTNS is F. Each length is used to determine the length and position of the returned data for the entry.

For example, if three field names were supplied on input, then there will be three field lengths. Each length will be for the data immediately following the lengths. If the lengths had values 4, 6, and 8, then following the last length, there would be 4-bytes worth of data for the first field, 4-bytes from the last length field would be 6 bytes of data for the second field, and 10 bytes from the last length would be 8 bytes worth of data for the third field. Each length is set to:

-1: If the data to be retrieved is suppressed; security data will be suppressed if the caller does not have the proper RACF® authority.
0: If no data was found for this entry. This can happen, for instance, if the data does not apply to the particular entry type being supplied.
2 or 4: If the data field to be retrieved has variable length and does not exist. Data with variable length is always returned with two- or four-byte length information preceding the data (depending on the setting of CSIOPTNS) and is included as part of data. Therefore, when the field to be retrieved does not exist, this preceding length information is set to 0 and the total length of the data returned will then be the length of this preceding length information.
n: If the data field to be retrieved has fixed length and does not exist. n is the length of the fixed length data and the data is set to be all 'FF'X.
n: If the data is retrieved and is the total length of the data retrieved.

The following illustration shows the general relationship of the length fields and their corresponding data.

Restriction: Total information returned for an entry cannot exceed 65,535 characters unless CSIOPTNS is set to F (use fullword lengths). If CSIOPTNS is not set to F, any attempt to retrieve information greater than 65,535 characters results in setting the CSIENTER flag in that entry and the CSI request will continue with the next data set (if any). When the CSI request is complete, the return code will be 100 and the reason code will be 4, unless a more serious error occurs. For the entry with the CSIENTER flag set, the CSIRETN value is returned; the return code is 44 and the reason code is 14. For example, a request for the NAME fieldname of a user catalog (or data set) that has more than 1489 aliases defined would result in this error.