NAME

sam_media_api - SAM Media API for file systems, media catalogs, devices, file defects, and on demand media validation.

AVAILABILITY

SUNWsamfs

SYNOPSIS

cc -mt [ flag… ] -I ∕opt∕SUNWsamfs∕include file… [ library… ] -R ∕opt∕SUNWsamfs∕lib -L ∕opt∕SUNWsamfs∕lib -lsamut -lsamcat -lsam -ldb

#include "∕opt∕SUNWsamfs∕include∕media.h"

int sam_get_fs_count(int *count);

int sam_get_fs_list(struct fs_list *list);

int sam_get_fs_info(struct fs_info *info, char *fsname);

int sam_get_cart_count(int *count);

int sam_get_cart_list(struct cart_list *list, int index, int count);

int sam_getall_cart_list(struct cart_list *list);

int sam_get_cart_info(struct cart_info *info, vsn_t vsn);

int sam_get_device_count(int *count);

int sam_getall_device_list(struct device_list *list);

int sam_get_device_info(struct device_info *info, equ_t eq);

int sam_getall_defects_count(int *count);

int sam_get_defects_count(int *count, vsn_t vsn);

int sam_getall_defects_list(struct defects_list *list);

int sam_get_defects_info(struct defects_list *list, vsn_t vsn);

int sam_get_validation_count(int *count);

int sam_get_validation_queue(struct verify_queue *queue);

int sam_has_validation_sched(vsn_t vsn);

int sam_remove_sched_validation(vsn_t vsn);

int sam_sched_validation(vsn_t vsn);

DESCRIPTION

The SAM Media API is a thread safe C Programming Language API. The API provides routines to get information about Oracle HSM file systems, media catalogs, libraries and tape drives, file defects discovered by media validation, and on demand media validation.

The data structures used by this API are documented in the ∕opt∕SUNWsamfs∕include∕media.h header file. The API data structures that contain status and state fields use the same macros and defines that are found in the ∕opt∕SUNWsamfs∕include∕catalog.h and ∕opt∕SUNWsamfs∕include∕devstat.h header files.

This API is an evolving interface that can be removed or modified in a future release without notice. Users of this API should rebuild their applications for each new Oracle HSM release installed on their host.

This man page provides information about the SAM Media API functions.

SAM Media API routines:

Routine

Description

int sam_get_fs_count(int *count)

Get count of Oracle HSM MDS file systems.

int sam_get_fs_list(struct fs_list *list)

Get list of information about all Oracle HSM MDS file systems.

int sam_get_fs_info(struct fs_info *info, char *fsname)

Get information about a specific Oracle HSM file system.

int sam_get_cart_count(int *count)

Get count of cartridges in all library media catalogs.

int sam_get_cart_list(struct cart_list *list,

int index, int count)

Get range of library media catalog information. The index is an offset into all media catalogs and the count is the number of entries to retrieve.

int sam_getall_cart_list(struct cart_list *list)

Get list of information about all library media catalogs.

int sam_get_cart_info(struct cart_info *info, vsn_t vsn)

Get cartridge information about a specific vsn.

int sam_get_device_count(int *count)

Get count of all library and tape devices.

int sam_getall_device_list(struct device_list *list)

Get list of information about all library and tape devices.

int sam_get_device_info(struct device_info *info, equ_t eq)

Get information about a specific device.

int sam_getall_defects_count(int *count)

Get count of all file defects discovered during media validation.

int sam_get_defects_count(int *count, vsn_t vsn)

Get count of file defects discovered for a specific vsn during media validation.

int sam_getall_defects_list(struct defects_list *list)

Get list of all file defects discovered by media validation.

The file defects reported by the defects functions are verified using the sam_stat (3x) function before returned by this function.

If a file is rearchived or the tape is relabeled, the file defect will be deleted from the defects database and not included in this list.

The verifyd.cmd must be configured for action = log age time to log file defects found during the file system scan.

int sam_get_defects_info(struct defects_list *list, vsn_t vsn)

Get list of media validation file defects found for a specific vsn.

int sam_get_validation_count(int *count)

Get count of on scheduled demand media validations.

int sam_get_validation_queue(struct verify_queue *queue)

Get list of vsns scheduled for on demand media validation.

int sam_has_validation_sched(vsn_t vsn)

Determine if vsn is scheduled for on demand media validation.

int sam_remove_sched_validation(vsn_t vsn)

Remove vsn from on demand media validation, a running validation is canceled.

int sam_sched_validation(vsn_t vsn)

Schedule vsn for on demand media validation.

RETURNS

The SAM Media API functions return zero for success and non-zero for failure.

ERRORS

Below are errors returned by this API, other errors can be returned by the private Oracle HSM APIs which this API relies on.

EAGAIN: Oracle HSM is not running.
ENOENT: Not found, empty, does not exist.
ENOMEM: Out of memory, list too large.
EIO: On demand media validation directory scan failed.

EXAMPLES

An example source file for this API is ∕opt∕SUNWsamfs∕examples∕media.c