NAME

intro_libsam, intro_libsamrpc - Introduces the StorageTek QFS and and Oracle HSM Application Programmer Interface (API) routines

AVAILABILITY

SUNWqfs

SUNWsamfs

DESCRIPTION

The StorageTek QFS and Oracle HSM API allows a StorageTek QFS or Oracle HSM file to be requested from within an application program. The aplication program can reside either on the machine upon which the StorageTek QFS or Oracle HSM file system is running or on another machine on the network. This man page provides an introduction to the API routines.

The following topics are presented:

• API overview

• API library routines

• Using libsam

• Using libsamrpc

API OVERVIEW

When a request is made, the process or program making the request is the client process or program, running on the client machine. The requests are received and processed by the server, running on the server, or host, machine. For the API routines, the server machine is always the machine upon which the StorageTek QFS or Oracle HSM file system is running.

In the simplest case, the client and server machines are the same, and no network communication is necessary. In other cases, however, the application programmer needs to allow for the client program to run on a machine where the StorageTek QFS or Oracle HSM file system is not running. In this case, networked library calls from libsamrpc must be used.

The two API libraries available with the StorageTek QFS and Oracle HSM file systems are as follows:

• libsam. The library calls in libsam do not perform network communication. They only make local requests. In this case, each library call makes a system call, and the server is the local operating system. Functionality provided by this library is limited on Linux system; see below.

• libsamrpc. The library calls in libsamrpc use Remote Procedure Calls (RPCs) to communicate with a special server process, sam-rpcd. Because of the RPC mechanism, the client and server can exist on the same machine or on different machines in the network. The server process always runs on the machine upon which the StorageTek QFS or Oracle HSM file system is running.

Both libsam and libsamrpc are released in shared object (.so) and archive (.a) format on both the Solaris and Linux platforms. libsam.so, libsam.a, libsamrpc.so and libsamrpc.a are installed in ∕opt∕SUNWsamfs∕lib.

API LIBRARY ROUTINES

The library calls for the StorageTek QFS and Oracle HSM software are supported in libsam, and a subset is supported in libsamrpc. On Linux systems these calls are available only through the libsamrpc library. The API libraries provide the routines listed below:

sam_advise

Sets file attributes.

Availability: StorageTek QFS and Oracle HSM environments.

Libraries: libsam.

sam_archive

Sets archive attributes on a file.

Availability: Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_rearchive

Sets rearchive attributes on a file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_exarchive

Exchanges archive copies of a file or directory.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_unarchive

Removes archive copies for a file or directory.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_unrearch

Removes rearchive attributes on a file or directory.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_damage

Sets damaged attribute on a file or directory.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_undamage

Clears damaged and stale status of a file or directory.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_cancelstage

Cancels a pending or in-progress stage on a file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_closecat

Ends access to the catalog for an automated library.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_closerpc

Closes down the RPC connection.

Availability: Oracle HSM environments.

Libraries: libsamrpc.

sam_devstat, sam_ndevstat

Gets device status. sam_ndevstat accepts a longer device name.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_devstr

Translates numeric device status into a character string.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_getcatalog

Obtains a range of entries from the catalog for an automated library.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_initrpc

Initializes the RPC connection.

Availability: Oracle HSM environments.

Libraries: libsamrpc.

sam_initrpc_timeout

Initializes the RPC connection setting the remote call timeout value.

Availability: Oracle HSM environments.

Libraries: libsamrpc.

sam_opencat

Accesses the VSN catalog for an automated library.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_readrminfo

Gets information for a removable media file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_release

Releases and sets release attributes on a file.

Availability: Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_request

Creates a removable media file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_restore_copy

Creates an archive copy for a file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_restore_file

Creates an offline file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_segment

Sets segment attributes on a file or directory.

Availability: Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_segment_stat

Obtains file information and follows symbolic links to a segmented file.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_setfa

Sets file attributes.

Availability: StorageTek QFS and Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_ssum

Sets checksum attributes on a file.

Availability: Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_stage

Stages and sets stage attributes on a file.

Availability: Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_stat, sam_lstat

sam_stat obtains file information and follows symbolic links to the file. sam_lstat obtains file information, and if that file is a link, it returns information about the link.

Availability: StorageTek QFS and Oracle HSM environments.

Libraries: libsam and libsamrpc.

sam_settimeout

Sets the RPC call timeout value.

Availability: Oracle HSM environments.

Libraries: libsamrpc.

sam_vsn_stat, sam_segment_vsn_stat

Obtain VSN status for a file or a file's data segment that overflows VSNs.

Availability: Oracle HSM environments.

Libraries: libsam.

sam_media_api

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

Availability: Oracle HSM environments.

