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 current DSN. 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. |
| GUA[16] | Get Unique Alias. If actual ALIAS information is required, use the GUA instead of the GU function to prevent the ALIAS from
being resolved to the related dataset. When using the GU function and an ALIAS name is used, the alias is resolved to the
related dataset.
The GN function always returns an ALIAS if that is the next dataset to be returned. So, when producing a listing of datasets by doing STN> and GN, an ALIAS may be returned. An ALIAS is indicated by the value 'Y' or 'S' in the ()-RECORD-IS-ALIAS field. |
| 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. |
| RESA[16] | Resolve alias. Resolve an alias to the related dataset. By passing in the alias dataset name it is resolved to the related
dataset. If it is a symbolic relation the symbols are resolved if possible.
The LK-RELATED-DATASET-NAME and LK-RELATED-DATASET-MEMBER fields contain the first related dataset for the returned dataset. If the returned dataset has an alias, the first one is listed in these fields. If the returned dataset is an ALIAS, then the dataset it relates to is returned in these fields. A dataset may have more than one alias, but only the first is returned in these fields. For a full listing use the IDCAMS LISTCAT (DSNAME) ALL command. |
| 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 in the first field of the MEMBER name.
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.