The COBOL copybook mfpubcat.cpy and PL/I include member mfpubcat.inc contain declarations of constants that you can use to populate the function field (FUNC) when calling the API. In the copybook, these are 78 level fields immediately following the FUNC field, and in the include member, they are declared immediately following the interface structure.
The functions supported are as follows:
| Function code | Description |
|---|---|
| ALLC | Insert a new record into the catalog, using values provided in the interface area. If the associated physical file does not already exist, and the environment variable MFALLOC_PCFILE is not set to N, allocate the associated physical file. |
| DLET | Delete. Remove a record from the catalog based on the DSN named in the interface area and delete the associated physical file. |
| GCFE | Get Catalog File Errors. Returns the first catalog file error that occurred. |
| GCFS | Get Catalog File Status. Returns the file status details of the first catalog file or the catalog number specified by ()-cat-file-number (see mfpubcat.cpy). |
| GETC | Get Cluster. When passed a VSAM Cluster element (for example, an Alternate Index, dataset name), this function returns the Cluster that the element belongs to. |
| GN | Get Next. Retrieve the next catalog record, based on the DSN index. If a current position has not already been established, the results are undefined. |
| GNFE | Get Next Catalog File Error. Gets the next catalog file error. GCFE retrieves all the catalog file errors that occurred during the previous listing, and returns the first one. Follow that call with GNFE calls to iterate over the list. |
| GNFS | Get Next File Status. Gets the next catalog file status. GCFS retrieves all the catalog file status records, and returns the first one. Follow that call with GNFS calls to iterate over all the catalog file statuses. |
| GNPC | Get Next PCDSN. Retrieve the next catalog record, based on the PCDSN index. If a current position has not already been established, the results are undefined. |
| GP | Get Previous. If a current position has not already been established, the results are undefined. |
| GU | Get Unique. Retrieve the record associated with the DSN named in the interface area. |
| GUPC | Get Unique PCDSN. Retrieve the record associated with the PCDSN named in the interface data. |
| ISRT | Insert a new record into the catalog, using values provided in the interface area. If the associated physical file does not already exist, and the environment variable MFALLOC_PCFILE is not set to N, and the file location is the default allocated dataset location, allocate the associated physical file. |
| REN | Rename. Change the dataset name on an existing catalog record. |
| REPL | Replace. Update an existing catalog record using replacement values provided in the interface area. See Notes. |
| STN> | Start not greater than. Establish a position in the catalog determined by the value of the DSN field in the interface area. A record with this value need not exist. |
| STN< | Start not less than. Establish a position in the catalog determined by the value of the DSN field in the interface area. A record with this value need not exist. |
| STNE | Start Not Greater Than (as STN>) but switch Disable Additional Qualifiers on. This provides the same functionality as selecting Disable Additional Qualifiers on the ESMAC catalog listing page. |
| STNI | Start not greater than and ignore errors. Same as STN> but ignores catalog errors while listing records. At the end of the listing, use the GCFE call to retrieve any errors. |
If you are using wildcards to identify data sets on which to perform any of the above functions, and the data set name criteria is 44 characters or more, you should use the * wildcard as the first character of the criteria.
Changes to (including deletion of) a data set that is currently allocated to the job step are not permitted after the data set has been opened. If attempted, MVSCATPB will return a retcode of 78-RET-VALIDATE-ERROR (20) and a reason code of 78-dataset-in-use (19).
When updating the DSORG of a data set using the REPL function, a check now verifies that the change is appropriate. If it is not, a return code of 78-RET-VALIDATE-ERROR (20) and a reason code of 78-MISMATCHED-DSORG (50) is produced.