Libraries: libsam.

All APIs in libsam, except for sam_closecat, sam_getcatalog, sam_opencat, and sam_media_api are available for use with 64-bit programs. Oracle does not support a 64-bit version of libsamrpc.

For more details about each library routine, see the individual corresponding man page for that routine. Library routines contained in libsam are found in section 3 of the online man pages. Library routines contained in libsamrpc are found in section 3X of the online man pages.

USING libsam

No special initialization or configuration is required prior to using the API library routines in libsam. The application program must be linked with libsam, however. For information on the routines, see the individual libsam man pages, all of which are listed in the SEE ALSO section of this man page.

USING libsamrpc

The source code for libsamrpc is included in the Solaris distribution for customers who wish to write and run application programs on platforms that do not run the Solaris or Linux operating systems. In these cases, the library must be ported to the client machine. The source code is located in ∕opt∕SUNWsamfs∕client∕src. Example application programs are located in ∕opt∕SUNWsamfs∕client∕examples.

Specifying the Server Machine

A call to sam_initrpc is required before any other RPC client API calls can be executed successfully. Only one sam_initrpc call is required, followed by any number of other client API calls (other than sam_closerpc). The sam_initrpc call accepts one argument: a pointer to a character string that specifies the name of the server machine. If this pointer is NULL, sam_initrpc checks for an environment variable named SAMHOST. If this environment variable is set, that name is used for the server machine. If there is no SAMHOST environment variable, the default server name samhost is used.

In summary, the name of the server machine can be specified in any of three ways, which are checked by sam_initrpc in the following order:

1. As an argument to the sam_initrpc call.

2. As the environment variable SAMHOST.

3. By accepting the default server name, samhost.

Understanding the RPC Server Process

The RPC API server process receives and processes requests from the client. This server process, ∕opt∕SUNWsamfs∕sbin∕sam-rpcd, must be run on the same machine as the file system. The sam-rpcd daemon must be running for client requests to execute successfully.

The sam-rpcd daemon is started automatically by sam-amld if the appropriate entry is made in the defaults.conf file. For information on editing the defaults.conf file, see Configuring the API later in this man page.

The sam-rpcd daemon can also be started manually. It should be run as superuser. The sam-rpcd command accepts no arguments.

The sam-rpcd daemon services the requests it receives by making the appropriate system call on the server machine and then returning the output or result to the client. For more information on this daemon, see the sam-rpcd (1m) man page.

Configuring the API Server and Clients

Once your software is properly configured and running, set up the API server and clients. In the location specified by the ∕etc∕nsswitch.conf file, enter the RPC program name samfs and an RPC program number chosen by you. The name and number pair must be the same on the server and all clients (for more information, see the nsswitch.conf (4) man page). In the example, we enter the RPC program name samfs and the RPC program number in the ∕etc∕rpc file (or the NIS database):

samfs		150005

The API server is started automatically by the sam-amld daemon if the following entry is made in the defaults.conf file (note that changes to the defaults.conf file do not take effect until the next time the sam-amld daemon is initialized):

samrpc = on

The sam-rpcd daemon is not automatically started if no entry for it appears in the defaults.conf file or if the following entry appears in the file:

samrpc = off

For more information about the defaults.conf file, see the defaults.conf (4) man page.

If the name of the server machine is not specified, the default host name samhost must be listed as an alias for the Oracle HSM file system server machine. For more information, see the sam_initrpc (3x) man page.

Authentication and libsamrpc

Authentication information is generated at the time of the sam-initrpc call. This information consists of the user identification (uid) and group identification (gid) of the calling process. It is associated with the connection made to the RPC server process.

Subsequent libsamrpc calls have this information associated. When the request is received by the RPC server process on the server machine, the uid and gid information is used. File access and operations are granted or denied based on this information.

It is important that the server machine have a common uid and gid space with the client machines.

SEE ALSO

sam_advise (3), sam_archive (3x), sam_rearch (3), sam_exarchive (3), sam_unarchive (3), sam_unrearch (3), sam_damage (3), sam_undamage (3), sam_cancelstage (3), sam_closecat (3), sam_devstat (3), sam_devstr (3), sam_getcatalog (3), sam_lstat (3x), sam_ndevstat (3), sam_opencat (3), sam_readrminfo (3), sam_release (3x), sam_request (3), sam_restore_copy (3), sam_restore_file (3), sam_segment (3x), sam_setfa (3x), sam_ssum (3x), sam_stage (3x), sam_stat (3x), sam_media_api (3).

sam_archive (3x), sam_closerpc (3x), sam_initrpc (3x), sam_lstat (3x), sam_release (3x), sam_stage (3x), sam_stat (3x).