카탈로그 관리 API

본 부록에서는 카탈로그 관리 API의 인터페이스를 사용하여 카탈로그 항목과 데이터셋을 관리하는 방법에 대해서 기술한다.

1. 개요

OpenFrame에서 제공하는 카탈로그 관리 API의 인터페이스를 사용하여 카탈로그 항목 삭제와 조회 등 카탈로그와 데이터셋에 대한 관리를 할 수 있다.

카탈로그 관리 API를 사용해서 프로그램을 작성하려면 OpenFrame 바이너리와 함께 배포되는 amsu.h 헤더 파일을 사용자 프로그램에 포함해야 하고, 사용자 프로그램을 컴파일할 때 libams.so 라이브러리를 링크해야 한다.

카탈로그 관리 API의 인터페이스는 다음과 같이 분류할 수 있다.

  • Initialization & Finalization

    API 설명

    amsu_initialize()

    카탈로그 관리를 위한 초기화를 수행한다.

    amsu_finalize()

    카탈로그 관리 종료를 위한 일을 수행한다.

  • Volume Information

    API 설명

    amsu_volume_list()

    시스템에 등록된 볼륨의 목록을 가져온다.

    amsu_default_volume()

    시스템에 등록된 기본 볼륨을 가져온다.

    amsu_volume_path()

    특정 볼륨에 대한 디렉터리 경로를 가져온다.

  • Catalog Search

    API 설명

    amsu_use_catalogs()

    임의의 카탈로그 검색순서를 지정한다.

    amsu_search_entries()

    카탈로그에서 특정 항목을 검색한다.

    amsu_master_catalog()

    시스템에 등록된 마스터 카탈로그 정보를 가져온다.

    amsu_candidate_catalog()

    특정 데이터셋을 카탈로깅하기 위한 후보 카탈로그를 검색한다.

  • File Path Resolution

    API 설명

    amsu_filepath2()

    특정 데이터셋의 이름에 대해 UNIX 파일경로를 가져온다.

    amsu_filename2()

    특정 데이터셋의 이름에 대해 파일이름을 가져온다.

  • Entry Management

    API 설명

    amsu_delete()

    카탈로그에 등록된 데이터셋을 삭제한다.

    amsu_info()

    카탈로그에 등록된 항목 정보를 읽어온다.

    amsu_assoc()

    카탈로그에 등록된 항목과 연관된 목록을 가져온다.

2. Initialization & Finalization

2.1. amsu_initialize()

카탈로그 관리를 위한 초기화를 수행한다. 카탈로그 관리를 위해 필요한 자원을 메모리에 적재한다. 이 함수를 호출하지 않고 다른 카탈로그 관리 API를 사용할 때 에러가 발생하므로 반드시 초기화하도록 한다.

  • 프로토타입

    int amsu_initialize();

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

2.2. amsu_finalize()

카탈로그 관리를 종료할 때 호출한다. 카탈로그 관리를 위해 메모리에 적재한 자원을 삭제한다.

  • 프로토타입

    int amsu_finalize();

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

3. Volume Information

3.1. amsu_volume_list()

시스템에 등록된 볼륨의 목록을 가져온다.

  • 프로토타입

    int amsu_volume_list(int *count, char *volser[]);

  • 파라미터

    파라미터 설명

    count (출력)

    volser로 주어진 버퍼의 크기(입력), 등록된 볼륨의 개수이다.

    volser (출력)

    등록된 볼륨 시리얼을 담기 위한 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

3.2. amsu_default_volume()

시스템에 등록된 기본 볼륨을 가져온다.

  • 프로토타입

    int amsu_default_volume(char *volser);

  • 파라미터

    파라미터 설명

    volser (출력)

    기본 볼륨 시리얼을 담기 위한 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

3.3. amsu_volume_path()

특정 볼륨에 대한 디렉터리 경로를 가져온다.

  • 프로토타입

    int amsu_volume_path(char *volser, char *vpath);

  • 파라미터

    파라미터 설명

    volser (입력)

    디렉터리 경로를 알고 싶은 볼륨 시리얼이다.

    vpath (출력)

    디렉터리 경로를 담기 위한 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

4. Catalog Search

4.1. amsu_use_catalogs()

임의의 카탈로그 검색순서를 지정한다.

  • 프로토타입

    int amsu_use_catalogs(char **cat_names);
