Table of Contents
This appendix describes how to manage catalog items and data sets using the Catalog Management API.
Catalogs and data sets can be managed by using the OpenFrame Catalog Management API.
To write a program using the Catalog Management API, you must include the ams_user.h header file that is distributed with the OpenFrame binary and link the libams.so library when compiling the program.
The Catalog Management API can be categorized as follows:
Initialization & Finalization
| API | Description |
|---|---|
Executes initialization for catalog management. | |
Executes tasks necessary for finishing catalog management. |
Volume Information
| API | Description |
|---|---|
Retrieves the list of volumes registered in the system. | |
Retrieves the default volume registered in the system. | |
Retrieves the directory path for a specific volume. |
Catalog Search
| API | Description |
|---|---|
Specifies the catalog search order. | |
Searches for a specific entry in the catalog. | |
Retrieves the master catalog information registered in the system. | |
Searches the catalogs that are candidates for cataloging a specific data set. |
File Path Resolution
| API | Description |
|---|---|
Retrieves the Unix file path for a specific data set name. | |
Retrieves the filename for a specific data set name. |
Entry Management
| API | Description |
|---|---|
Deletes the data set registered in the catalog. | |
Reads the catalog information registered in the catalog. | |
Retrieves the list of entries associated with the specified cataloged entry. |
Performs initialization for catalog management by loading necessary resources into memory. If another Catalog Management API is used without calling this function, an error occurs.
Prototype
int amsu_initialize();
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Retrieves the list of volumes registered in the system.
Prototype
int amsu_volume_list(int *count, char *volser[]);
Parameters
| Parameter | Description |
|---|---|
count (OUT) | Size of the buffer given to volser (IN) and the number of registered volumes. |
volser (OUT) | Buffer to store the registered volume serials. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Retrieves the default volume registered in the system.
Prototype
int amsu_default_volume(char *volser);
Parameter
| Parameter | Description |
|---|---|
volser (OUT) | Buffer used to store the default volume serial. |
Return Value
If executed successfully, 0 is returned. If an error occurs, a negative error code is returned.
Retrieves the directory path of a specific volume.
Prototype
int amsu_volume_path(char *volser, char *vpath);
Parameters
| Parameter | Description |
|---|---|
volser (IN) | Volume serial for which the directory path is needed. |
vpath (OUT) | Buffer to store the directory path. |
Return Value
If executed successfully, 0 is returned. If an error occurred, a negative error code is returned.
Specifies the catalog search order.
Prototype
int amsu_use_catalogs(char **cat_names); int amsu_use_catalog(char *cat_name);
Parameters
| Parameter | Description |
|---|---|
cat_names (IN) | List of catalog names that is to be searched first during the catalog search. |
cat_name (IN) | Name of the catalog that is to be searched first during the catalog search. |
Return Value
If executed successfully, 0 is returned. If an error occurs, a negative error code is returned.
Searches for a specific entry in a catalog. Catalogs are prioritized as follows:
Catalog specified by amsu_use_catalogs()
Alias catalog specified by filter_key
Master catalog if the previous searches return no result
Prototype
int amsu_search_entries(char *filter_key, char *entry_types, int *count,
amsu_result_t *result, int flags);
Parameters
| Parameter | Description |
|---|---|
filter_key | Catalog entry expression to search for. (IN: including wild card characters, such as '*', '%') |
entry_types (IN) | Catalog entry type to search for. (NULL means all) |
count (OUT) | Result buffer size (IN), search result entry count. |
result (OUT) | Buffer to store the search result. |
flags (IN) | Catalog search option. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Note
The following are catalog entry types and search option macros. Refer to the macros defined in the ams_user.h header file for catalog entry types and catalog search options.
| Macro | Entry type | Description |
|---|---|---|
AMSU_ENTRY_TYPE_NONVSAM | 'A' | Non-VSAM |
AMSU_ENTRY_TYPE_GDG | 'B' | Generation data group |
AMSU_ENTRY_TYPE_CLUSTER | 'C' | VSAM cluster |
AMSU_ENTRY_TYPE_DATA | 'D' | Data component |
AMSU_ENTRY_TYPE_AIX | 'G' | Alternate index |
AMSU_ENTRY_TYPE_GDS | 'H' | Generation data set |
AMSU_ENTRY_TYPE_INDEX | 'I' | Index component |
AMSU_ENTRY_TYPE_PATH | 'R' | Access path |
AMSU_ENTRY_TYPE_UCAT | 'U' | User catalog |
AMSU_ENTRY_TYPE_ALIAS | 'X' | Alias |
Catalog Search Option Macros:
| Macro | Search option | Description |
|---|---|---|
AMSU_SEARCH_DEFAULT | 0x00 | Searches for the default value |
AMSU_SEARCH_CLS_COMPS | 0x01 | Returns the component if the cluster name matches the filter key |
AMSU_SEARCH_1_CATALOG | 0x02 | Searches only a single catalog |
A catalog search result is stored in the following structure:
/* -------------------------- catalog search result -------------------- */
typedef struct _amsu_result_t {
char catname[AMSU_ENTRY_NAME_LENGTH+1];
char entname[AMSU_ENTRY_NAME_LENGTH+1];
char enttype;
} amsu_result_t;
Retrieves master catalog information registered in the system.
Prototype
int amsu_master_catalog(char *mascat_name, char *mascat_vser);
Parameters
| Parameter | Description |
|---|---|
mascat_name (OUT) | Buffer to store the master catalog data set name. |
mascat_vser (OUT) | Buffer to store the master catalog volume serial. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Searches the candidate catalog for a specific data set.
Candidate catalogs are determined through the following steps:
GDG catalog if a data set name is GDS
Catalog specified by amsu_use_catalogs()
Alias catalog defined with the data set name
Master catalog if none of the previous conditions are met.
Prototype
int amsu_candidate_catalog(char *dsname, char *cat_name);
Parameters
| Parameter | Description |
|---|---|
dsname (IN) | Name of the data set to be cataloged. |
cat_name (OUT) | Buffer to store the name of the candidate catalog. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Retrieves the file path with a specific data set name.
Prototype
int amsu_filepath(char *dsname, char *volser, char *filepath); int amsu_filepath2(char *dsname, char *membname, char *volser, char *filepath);
Parameters
| Parameter | Description |
|---|---|
dsname (IN) | Name of the data set to find the file path. |
membname (IN) | PDS member to find the file path. |
volser (IN) | Volume serial where the specified data set is stored. |
filepath (OUT) | Buffer to store Unix file path. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Retrieves file name of the specified data set name.
Prototype
int amsu_filename(char *dsname, char *filename); int amsu_filename2(char *dsname, char *membname, char *filename);
Parameters
| Parameter | Description |
|---|---|
dsname (IN) | Name of the data set to find the file path. |
membname (IN) | PDS member to find the file path. |
filename (OUT) | Buffer to store Unix file path. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Deletes entries registered in a catalog.
Prototype
int amsu_delete(char *cat_name, char *entry_name, char entry_type, int flags);
Parameters
| Parameter | Description |
|---|---|
cat_name (IN) | Name of the catalog where the entry is cataloged. |
entry_name (IN) | Name of the cataloged entry. |
entry_type (IN) | Type of cataloged entry. |
flags (IN) | Option for catalog deletion. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Reads the information of the entry registered in a catalog.
Prototype
int amsu_info(char *cat_name, char *entry_name, char entry_type, void
*entry_info, int flags);
Parameters
| Parameter | Description |
|---|---|
cat_name (IN) | Name of the catalog where the entry is cataloged. |
entry_name (IN) | Name of the cataloged entry. |
entry_type (IN) | Type of cataloged entry. |
flags (IN) | Catalog query option. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Note
Depending on the catalog type, information about the catalog entry is stored in different structures. The data structure for the GDG entry is as follows:
/* -------------------------- GDG info type ---------------------------- */
typedef struct _amsu_gdg_info_t {
char dscrdt2[8]; /* creation date */
char dsexdt2[8]; /* expiration date */
char ownerid[8]; /* owner of the data set */
int16_t gdglimit; /* maximum number of GDS allowed */
uint8_t gdgattr; /* GDG attributes - bit flags */
} amsu_gdg_info_t;
For entries other than GDG, refer to the structures defined in the ams_user.h header file.
Retrieves the list of entries associated with the specified cataloged entry.
Prototype
int amsu_assoc(char *cat_name, char *entry_name, char entry_type, int
*count, amsu_symbol_t *assocs);
Parameters
| Parameter | Description |
|---|---|
cat_name (IN) | Name of the catalog the entry is cataloged in. |
entry_name (IN) | Name of the cataloged entry. |
entry_type (IN) | Type of the cataloged entry. |
count (OUT) | Associated buffer size (IN) and associated entry count. |
assoc (OUT) | Associated entry buffer. |
Return Value
If successful, 0 is returned. If an error occurs, a negative error code is returned.
Note
Associated entry list is stored in a structure as follows:
/* -------------------------- catalog entry symbol --------------------- */
typedef struct _amsu_symbol_t {
char entname[AMSU_ENTRY_NAME_LENGTH+1];
char enttype;
} amsu_symbol_t;