Catalog Management API

This appendix describes how to manage catalog items and data sets using the Catalog Management API.

1. Overview

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

    amsu_initialize()

    Executes initialization for catalog management.

    amsu_finalize()

    Executes tasks necessary for finishing catalog management.

  • Volume Information

    API Description

    amsu_volume_list()

    Retrieves the list of volumes registered in the system.

    amsu_default_volume()

    Retrieves the default volume registered in the system.

    amsu_volume_path()

    Retrieves the directory path for a specific volume.

  • Catalog Search

    API Description

    amsu_use_catalogs()

    Specifies the catalog search order.

    amsu_search_entries()

    Searches for a specific entry in the catalog.

    amsu_master_catalog()

    Retrieves the master catalog information registered in the system.

    amsu_candidate_catalog()

    Searches the catalogs that are candidates for cataloging a specific data set.

  • File Path Resolution

    API Description

    amsu_filepath2()

    Retrieves the Unix file path for a specific data set name.

    amsu_filename2()

    Retrieves the filename for a specific data set name.

  • Entry Management

    API Description

    amsu_delete()

    Deletes the data set registered in the catalog.

    amsu_info()

    Reads the catalog information registered in the catalog.

    amsu_assoc()

    Retrieves the list of entries associated with the specified cataloged entry.

2. Initialization & Finalization

2.1. amsu_initialize()

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.

2.2. amsu_finalize()

Terminates catalog management by deleting the related resources from memory.

  • Prototype

    int amsu_finalize();

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

3. Volume Information

3.1. amsu_volume_list()

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.

3.2. amsu_default_volume()

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.

3.3. amsu_volume_path()

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.

4. Catalog Search

4.1. amsu_use_catalogs()

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.

4.2. amsu_search_entries()

Searches for a specific entry in a catalog. Catalogs are prioritized as follows:

  1. Catalog specified by amsu_use_catalogs()

  2. Alias catalog specified by filter_key

  3. 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;

4.3. amsu_master_catalog()

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.

4.4. amsu_candidate_catalog()

Searches the candidate catalog for a specific data set.

Candidate catalogs are determined through the following steps:

  1. GDG catalog if a data set name is GDS

  2. Catalog specified by amsu_use_catalogs()

  3. Alias catalog defined with the data set name

  4. 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.

5. File Path Resolution

5.1. amsu_filepath2()

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.

5.2. amsu_filename2()

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.

6. Entry Management

6.1. amsu_delete()

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.

6.2. amsu_info()

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.

6.3. amsu_assoc()

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;