int amsu_use_catalog(char *cat_name);

  • 파라미터

    파라미터 설명

    cat_names (입력)

    카탈로그를 검색할 때 우선적으로 검색할 카탈로그 이름 리스트이다.

    cat_name (입력)

    카탈로그를 검색할 때 우선적으로 검색할 카탈로그 이름이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

4.2. amsu_search_entries()

카탈로그에서 특정 항목을 검색한다. 카탈로그 검색순서는 아래와 같다.

  1. amsu_use_catalogs()에 의해 지정된 카탈로그

  2. filter_key에 의해 지정된 Alias 카탈로그

  3. 앞에서 검색이 되지 않았을 경우 마스터 카탈로그

    • 프로토타입

      int amsu_search_entries(char *filter_key, char *entry_types, int *count,
                        amsu_result_t *result, int flags);

    • 파라미터

      파라미터 설명

      filter_key

      검색할 카탈로그 항목 표현식이다.

      (IN : '*', '%' 등의 와일드 카드 문자 포함)

      entry_types (입력)

      검색할 카탈로그 항목 유형이다. (NULL이면 모두 검색)

      count (출력)

      result 버퍼의 크기(입력), 검색된 항목 개수이다.

      result (출력)

      검색된 항목을 담을 버퍼이다.

      flags (입력)

      카탈로그 검색 옵션이다.

    • 반환값

      정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

    • 참고

      다음은 카탈로그 항목 유형과 카탈로그 검색 옵션 매크로이다. 카탈로그 항목 유형과 카탈로그 검색 옵션은 ams_user.h 헤더 파일에 정의된 매크로를 참고한다.

      매크로 항목 유형 설명

      AMSU_ENTRY_TYPE_NONVSAM

      'A'

      Non-VSAM이다.

      AMSU_ENTRY_TYPE_GDG

      'B'

      세대 데이터 그룹이다.

      AMSU_ENTRY_TYPE_CLUSTER

      'C'

      VSAM 클러스터이다.

      AMSU_ENTRY_TYPE_DATA

      'D'

      데이터 컴포넌트이다.

      AMSU_ENTRY_TYPE_AIX

      'G'

      보조 인덱스이다.

      AMSU_ENTRY_TYPE_GDS

      'H'

      세대 데이터셋이다.

      AMSU_ENTRY_TYPE_INDEX

      'I'

      인덱스 컴포넌트이다.

      AMSU_ENTRY_TYPE_PATH

      'R'

      접근경로이다.

      AMSU_ENTRY_TYPE_UCAT

      'U'

      사용자 카탈로그이다.

      AMSU_ENTRY_TYPE_ALIAS

      'X'

      Alias이다.

      다음은 카탈로그 검색 옵션 매크로이다.

      매크로 검색 옵션 설명

      AMSU_SEARCH_DEFAULT

      0x00

      기본 검색 옵션이다.

      AMSU_SEARCH_CLS_COMPS

      0x01

      클러스터 이름이 filter key와 일치하면 컴포넌트가 반환된다.

      AMSU_SEARCH_1_CATALOG

      0x02

      단 하나의 카탈로그만 검색된다.

      카탈로그를 검색해서 나온 결과는 다음과 같은 구조체에 담기게 된다.

      /* -------------------------- 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()

시스템에 등록된 마스터 카탈로그 정보를 가져온다.

  • 프로토타입

    int amsu_master_catalog(char *mascat_name, char *mascat_vser);

  • 파라미터

    파라미터 설명

    mascat_name (출력)

    마스터 카탈로그 데이터셋 이름을 담을 버퍼이다.

    mascat_vser (출력)

    마스터 카탈로그 볼륨 시리얼을 담을 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

4.4. amsu_candidate_catalog()

특정 데이터셋에 대한 후보 카탈로그를 검색한다.

후보 카탈로그는 다음의 절차에 의해서 결정된다.

  1. 데이터셋 이름이 GDS인 경우 GDG 카탈로그

  2. amsu_use_catalogs()로 지정된 카탈로그

  3. 데이터셋 이름에 의해서 지정된 Alias 카탈로그

  4. 앞에서 결정이 되지 않았을 경우 마스터 카탈로그

    • 프로토타입

      int amsu_candidate_catalog(char *dsname, char *cat_name);

    • 파라미터

      파라미터 설명

      dsname (입력)

      카탈로깅될 데이터셋 이름이다.

      cat_name (출력)

      후보 카탈로그 이름을 담을 버퍼이다.

    • 반환값

      정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

5. File Path Resolution

5.1. amsu_filepath2()

특정 데이터셋의 이름에 대해 파일 경로를 가져온다.

  • 프로토타입

    int amsu_filepath(char *dsname, char *volser, char *filepath);
int amsu_filepath2(char *dsname, char *membname, char *volser, char *filepath);

  • 파라미터

    파라미터 설명

    dsname (입력)

    파일 경로를 조회하고자 하는 데이터셋 이름이다.

    membname (입력)

    파일 경로를 조회하고자 하는 PDS의 멤버이다.

    volser (입력)

    지정된 데이터셋이 저장된 볼륨 시리얼이다.

    filepath (출력)

    UNIX 파일 경로를 담을 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

5.2. amsu_filename2()

특정 데이터셋의 이름에 대해 파일 이름을 가져온다.

  • 프로토타입

    int amsu_filename(char *dsname, char *filename);
int amsu_filename2(char *dsname, char *membname, char *filename);

  • 파라미터

    파라미터 설명

    dsname (입력)

    파일 경로를 조회하고자 하는 데이터셋 이름이다.

    membname (입력)

    파일 경로를 조회하고자 하는 PDS의 멤버이다.

    filename (출력)

    UNIX 파일 이름을 담을 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

6. Entry Management

6.1. amsu_delete()

카탈로그에 등록된 항목을 삭제한다.

  • 프로토타입

    int amsu_delete(char *cat_name, char *entry_name, char entry_type, int flags);

  • 파라미터

    파라미터 설명

    cat_name (입력)

    해당 항목이 카탈로깅된 카탈로그 이름이다.

    entry_name (입력)

    해당 항목의 카탈로깅된 이름이다.

    entry_type (입력)

    해당 항목이 카탈로깅된 유형이다.

    flags (입력)

    카탈로그 삭제 옵션이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

6.2. amsu_info()

카탈로그에 등록된 항목에 대한 정보를 읽어온다.

  • 프로토타입

    int amsu_info(char *cat_name, char *entry_name, char entry_type, void
              *entry_info, int flags);

  • 파라미터

    파라미터 설명

    cat_name (입력)

    해당 항목이 카탈로깅된 카탈로그 이름이다.

    entry_name (입력)

    해당 항목의 카탈로깅된 이름이다.

    entry_type (입력)

    해당 항목이 카탈로깅된 유형이다.

    flags (입력)

    카탈로그 삭제 옵션이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

  • 참고

    카탈로그 항목에 대한 정보는 항목의 유형에 따라 서로 다른 구조체에 담기게 된다. 아래는 GDG 항목에 대한 정보 구조체를 보여준다.

    /* -------------------------- 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;

    GDG 이외의 항목에 대해서는 ams_user.h 헤더 파일에 정의된 구조체를 참고한다.

6.3. amsu_assoc()

카탈로그에 등록된 항목과 연관된 항목 목록을 가져온다.

  • 프로토타입

    int amsu_assoc(char *cat_name, char *entry_name, char entry_type, int
               *count, amsu_symbol_t *assocs);

  • 파라미터

    파라미터 설명

    cat_name (입력)

    해당 항목이 카탈로깅된 카탈로그 이름이다.

    entry_name (입력)

    해당 항목의 카탈로깅된 이름이다.

    entry_type (입력)

    해당 항목이 카탈로깅된 유형이다.

    count (출력)

    연관된 항목 버퍼 크기(입력), 연관된 항목 개수이다.

    assoc (출력)

    연관된 항목 버퍼이다.

  • 반환값

    정상적으로 실행된 경우 0을 반환하고 에러가 발생한 경우 음수의 에러 코드를 반환한다.

  • 참고

    연관된 항목 목록은 다음과 같은 구조체에 담기게 된다.

    /* -------------------------- catalog entry symbol --------------------- */

typedef struct _amsu_symbol_t {
    char        entname[AMSU_ENTRY_NAME_LENGTH+1];
    char        enttype;
} amsu_symbol_t;