From SRB

Contents 1 SRB - The Storage Resource Broker (Version 3.4.0) 1.1 Major features of the SRB 1.2 The SRB Architecture 1.2.1 An Overview of the SRB architecture 1.2.2 Implementation details 1.2.2.1 The SRB process model 1.2.2.2 Federation of SRB servers 1.2.2.3 Federation of MCAT Zones 1.2.2.4 Master/Slave MCAT 1.2.2.5 The SRB agent design details 1.2.2.6 The SRB container design 2 The SRB client API 2.1 Overview 2.2 Description of API 3 Setting up Client Environment 3.1 Building and installing the SRB client library 3.2 Setting up the client user environment 3.3 Locations of the SRB client library and header files 4 Client Programming 4.1 Connecting and disconnecting to the SRB Server 4.2 Error handling 4.3 Client programming examples 4.4 srbObjOpen

SRB - The Storage Resource Broker (Version 3.4.0)

[README.first.htm Release Notes for Version 2.0.0]

Major features of the SRB

1) SRB server - The Storage Resource Broker (SRB) is a middleware that provides distributed clients with uniform access to diverse storage resources in a heterogeneous computing Environment. Storage systems handled by the current release of the SRB include the UNIX file system, archival storage systems such as UNITREE and HPSS, and database Large Objects managed by various DBMS including DB2, Oracle and Illustra.

2) Client library - Client applications are provided with a set of API for sending requests and receiving response to/from the SRB servers.

3) MCAT server - The meta data of the SRB system is managed by the MCAT server which is based on relational database technology. The MCAT server stores meta data associated with data sets, users and resources managed by the SRB. Detailed descriptions on the design of MCAT are given in http://www.npaci.edu/DICE/Software/SRB/mcat.html. Meta data includes information for access control, and data structures required for implementing "collection" (directory) abstraction. Since the MCAT is implemented with relational database technology, it can be extended beyond the capability of traditional file system, such as implementing a more complex access control system, proxy operations, and information discovery based on system level and application level meta data.

4) A logical view of data - The MCAT presents clients with a logical view of data sets stored in the SRB. Similar to the file name in the file system paradigm, each data set stored in SRB has a logical name, which may be used as a handle for data operation. Unlike the file system where the physical location of a file is implicitly implied in its path name through its mount point, the physical location of a data set in the SRB environment is logically mapped to the data sets. Therefore, the actual data of data sets belonging to the same collection may physically reside in different storage systems. A client does not need to remember the physical mapping of a data set. It is stored as the meta data associated with the data set.

5) The global logical name space – Similar to file system paradigm, data sets can be arranged in a directory-like structure, which we call collection. Collections provide a logical grouping mechanism where each collection may contain a group of physically distributed data sets and/or sub-collections.

6) Metadata support - Various types of metadata including Extensible Schema http://www.sdsc.edu/srb/matrix/wiki2/index.php/Extensible_Schema can be associated with data sets so that it can be used to query and locate data.

7) Data access performance enhencements - A number of performance enhencements were made to improve the data access performance:

i) Parallel I/O - designed to improve the performance of transferring large files by using multiple streams for the data transfer.

ii) Bulk transfer - designed to improve the performance of transferring a large number of small files Small files are concatenated into a large buffer first and this buffer is transferred in a single operation to reduce overhead.

iii) Third party transfer - designed to improve the performance of server to server transfer such as data replication which data transfer is carried out directly between the two servers without involving the client.

iv) Container implementation - designed to improve the performance of archiving a large number of small files. Due to the relative high latency of writing a large number of small files to tape, these small files are concatenated into a single container file before writing to tapes.

8) Strong access control support - Owner of a data set can grant access to individual users or groups of users.

9) A set of UNIX like utilities (e.g., ls, cp, chmod, etc) for manipulating and querying collections and datasets in the SRB space.

10) A Mass Storage System (MSS) implementation within SRB - The system can be configured to have a pool of disk cache resources in the frontend and a STK tape silo library in the backend. Data files stored in this system are automatically staged to the disk cache whenever accessed and migrate to the tape library when more free cache space is needed.

11) Support two authentication schemes - The SRB can now support two authentication schemes - GSI, SEA and encrypted password. GSI (Grid Security Infrastructure) is a security infrastructure based on X.509 certificates developed by the Globus group (http://www.npaci.edu/DICE/security/index.html).

12) Ticket - The Ticket abstraction has been implemented to facilitate the sharing of data among users. The Ticket implementation works as follows:

i) The owner of a data object or collection may grant read only access to a user or a group of users through issuance of tickets on the data object or collection.

ii) A ticket is a 10 character alphanumeric string and can be passed from the ticket issuer to the ticket users. A ticket user can then use this ticket to open and read data objects.

iii) A ticket can be issued to either MCAT registered or unregistered users. Unregistered users who wish to use a ticket to access a data object must use a special call to connect to the SRB sever. The normal user authentication will then be bypassed but the resulting connection has only limited privileges.

13) Logical resource implementation - the RESOURCE meta data has been modified to allow grouping of two or more physical resources into a resource group or logical resource. Logical resources can be used in more than one way. A logical resource can be used to group together a pool of disk cache and appears as one large disk cache, or it can be used to automatically replicate data in each of the physical resource belonging to the logical resource.

13) Data replication – The SRB supports data replication. The following gives some details of the implementation:

i) Automatic replication of new data - When creating a data set, a client can specify a logical resource rather than a physical resource as the resource input. With the COPIES=ALL flag set, a copy of the data will be created in each of the physical resource belonging to the logical resource.

ii) Replication of existing data - A user can use the Sreplicate command or the srbObjReplicate() API to replicate existing data to the specified resource.

14) Replica synchronization - Copies of replica can modified individually and replica of an object can be out of sync. Now, the most recently modified copy will be marked as "dirty". A new command - "Ssyncd" and API - srbSyncData() has been created to synchronize all copies (replica) of an SRB object with the dirty copy. A "%" character to the left of the file name of a "Sls -l" output indicates the given copy is "dirty".

15) Proxy operation - Some operations can be more efficiently done by the server without much involvement by the client. An example is the copy operation where it is more efficient for the server to do all the read and write operations on behalf of the client than passing the data read to the client and then for the client passing it back to the server for the write operation. A framework for handling proxy operations has been set up to facilitate the building of new proxy functions. These proxy functions can be in the form of either direct codes in the SRB server or individual executables which are accessible by users the the Spcommand utility or the srbExecCommand() API

16) Auditing - Auditing provides a facility to audit the usage of data sets.

17) A JAVA based SRB client GUI - The srbBrowser is a JAVA based SRB client GUI which can be used to perform a variety of client level operations including replication, copy and paste, registration of datasets and metadata manipulation and query, etc.

TOP

The SRB Architecture

An Overview of the SRB architecture

The Storage Resource Broker (SRB) is a middleware that provides distributed clients with uniform access to diverse storage resources in a heterogeneous computing Environment.

Figure 1 gives a simplified view of the SRB architecture. The model consists of three components: the meta data catalog (MCAT) service, SRB servers and SRB clients, connected to each other via network.

The MCAT stores meta data associated with data sets, users and resources managed by the SRB. The MCAT server handles requests from the SRB servers. These requests include information queries as well as instructions for meta data creation and update.

Client applications are provided with a set of API for sending requests and receiving response to/from the SRB servers. The SRB server is responsible for carrying out tasks to satisfy the client requests. These tasks include interacting with the MCAT service, and performing I/O on behalf of the clients. A client uses the same common API to access every storage systems managed by the SRB. The complex tasks of interacting with various types of storage system and OS/hardware architecture, are handled by the SRB server.

TOP '

Implementation details

'

The SRB process model

Figure 2 depicts the SRB process model. The design of the SRB server is based on the traditional network connected client/server model. It is composed of two separate servers, SRB Master and SRB Server. The SRB Master is the main daemon listening continuously on a well-known port for connection requests from clients. Once a connection from a client is established and authenticated, it forks and execs a copy of the SRB Server, which we call SRB agent, to service the connection. From that point onward, the client and the SRB agent communicate using a different port and the SRB Master goes back to listening for more connections. A client can use the same SRB agent to service multiple requests.

Client applications communicate with the SRB agent using a set of API via TCP/IP sockets. The client library sends requests using pre-defined request stubs to the SRB agent, and receives and parses replies from the SRB agent. The model is distributed in the sense that clients and servers may be running on different hosts.

TOP

Federation of SRB servers

A group of distributed SRB servers coordinating with each other to service client requests, can be configured to form a federation. The advantages of a federated SRB are as follows:

o For technical and policy reasons, various storage systems must run on different hosts.

o Improved performance.

o Improved data reliability and availability – Replica of data may be stored in different storage systems and on different hosts.

Figure 3 depicts the working of a federated SRB, which consists of two SRB masters, running on hosts A and B. The SRB server on A is MCAT enabled meaning that it can talk to the MCAT server. In this example, a client "open data set" request may result in the following steps:

1) After completing the connection sequence with the SRB master on host A, the client sends a request to the SRB agent on host A to open a data set for reading.

2) The SRB agent makes a MCAT call passing the client’s user ID and the data set name to the MCAT server to check if the client has the proper access permission to the data set. If it checks out, the MCAT call returns a data structure that contains the physical location where the data set is stored. The physical location data structure includes the host name, the storage system type (e.g., UNIX, HPSS, DB2 Large Object, etc) and the path name (e.g. a unix file path).

3) The SRB agent on host A realizes the requested data set is on host B and carries a remote open on behalf on the client passing along the storage system type and the path name to the SRB agent on host B.

4) The SRB agent on host B uses the storage system type to invoke the appropriate low level storage driver to invoke to handle the open call, passing along the path name to be opened. Upon completion of the open call, the SRB agent on host B returns the opened file descriptor or error code to the SRB agent on host A.

5) If the open call is successful, the SRB agent on host A stores the returned file descriptor and other information such as host name, etc in a internal data structure and pass back the pointer to this data structure to the client. The client can then use this pointer in subsequent read calls; if the open call is not successful, an error code is returned instead.

TOP

Federation of MCAT Zones

A zone is defined as a federation of SRB resources/servers controlled by a single MCAT. Each zone has full control of its administrative domain and can operate independently from other zones. A federation of MCAT zones allows the sharing of data and resources between zones in the federation. Users in one zone with proper permission, can access data and resources in another zone. Special attention was kept to make sure that security compromise in one zone will not significantly affect the security of another zone. http://www.sdsc.edu/srb/matrix/wiki2/index.php/Zones gives more detailed information on the zone design.

Master/Slave MCAT

A SRB federation (zone) can be configured to run with a single Master MCAT plus zero or more Slave MCATs.

The purpose of the Slave MCAT is to improve responsiveness across a Wide-Area-Network. SRB functions that read from the MCAT, and do not update, can then query the Slave MCAT, which can be local. The decisions on which SRB calls go to a Slave (if defined) or Master MCAT is done by some of the SRB code which "knows" which calls are read only. It is up to the administrator to configure Slave MCATs to be local. http://www.sdsc.edu/srb/matrix/wiki2/index.php/Master_Slave_MCAT gives more detailed information on the Master/Slave MCAT design.

TOP

The SRB agent design details

As described above, the SRB is designed based on the traditional client/server model. Client applications are provided with a set of simple API to communicate with the SRB servers. The main daemon, the SRB master, is responsible for the simple tasks of listening for incoming connections, and spawning a SRB agent to handle each connection once the client is authenticated. The SRB agents are responsible for receiving and servicing all subsequent client requests.

Figure 4 gives a simplified view of the SRB agent design.

At the top is the "dispatcher" module, which listens for incoming client requests and dispatches the requests to the proper request handlers. The "dispatcher" is also responsible for returning the results to clients.

Clients are provided with two sets of API, the high-level and low-level API. The high-level API handles data sets that use the MCAT server for meta data management, while the low-level API handles data sets that do not use the MCAT. When using the high-level API to create a data set, the data set is automatically registered in MCAT and the MCAT keeps all relevant information associated with the data set until the data set is deleted. On the other hand, data sets created using the low-level API are not registered in MCAT. When accessing a data set using the low-level API, a client needs to provide all required information such as the physical location (host address and full path name) and the storage system type of the data set. Detailed descriptions of the client API are given in [#Appendix A Appendix A].

The high-level request handler of the SRB agent handles all high-level client requests, and the low-level request handler handles low-level client requests.

Through the high-level API, a client can access the following type of services provided by the SRB agents:

1) Create and remove data sets.

2) Perform I/O operations on data sets.

3) Manipulate and query meta data associated with the data sets and collections.

4) Manipulate and query meta data associated with other objects such as users, user-groups and resources managed by the SRB.

All these operations require the high-level request handler to interact with the MCAT service to manipulate and query the meta data stored in MCAT. In addition, for requests that perform operations on data set (1) and 2)), low-level requests will be generated and dispatched to the low-level request handler for further processing.

A set of library calls is used by the high-level request handler to interact with the MCAT service. These calls allows the SRB agent to register, unregister and modify meta data associated with data sets, users and storage resources, and to query the meta data. Basically, these routines translate easy-to-understood input parameters into complex SQL queries and send them to the MCAT server. Upon receiving the query results from the MCAT server, these routines parse the query results into simple forms before returning them to the caller.

The type of MCAT call made by the SRB agent depends on the type of client call the SRB agent is trying to handle. For example, to handle a "create data set" call, a query is sent to the MCAT server on the requested storage resource. If the client is allowed to create data set in this storage resource, it returns the physical location (host name, directory path) and storage system type of the requested storage system to the caller. Using the returned directory path, a unique physical path name (e.g., UNIX or HPSS path name) is generated. A low-level "create" call is generated and dispatched, passing on the host name, path name and storage system type parameters to the low-level request handler. If the low-level create call is successful, a "register data set" call is made to the MCAT server, passing on the data set name, the collection in which to put the data set, the storage resource, the physical path name and the user name. The MCAT registration routine does a few sanity checks (such as the permission to create data sets in the specified collection, duplicate data set name, etc). If the registration is successful, a set of meta data associated with the newly created data set is added to the MCAT catalog. Finally, the SRB agent returns a handle to the client. The client can then use this handle for subsequent read/write calls. If the data set register call is unsuccessful, a low-level unlink call is dispatched and an error is returned to the client.

The low-level request handler handles low-level client requests dispatched directly from the request dispatch, or high-level client requests passed indirectly through the high-level request handler module. This module performs the basic I/O operations on behalf of the client on the various storage systems managed by the SRB agent. The common parameters passed to this module are the resource location (host name), the storage system type (UNIX, HPSS, DB2, etc) and the physical path name (UNIX path name). If the requested storage system is not local, it dispatches a remote call to the appropriate SRB agent. Otherwise, it calls its low-level drivers to carry out the I/O operation.

Two types of drivers, the file-type and the DB-type, are supported. The file-type drivers provide UNIX-like file I/O interfaces to the file system of the storage systems, i.e., UNIX, UniTree and HPSS. Other non-file system type drivers, such as FTP and HTTP, are also grouped under this category because the similarities in the I/O interface. I/O operations supported by the file-type drivers are create, open, close, unlink, read, write, sync, seek, stat, chmod, mkdir, opendir, closedir and readdir.

The DB-type drivers provide I/O interface to DB large objects stored in DBMS, i.e., DB2, Oracle and Illustra. . I/O operations supported by the DB-type drivers are create, open, close, unlink, read, write and seek.

TOP

The SRB container design

Due to the relative high overhead of creating/opening files in archival storage systems such as HPSS, they are not suitable for storing large number of small files typically found in digital library systems. The container concept was specifically designed to circumvent this type of limitation. The idea is through the use of containers, many small files can be aggregated in the cache system before storage in the archival storage system. The metadata for translating an inContainer object to file path, offset and size are kept in the MCAT and the SRB I/O drivers have been adapted to handle inContainer objects.

A caching system has been designed to handle container I/O. All container writes are done to the cache copy first. When a client is done filling up the container, a syncContainer call can be made to write the entire container copy to the archival storage system. For reading an object that has been stored in a container (inContainer object), if the container is not already on cache, the SRB server will stage the entire container to the cache first. Reading is done only on the cache copy. The metadata for translating an inContainer object to file path, offset and size are kept in the MCAT and the SRB I/O drivers have been adapted to handle inContainer objects.

The current version of the SRB server has been designed to handle multiple archival and cache storage resources. Multiple storage resources for containers was implemented through the use of logical resource. At the time of container creation, a logical resource is associated with the container being created through the srbContainerCreate() API.

Logical resource is an abstraction that contains one or more physical resources. Physical resource is a SRB abstraction that describe the underlying storage resources that can be accessed by the current SRB server configuration. In MCAT, a set of attributes is associated with a physical resource. Among other things, these attributes identify the location of the resource (host address and the path of the SRB vault), the type of resource (UNIX file system, HPSS file system and DB large objects), and the resource class (cache or permanent, primary or normal), etc.

The logical resource used to create a container should contain both classes of physical resources: "permanent/archival" (e.g., HPSS) and "cache" (e.g., UNIX disk file system) resources. A "cache" copy can be purged while a "permanent" copy is not purgable. Multiple resources for each resource class are allowed in which case, one and only one must be designated as "primary" for each resource class.

All container I/Os are done only to the copy on the "cache" type resource. If a "cache" copy does not exist (purged), the SRB server will attempt to stage a copy from the primary permanent resource to the primary cache resource first. If the primary permanent copy is not available (system or device down), other permanent copies will be used. Similarly, if the primary cache is not available, other cache resources belonging to the same logical resource will be used. It should be noted that the staging is done for the whole container rather than individual container segments. Once a "cache" copy is found or staged, read/write I/O can be carried out on objects contained in the container. If the cache copy has been modified, the srbSyncContainer() call or the Ssyncont command can be used to synchronize the cache copy to the archival resource.

The following software has been developed to support containers:

API - Five new APIs, srbContainerCreate(), srbRmContainer(), srbGetContainerInfo(), srbSyncContainer() and srbReplContainer() have been created to create, remove, query container info, synchronize and replicate(or stage) copies of a container.

Command line utilities - Five command line utilities: Smkcont, Srmcont, Ssyncont, Slscont and Sreplcont to create, remove, sync, list meta-data and replicate (stage) copies of a container. The Slscont command allows the listing of all containers owned or accessible by a user as well as listing all inContainer objects stored in a given container.

TOP

The SRB client API

'

Overview

Clients are provided with a set of API for sending requests and receiving response to/from the SRB servers.

A majority of the API performs some kind of operations on data sets. These APIs can be subdivided into 2 classes: high-level APIs and low-level APIs. The high-level APIs handle requests from clients for operations on data sets and resources that are in their logical represenatations. A typical high-level API handler queries the MCAT to convert the logical representations to their physical representations and then calls the low-level APIs to perform low level functions. In another words, high-level APIs handle requests with inputs in their logical representations while the low-level APIs handle physical representations type requests.

A normal client will only use the high-level APIs to interact with the SRB while the low-level APIs are mostly used for server to server type requests. In fact, most low level APIs are privileged operations. Only the high-level APIs will be described in this document.

The rest of the API handles client/server connections, interacts with MCAT for information query and meta data creation and update.

TOP

Description of API

A brief description of the SRB client API is given below. A more detailed description of the API can be found in [#Appendix A Appendix A].

'

1) Client/server connection API – This set of API handles opening and closing connection to a SRB server.

#srbConnect - Initiate a connection to a SRB server. This call is replacing clConnect.

#clConnect - Initiate a connection to a SRB server. This call is being replaced by srbConnect.

#tiUserConnect -– Initiate a connection to a SRB server by a TICKET USER. Normal authentication will be bypassed for a TICKET USER.

#clFinish - Close the current connection and free the srbConn data structure.

#clErrorMessage - Return the ErrorMessage of a connection. This is the error message returned by the SRB server from the current client call.

'

2) High-Level API:

#srbObjOpen - Open a SRB data set.

#srbObjOpenWithTicket - Open a SRB data set using a ticket.

#srbObjCreate - Create a SRB data set.

#srbObjClose - Close an opened data set.

#srbObjUnlink - Unlink a data set.

#srbObjRead - Read a block of data from a data set into buffer.

#srbObjWrite - Write content of buffer to a data set.

#srbObjSeek - Change the current read or write location on an data set.

#srbObjSync - Sync an opened SRB object.

#srbObjStat - Stat an SRB object.

#srbObjStat64 - Stat an SRB object and put results in a stat64 struct.

#srbObjGetdents - The SRB equivalent of the UNIX getdents call.

#srbObjGetdents64 - The SRB equivalent of the UNIX getdents64 call.

#srbObjProxyOpr - Proxy Operation request.

#srbObjProxyFunct - Proxy Function request.

#srbObjReplicate - Make a copy of a data set.

#srbObjMove - Move a data set from one resource to another.

#srbCreateCollect - Create a SRB collection.

#srbListCollect - List a SRB collection.

#srbModifyCollect - Modify a SRB collection.

#srbIssueTicket - Issue a ticket.

#srbRemoveTicket - Cancel a ticket.

#srbContainerCreate - Create a container.

#srbGetContainerInfo Get container info.

#srbRmContainer - Remove a container.

#srbSyncContainer - Synchronize copies of a container.

#srbReplContainer - Replicate/stage a container.

#srbObjGet - Download a file from SRB to local file system using parallel I/O.

#srbObjGetC - The client initiated version of srbObjGet..

#srbObjPut - Upload a file from local file system to SRB using parallel I/O.

#srbObjPutC - The client initiated version of srbObjPut.

#srbObjCopy - Copy a data set from one SRB path to another SRB path..

#srbSyncData - Synchronize all copies (replica) of an SRB object with the most recently modified version

#srbBulkRegister - Register inContainer object in bulk.

#srbExecCommand - Remote execution of command.

#srbExecFunction - Proxy Operation that exec a server builtin function.

#srbBulkLoad - Bulk upload a set of data files.

#srbBulkUnload - Bulk download of non-container files in a collection recursively.

#srbObjChksum - Checksum a SRB data file.

#srbGetFsFreeSpace - get the Vault File System free space.

#srbObjFStage - Stage a SRB data file. Only applicable to samfs resource

#srbBackupData - Backup a data object - Make a replica to the backup resource.

#srbGetSvrVersion - Get the Server version

'

2) API that interact with MCAT – This set of API interacts with MCAT for information query and meta data creation and update.

#srbGetDatasetInfo - Get some default Info on a SRB data set.

#srbGetDataDirInfo - Get arbitrary meta data info on users, data sets or resources by querying the MCAT catalog.

#srbRegisterDataset - Register a SRB data object.

#srbUnregisterDataset - Unregister a SRB data object.

#srbSetAuditTrail - Setting and Unsetting Audit Trail.

#srbModifyDataset - Modify a SRB data set

#srbChkMdasAuth - Authenticate a userName/passwd.

#srbChkMdasSysAuth - Authenticate a userName/passwd for sys admin access.

#srbRegisterUserGrp - Register a user group

#srbRegisterUser - Register a user.

#srbModifyUser - Modify a user info.

#srbGetPrivUsers - Read the privileged users list.

#srbGetMoreRows - Get more rows of result from a srbGetDatasetInfo, srbGetDataDirInfo, srbListCollect or srbGetPrivUsers call.

#freeSqlResult - Free any memory associated with a SQL result struct including the SQL result struct itself.

#clearSqlResult - Clear the memory associated with a SQL result struct, but the SQL result struct is not freed.

#printSqlResult - Print the content of a SQL result struct.

#srbGetContainerInfo - Query metadata associated with a container.

#srbRegisterLocation - Register/create a new location.

#srbIngestToken - Ingest/create a new Token of type ResourceType, DataType,UserType, Domain, or Action.

#srbRegisterResource - Register/create a new resource (physical or compound).

#srbRegisterLogicalResource - Register/create a new logical resource.

#srbRegisterReplicateResourceInfo - Add another physical resource to a logical or compound resource.

#srbDeleteValue - Delete/remove a value of type location, user, or resource (other types are implemented but untested).

#srbSetupSessionPublicKey - Get the MCAT-enabled server's public key in preparation for transferring encryptioned information.

#srbSetupSession - set up a session (for encryption) with the MCAT-enabled server.

'

3) Miscellaneous SRB API:

#srb_perror - Emits an SRB error message string corresponding to the input error code.

#srbVaultInfo - Get Info on the SRB storage vault.

#srbFreeVaultInfo - Free memory taken by the vaultQueElement link list.

#srbPrintVaultInfo - Print out the VaultInfo link list.

#srbHostConfig - Get the storage vault information on a SRB host.

#srbPrintHostInfo - Print the HostInfo link list.

#srbFreeHostInfo - Free memory taken by the clHostElement link list.

'

TOP

Setting up Client Environment

'

Building and installing the SRB client library

This section describes the steps for building and installing the SRB client library – libSrbClient.a.

1) Build and install the SRB client/server software described in http://www.sdsc.edu/srb/matrix/wiki2/index.php/Installation

2) Type in "gmake install" to install the software in the $(installDir) directory. This procedure installs the following module in the $(installDir) directory:

bin/libSrbClient.a - The client library.

TOP

Setting up the client user environment

Before a user can connect to the SRB server, the following user environment setup must be carried out:

1) The ~/.srb/..MdasEnv file - A template of the file can be found in utilities/envFiles/.MdasEnv of the distribution package. This file contains four parameters:

a) mdasCollectionHome - This is equivalent to the user's home directory (collect) and is created by the MCAT administrator at the time of the user registration.

b) mdasDomainHome - This is the domain name associated with the user. This domain name is assigned to the user at the time of the user registration.

c) srbUser - This is the user name of the user. This name is assigned to the user at the time of the user registration.

d) srbHost - This is the default host address of the SRB server when a SRB client initiates a SRB connection.

e) AUTH_SCHEME - This parameter defines the authentication scheme to use. Valid input values are:

'ENCRYPT1' - SDSC's encrypted password based challenge/response scheme

'GSI_AUTH' - Use the GSI authentication scheme. If this option is chosen, an additional parameter SERVER_DN given below is required.

If this parameter is not defined, the 'ENCRYPT1' Authentication scheme will be used.

2) Setting up user authentication - The AUTH_SCHEME parameter in the .MdasEnv file is used to define the authentication scheme to use. Each authentication scheme requires a different setup by the user.

a) ENCRYPT1 authentication setup - This is a plain text password setup where the password is generated at the time of user registration with the MCAT catalog. Upon receiving this password from the MCAT administrator, a user should place it in a file named ~/.srb/.MdasAuth which will be used directly by the SRB library to authenticate the user.

b) GSI authentication setup - Please read [README.gsi.htm README.gsi] and follow the HTTP links for GSI client environment setup suggested by in the document. Once the certification/key has been obtained and converted to PEM format for GSI use, look into the cert pem file with a text editor and locate the user "Distinguish Name" string. The string representing the "Distinguish Name" should look like the following:

subject=/C=US/O=NPACI/OU=SDSC/UID=srb/CN=Storage Resource Broker/Email=srb@sdsc.edu

Copy this string and send it to the SRB administrator for registration.

NOTE: Currently, the SDSC SRB servers are configured to handle both Mdas and SEA authentication.

[[#SRB - The Storage Resource Broker (Version 3.4.0) | TOP]

Locations of the SRB client library and header files

The SRB client library is installed in $(installDir)/bin/libSrbClient.a.

A client program should include the header file "srbClient.h" and the compilation header file search directive should include the following directories:

$(buildDir)/src/include

$(buildDir)/src/catalog/include

The Makefile in the test/examples directory gives an example of a makefile for making SRB client code.

TOP

Client Programming

Examples on the use of SRB client APIs can be found in the test/examples/src directory of the source distribution.We will go through some of these examples in this chapter.

Connecting and disconnecting to the SRB Server

The sconnect.c file in the examples directory gives an example of a client connecting and disconnecting to the SRB Server. The client uses the srbConnect () call to connect to the SRB server. Prototype of this call is:

srbConn * srbconnect (char* srbHost, char* srbPort, char* srbAuth, char *userName, char *domainName, char *authScheme, char *serverDn)

srbHost - the host address of the SRB server. srbPort - the port number of he SRB server. srbAuth - the password if ENCRYPT1 authentication scheme is used. userName - the user name of the client domainName - the domain name of the client. authScheme - the authentication scheme to use - "ENCRYPT1" or "GSI_AUTH" serverDn - the Distinguish Name of the server user.

A NULL value can be used for any one of these inputs in which case, the values will be taken from the .MdasEnv file.

If this call is successful, a non-null handle will be returned which can be used for all subsequent API calls. Upon completion, the clFinish call should be used to close the connection to the SRB server.

The following is some codes taken from the sconnect.c file:

   srbConn *conn;
   srbResult *res;

   conn = srbConnect (HOST, PORT, SRB_AUTH, USER, DOMAIN, AUTH_SCHEME, 
     SERVER_DN);
   if (clStatus(conn) != CLI_CONNECTION_OK) {
       fprintf(stderr,"Connection to srbMaster failed.\n");
       fprintf(stderr,"%s",clErrorMessage(conn));
       srb_perror (2, clStatus(conn), "", SRB_RCMD_ACTION|SRB_LONG_MSG);
       clFinish (conn);
       exit (1);
   }

   printf ("Connected to srbServer successfully\n");

   clFinish(conn);

TOP

Error handling

The SRB uses two methods to return error conditions to the client. The first is the commonly used method of returning a value with the client API. In general, for integer type return values, a negative returned value implies error. For string type returns, a NULL returned value implies error. The error code for integer type returns are given in include/srb_error.h . Typically, these are error codes that are internally generated by the SRB and MCAT. Given the integer error code, an error message string can be generated using the srb_perror() API or the Serror utility.

The SRB server can also return a more informative error conditions in the form of a text string, but the client must use the clErrorMessage(conn) call to retrieve the message. Typically, it contains a short message describing the error condition and often times, the error codes from the underlying storage system (e.g., HPSS, UniTree, etc) is also included.

TOP

Client programming examples

The following files in the test/examples/src directory give specific examples of using the SRB client API:

sconnect.c - connect to a SRB server.

sput.c - upload a file to SRB.

sget.c - download a file from SRB.

sreplicate.c - replicate a SRB file.

sgetcopy.c - download a specific replica from SRB.

sstat.c - Get the stat (similar to the fstat() call) of a SRB file.

sgetdents.c - This the the SRB equivalent of the getdents() call in UNIX.

squery.c - query the MCAT metadata.

The following are two selected examples of using the SRB client API.

1) Uploading a file to SRB - sput.c

   /* Need to connect to SRB first */

   conn = srbConnect (HOST, PORT, SRB_AUTH, USER, DOMAIN, AUTH_SCHEME, 
     SERVER_DN);
   if (clStatus(conn) != CLI_CONNECTION_OK) {
       fprintf(stderr,"Connection to srbMaster failed.\n");
       fprintf(stderr,"%s",clErrorMessage(conn));
       srb_perror (2, clStatus(conn), "", SRB_RCMD_ACTION|SRB_LONG_MSG);
       clFinish (conn);
       free (buf);
       exit (1);
   }

   /* Create a srb file. need to specify the fileName - argv[2] */

   out_fd = srbObjCreate (conn, MDAS_CATALOG, argv[2],
     DATATYPE, RESOURCE ,COLLECTION, NULL, -1);

   if (out_fd < 0) { /* error */
       fprintf(stderr, "can't create srb file \"%s\", status = %d\n", argv[2], 
       out_fd);
       fprintf(stderr,"%s",clErrorMessage(conn));
       clFinish (conn);
       free (buf);
       exit (1);
   }

   /* Open a local file with filename = argv[1]. */

   in_fd = open (argv[1], O_RDONLY, 0);
   if (in_fd < 0) { /* error */
       fprintf(stderr, "can't open file\"%s\"\n", argv[1]);
       clFinish (conn);
       free (buf);
       exit (1);
   }

   /* Read from the local file and write to the just created srb file */
   total = 0;
   while ((bytesRead = read(in_fd, buf, BUFSIZE)) > 0) {
       /* Write to the data object */
       bytesWritten = srbObjWrite(conn, out_fd, buf, bytesRead);
       if (bytesWritten < bytesRead) {
          fprintf(stderr, "Error: Read %d bytes, Wrote %d bytes.\n ",
          bytesRead, bytesWritten);
           clFinish (conn);
           free (buf);
           exit (1);
       }
       total += bytesWritten;
   }

   /* remember to close the opened files */
   srbObjClose (conn, out_fd);
   close (in_fd);

2) MCAT query example - squery.c

* srbGetDataDirInfo(srbConn* conn, int catType, char qval[][MAX_TOKEN],
* int *selval, mdasC_sql_result_struct *myresult, int rowsWanted)
*
* srbGetDataDirInfo - Get metadata info by querying the MDAS catalog.
* The server uses the input qval[][] and selval[] array to compose
* and execute SQL queries and returns the query result in myresult.
* The selval[] array specifies a list of attrbutes to retrieve and
* qval[][] specifies a lists of predicates to search.
* Both selval[] and qval[][] must be arrays of size MAX_DCS_NUM and
* are indexed by values given in mdasC_db2_externs.h under the heading
* DCS-ATTRIBUTE-INDEX DEFINES.
*
* For the selval[] array, setting an element of the array to 1 means that
* the attribute associated with this element is to be retrieved. e.g.,
* selval[USER_NAME] = 1; means the "user_name" attribute is to be retrieved.
* The qval[][] array specifies the predicates of the query.
*/

TOP

5.0 Installing and configuring the SRB servers

This section describes the steps for installing and configuring the SRB servers. The SRB architecture supports multiple SRB servers running on various hosts. Metadata of data sets, resources and users managed by the SRB is stored in the MCAT catalog maintained in a relational database (DBMS). Therefore, a SRB installation may consist of multiple SRB servers running on various hosts, but only one SRB server is designated to interface with the MCAT database server. This server is built by defining the ORAMCAT or DB2MCAT keyword (see section [#Building and installing the SRB server 5.1] for definition) in the mk/mk.config file. This server is marked by the MDAS_ENABLED keyword in the data/hostConfig file.

Before any SRB server can be started, the MCAT catalog must be built and the MCAT server (DBMS) running. In addition, the user starting the SRB servers must have already been registered as a privileged user in MCAT. Currently at SDSC, we are running the MCAT server on a Oracle DBMS and the MDAS_ENABLED SRB server running on host gabor.sdsc.edu. Please email srb@sdsc.edu if a site wishes to use our MCAT server for its SRB metadata. If a site wants to setup and run its own MCAT catalog, the installation and configuration of the MCAT and the MCAT server are given in http://www.npaci.edu/DICE/Software/SRB/mcat.html.

If the SEA authentication scheme is to be used, and if the SEA library (libsea.a) does not already exist on your build platform, the SEA software which can be obtained at URL http://www.npaci.edu/DICE/Software/SEA/index.html, must be built first.

[#Beginning Image:Top.gif] '

5.1 Building and installing the SRB server

The following describes the steps for building and installing the SRB server software:

1) Edit the mk/mk.config file. All configurable parameters for building the SRB server and the client library are defined in this file.

The SRB architecture supports multiple SRB servers running on various hosts. Each SRB server may be built with different options defined in the mk/mk.config file. For example, the SRB server on host A may include the driver for accessing HPPS and the SRB server on host B may include the driver for accessing the Lobj stored in DB2, etc.

The parameters are self-explanatory through the comments given in this file. Some of the more important parameters are discussed below:

a) Basic build configuration:

installDir - The absolute path of the SRB install directory.

PORTNAME - The OS platform of this SRB port. Currently, the SRB software runs on 8 platforms. Valid PORTNAMEs are: PORTNAME_solaris, PORTNAME_sunos, PORTNAME_linux, PORTNAME_aix, PORTNAME_alpha, PORTNAME_osx, PORTNAME_c90 and PORTNAME_sgi.

b) MCAT flags – Enable any MCAT service that would be controlled by this SRB server.

ORAMCAT - defines that this SRB server being built is MDAS enabled and the MCAT is stored in Oracle DBMS. Normally, only one SRB server is MDAS enabled. Commented out by default.

DB2MCAT - defines that this SRB server being built is MDAS enabled and the MCAT is stored in Oracle DBMS. Normally, only one SRB server is MDAS enabled. Commented out by default.

NOTE: Both ORAMCAT and DB2MCAT cannot be defined at the same time.

c) Authentication flags

MDAS_AUTH - defines whether the MDAS authorization scheme will be supported for authentication. If used, the user/passwd pair registered with the MCAT catalog will be used to authenticate a user. Comment it out if the SRB server does not support MDAS authorization.

SEA_AUTH - defines whether SEA authorization scheme will be supported. The software can be configured to support both SEA_AUTH and MDAS_AUTH.

LIB_SEA - Is needed only if SEA_AUTH is defined. LIB_SEA specifies where the SEA client library is located. This library can be built from the SEA source branch in this package.

GSI_AUTH - defines whether GSI authorization scheme will be supported. The software can be configured to support GSI_AUTH, SEA_AUTH and MDAS_AUTH. This is OFF (commented out) by default.

LIB_GSI_AUTH - Is needed only if GSI_AUTH is defined. GSI_AUTH specifies where the GSI client library is located. This is commented out by default.

NOTE: Currently, the SDSC SRB servers are configured to handle all three authentication.

d) ADR_PROXY - defines whether the ADR DataCutter proxy operation will be supported.

e) JAVA_GUI and javaDir - JAVA_GUI defines whether the srbBrowser should be built. javaDir specifies the directory where the JDK software is installed. (e.g. /usr/local/apps/Java). In addition, if JAVA_GUI and javaDir are set, you must setenv CLASSPATH to "." and the path where the swing.jar is installed on your machine. e.g. setenv CLASSPATH /local/generic/lib/java/swing/swing.jar:.

Note: This software must be built using JDK 1.1.6 or 1.1.7 and swing 1.0.2.

f) Storage system flags – Flags such as HPSS, UTREE, FTP, DB_DB2, DB_Illustra, etc define whether a particular storage system will be supported by this SRB server. UNIX, FTP and HTTP are enabled by default. Other flags related to storage system:

SRB_LARGEFILE64 - defines whether the 64 bit file size is supported by the underlining driver of this SRB server. Current, 64 bit file size is supported by the PORTNAME_solaris, PORTNAME_aix, PORTNAME_linux and PORTNAME_c90 platforms.:

If the HPSS flag is set, the NO_DCE flag specifies whether the DCEless client library developed by Mike Gleicher will be used. Please contact Mike at mkg@san.rr.com for informations regarding licensing this library. If this flag is not set, the regular DCE authentication is assumed. In addition, a number of HPSS library and header directory paths including HPSS_LIB_DIR, HPSS_HDR_DIR, etc need to be specified for the build.

2) "cd" to the main SRB directory and type in "gmake clean" and then "gmake" to make the SRB software. The Makefile contains various options to make and clean all or a subset of the build.

gmake --- build all.

gmake clean --- clean all.

gmake srb --- build only the SRB server and client.

gmake clean_srb --- clean only the SRB server and client.

gmake util --- build only the utilities (S commands).

gmake clean_util --- clean only the utilities.

gmake browser - build only the java srbBrowser GUI.

gmake clean_browser - clean only the java srbBrowser.

3) Type in "gmake install" to install the software in the $(installDir) directory. This procedure installs the following modules in the $(installDir) directory:

bin/runsrb - The script that starts the SRB

bin/srbMaster-2.0.0 - The frontend server.

bin/srbServer - The backend server (forked by the srbMaster-2.0.0 for each client connection).

bin/libSrbClient.a - The client library.

data/hostAuthConfig - The optional (needed only if HOST_BASED_AUTH in the mk.config file is set) host based authorization configuration file.

data/mcatHost - This file identifies the host on which the MCAT enabled SRB server and the authentication scheme to use to connect to this server.

data/hostConfig - This is the optional SRB host configuration file. It is only needed when when you want to add aliases to your local hostName.

data/hpssCosConfig - This is the optional HPSS Class of Services configuration file. It is only needed if HPSS in the mk.config file is set.

data/hpssNodceAuth - The file contains authentication info for non-dce HPSS. It is only needed if the HPSS and NO_DCE flags in the mk.config file are set.

data/MdasConfig - The MDAS configuration file.

data/metadata.fkrel - This file defines the foreign key relationship between the MDAS catalog tables and is used internally by the SRB for query generation. This file should not be changed between releases.

data/LobjConfig - The database configuration file for the DB Large Object driver. Basically, it contains the userID and password for accessing each database server.

Files installed in the data/ directory are templates for various configuration files. Details for configuring these files are given in the next section.

[#Beginning Image:Top.gif] '

5.2 Configuring the SRB servers

5.2.1 Quick server setup

This section provides short notes on quick setup and startup of the SRB server. For more detail descriptions of setup, please read section [#Detailed server setup 5.2.2]

A) Setup for servers with UNIX driver only:

1) Configure the SRB user environment with the ~/.srb/.MdasEnv and ~/.srb/.MdasAuth files. Templates of these files can be found in the utilities/envFiles directory.

2) Configure the data/mcatHost file. If you are going to use SDSC MCAT, no change is needed.

3) To run the SRB server, type in:

cd bin

runsrb

This should start the SRB server. If it is not running,the data/srbLog file should give hints on why it is not running.

4) Check the data/srbLog file - The first line should contain something like:

LocalHostName: ghidorah, localhost, .....

followed by:

Local storage vault conf:

storSysType: 0, vaultPath: /projects/mdas/srb/SRBVaultTest

.

.

The LocalHostName list shows all the addresses of your local host recognized by the SRB server. It uses the gethostbyname() call to get the local addresses. There are situations where the local host address registered with MCAT may not show up with this call. Then, the "Local storage vault conf" will be empty. In this case, use the data/hostConfig file to include the MCAT registered host address to your local addresses.

B) Setup for servers with HPSS driver:

1) Build the SRB server with the HPSS flag set in the mk/mk.config file. In addition, the HPSS driver can use either the normally used DCE authentication or the NON-DCE implementation developed by Mike Gleicher. Please contact Mike at mkg@san.rr.com for informations regarding the licensing of the Non-DCE HPSS client/server software. If the NON-DCE authentication is used, the NO_DCE flag in mk/mk.config should be set before the build. If it is not set, DCE authentication is assumed.

2) Go through same procedures as A).

3) Configure the data/hpssCosConfig file.

4a) For NON-DCE authentication, configure the data/hpssNodceAuth file as described in the comment fields in the file. Basically, this file should contain the HPSS userID/password pair of the SRB user (the userID under which the SRB server runs).

NOTE: The NON-DCE authentication works only with the Non-DCE HPSS client/server implemented by Mike Gleicher.

4b) For DCE authentication, create a DCE keytab file and change the srbKeytabName parameter in bin/runsrb to point to this file path and the srbPrincipalName to the UserId associated with this keytab file.

C) Setup for servers with DB large object drivers:

1) Go through same procedures as A).

2) Configure the data/LobjConfig file.

[#Beginning Image:Top.gif] '

5.2.2 Detailed server setup

1) Setting up the SRB user environment - Before a user can start the SRB server, the procedures for setting up user environment given in section [#Building and installing the SRB client library 3.1] must be carried out. For GSI authentication, please read the section on " Steps to set up SRB Server certificates" in [README.gsi.htm README.gsi].

2) Setting up the SRB configuration files - Modifications to the following configuration files are needed for each SRB server installation:

data/mcatHost - This file identifies the host on which the MCAT enabled server and the authentication scheme to use to connect to this server.

data/hostAuthConfig - The optional host based authorization configuration file. This file specifies who and from which IP address/domain the client connection may come from. The parameters are self-explanatory through the comments given in this file. It is needed only if HOST_BASED_AUTH is enabled in mk/mk.config

data/hostConfig - This is the optional SRB host configuration file. It is only needed when when you want to add aliases to your local hostName.

data/MdasConfig - The MDAS configuration file. Only the MDAS_ENABLED SRB server requires this file. The current MCAT catalog is kept in a Oracle database. This file contains basic informations required for SRB to interface with the MCAT catalog. Configurable parameters include SRB's Oracle userid, password and log file location.

data/LobjConfig - The configuration file for the DBMS Large Object drivers. Basically, it contains the userID and password required for authenticating the SRB server with DBMS where the large objects are stored. The parameters defined in this file are Db2User, Db2Passwd for DB2), IllusUser, IllusPasswd (for Illustra), OracleUser and OraclePasswd (for Oracle). Input to some of these parameters can be blank if the SRB server being started does not support a particular DBMS.

data/hpssCosConfig - This file configures the HPSS Class Of Service (COS). Basically, this file contains a table with two columns - "COS ID" and "Maximum file size in KBytes". It is used by the HPSS driver for choosing the appropriate COS based on the "dataSize" input parameter of the srbObjCreate() call.

bin/runsrb - This is the startup script for the SRB server. Modifications of some env variables defined in this file may be required. The parameters are self-explanatory through the comments given in this file.

data/hpssNodceAuth - This file specifies the userID/passwd pair for authenticating the SRB server with the NON-DCE HPSS system. This file is needed only when the NO_DCE in the mk.config file is set. Otherwise, for DCE HPSS authentication, create a DCE keytab file and change the srbKeytabName parameter in bin/runsrb to point to this file path.

[#Beginning Image:Top.gif] '

5.3 Starting the SRB server

The servers in the SRB environment must be started in the following order:

1) The MCAT DBMS server.

2) The MDAS_ENABLED SRB server.

3) The rest of the SRB servers.

The script bin/runsrb is used to start the SRB server. To start the SRB server, type in:

. cd bin

. runsrb

[#Beginning Image:Top.gif] '

5.4 Running the test suite

After installing the SRB server for the first time, the test suite given in the test/testsuite directory should be run. To run the test suite, modify inputs such as AUTH, DOMAIN, HOST and PORT as required in the "testsuite" script file in the test/testsuite directory and type in the following:

. cd test/testsuite

. gmake clean

. gmake

. testsuite

[#Beginning Image:Top.gif] '

6.0 Building and Running the JAVA based srbBrowser

This section describes the steps for Building and Running the JAVA based srbBrowser. The srbBrowser is a JAVA based SRB client GUI. It can be used to perform a variety of client level operations including replication, copy and paste, registration of datasets and metadata manipulation and query, etc.

 6.1 Building the JAVA based srbBrowser 

Section [#Building and installing the SRB client library 3.1] gives a brief description of building the srbBrowser software as part of the client library build. The following gives a more detailed descriptions of the build:

1) The SRB client library (e.g., gmake srb) and utilities (e.g., gmake util) must be built before building the srbBrowser.

2) setenv CLASSPATH to the path where the swing.jar is installed on your machine and ".". e.g.,

setenv CLASSPATH /local/generic/lib/java/swing/swing.jar:.

3) Edit the data/mk.config file and define the "JAVA_GUI" parameter and set the "javaDir" parameter to the directory where your JDK is installed.

4) "cd" to the main SRB directory and type in "gmake clean_browser" and then "gmake browser" or, "cd java" and type in "gmake clean" and then "gmake".

[#Beginning Image:Top.gif] '

6.2 Running the JAVA based srbBrowser

To run the srbBrowser, setenv DISPLAY to your workstation, "cd java/bin" and type in "srbBrowser".

The following lists the SRB operations that can be carried out using the srbBrowser GUI:

1) The "Default" pull down menu allow a client to select the default storage resource and set the default comment. The default resource will be used for all subsequent dataset creation until it is changed. The default comment can be used for creating new comments for datasets.

2) The "Operations" menu shows the type of operations that can be performed depending what was selected. The following operations have been implemented:

"New" - make a new "Collection"

"Replicate" - Replicate a dataset or collection (recursively). Two choices are allowed: replicate to the default storage resource or choose a resource for replication.

"Copy" a dataset or collection - The following steps should be taken:

1) Select a dataset or a collection to be copied (source).

2) Select the "Copy" menu from the "Operation" pulldown menu.

3) Select the destination dataset or collection.

4) Select the "Paste" menu from the "Operation" pulldown menu.

"Delete" - Delete a dataset or a collection recursively.

"Import" - Import a file or directory from a local file system. The following steps should be taken:

1) Select the destination dataset or collection.

2) Select the "Import from Local FS" menu from the "Operation" pulldown menu.

3) A file chooser dialog box should appear. Browse through the local FS and selection a file or a directory to be imported from (source). Click on the "Open" button of the file chooser dialog box.

"Export" - Export a dataset or collection to a local file system. The following steps should be taken:

1) Select the source dataset or collection to be exported.

2) Select the "Export to Local FS" menu from the "Operation" pulldown menu.

3) A file chooser dialog box should appear. Browse through the local FS and selection a file or a directory to export to (destination). Click on the "Open" button of the file chooser dialog box.

"Register" and "Unregister" - Register and Unregister local files and directory. These functions may be recursive. Comparing to the "Import" and "Export" functions, registering a local file does not involve the the copying of the file physically. Rather, the file is registered with MCAT and hence becomes visible to the SRB world. For "Register" to work, your local file must be accessible by one of the SRB server in the federation. The following three steps must be taken to register a local file:

1) Set the default resource (through the "Default" menu) to the resource controlled by the SRB server that can access your local file.

2) Select a collection where you want this registered dataset or collection to reside.

3) Select the "Register Local FS" menu item from the "Operation" pull down menu and then selection the local file or directory you wish to register.

"Rename" - Rename a dataset.

"Display" - Display allows graphical (jpeg, gif, etc) and text (C, html, etc) files to be displayed in the srbBrowser window. This can also be achieved by double clicking the file displayed in the metadata window.

3) The "Metadata" menu allows the manipulation and querying of system level metadata. Manipulation of two attributes - "Access Control" and "Comments" has been implemented thus far.

The "Set Access Cntl" menu can be used to grant access permission of a dataset or a collection to individual users or group of users. Recursive operation is allowed for setting the access permission of a collection.

The "List Access Cntl" menu can be used to list the access permission of datasets and collections.

The "New Comment" menu can be used to attach a new "comment" to a dataset. A new comment can be created completely new or by adding to the default comment.

The "Modify Comment" menu can be used to modify an existing comment. Modification can be done by replacing the entire comment or appending to the current comment. The menu also allows the deletion of a comment.

The "Query Comment" menu can be used to query datasets based on the content of these comments. If a collection is selected for querying, the query will be done for all descendants of the collection. If a dataset is selected for querying, the content the comment for this dataset will be listed.

4) The "View" menu has only one sub-menu - "Refresh". The srbBrowser always try to update the tree structure and the metadata displayed in the window whenever changes were made by the srbBrowser. The "Refresh" function allowed the display to be refreshed after changes were made external to the srbBrowser.

[#Beginning Image:Top.gif] '

7.0 Building and Running srbMon - a SRB server monitoring program

This section describes the steps for Building and Running the srbMon daemon. The srbMon daemon is a SRB monitoring daemon which remotely monitors and logs all SRB servers belonging to a federation, and attempts to restart any servers that were found to be down..

To build srbMon, "cd admin" and type in "gmake clean" and then "gmake".

To run srbMon, the following steps should be carried out:

1) srbMon should be run on a host which does not belong to the SRB federation to be monitored.

2) Configure the admin/data/srbHostFile file. This file should contain all the hosts in the federation to be monitored.

3) srbMon uses "rsh" to start any SRB servers that were found to be down. Therefore, SRB admin must make sure that remote shell type permissions are properly setup (i.e., .rhosts and /etc/hosts.equiv files, etc) on each host being monitored.

4) To run the daemon, "cd admin/bin" and type in "srbMon1_1_2". This daemon will sleep most of the time, waking up every 10 minutes to monitor the SRB servers.

5) The srbMon daemon generates a log file - admin/data/monLog, logging the status of each server and action performed.

[#Beginning Image:Top.gif]

 Appendix A – Descriptions of the SRB Client API  1) Client/Server connection API: [#srbConnect srbConnect]
[#clConnect clConnect]
[#tiUserConnect tiUserConnect]
[#clFinish clFinish]
[#clErrorMessage clErrorMessage]
  2) High-level API: [#srbObjOpen srbObjOpen]
[#srbObjOpenWithTicket srbObjOpenWithTicket]
[#srbObjCreate srbObjCreate]
[#srbObjClose srbObjClose]
[#srbObjUnlink srbObjUnlink]
[#srbObjRead srbObjRead]
[#srbObjSeek srbObjSeek]
[#srbObjSync srbObjSync]
[#srbObjStat srbObjStat]
[#srbObjStat64 srbObjStat64]
[#srbObjGetdents srbObjGetdents]
[#srbObjGetdents64 srbObjGetdents64]
[#srbObjProxyOpr srbObjProxyOpr]
[#srbExecCommand srbExecCommand]
[#srbObjReplicate srbObjReplicate]
[#srbObjMove srbObjMove]
[#srbObjWrite srbObjWrite]
[#srbCreateCollect srbCreateCollect]
[#srbListCollect srbListCollect]
[#srbModifyCollect srbModifyCollect]
[#srbIssueTicket srbIssueTicket]
[#srbRemoveTicket srbRemoveTicket]
[#srbContainerCreate srbContainerCreate]
[#srbRmContainer srbRmContainer]
[#srbSyncContainer srbSyncContainer]
[#srbReplContainer srbReplContainer]
[#srbObjGet srbObjGet]
[#srbObjPut srbObjPut]
[#srbSyncData srbSyncData]
  3) Low-level File-type API: [#srbFileOpen srbFileOpen]
[#srbFileCreate srbFileCreate]
[#srbFileUnlink srbFileUnlink]
[#srbFileClose srbFileClose]
[#srbFileRead srbFileRead]
[#srbFileWrite srbFileWrite]
[#srbFileSeek srbFileSeek]
[#srbFileSync srbFileSync]
[#srbFileStat srbFileStat]
[#srbFileFstat srbFileFstat]
[#srbFileMkdir srbFileMkdir]
[#srbFileChmod srbFileChmod]
[#srbFileRmdir srbFileRmdir]
[#srbSetStorAttri srbSetStorAttri]
[#srbOpendir srbOpendir]
[#srbClosedir srbClosedir]
[#srbReaddir srbReaddir]
  4) Low-level DB-type API: [#srbDbLobjOpen srbDbLobjOpen]
[#srbDbLobjCreate srbDbLobjCreate]
[#srbDbLobjClose srbDbLobjClose]
[#srbDbLobjRead srbDbLobjRead]
[#srbDbLobjWrite srbDbLobjWrite]
[#srbDbLobjSeek srbDbLobjSeek]
[#srbDbLobjUnlink srbDbLobjUnlink]
  5) Low-level DB Table API: [#srbDbTableOpen srbDbTableOpen]
[#srbDbTableCreate srbDbTableCreate]
[#srbDbTableClose srbDbTableClose]
[#srbDbTableRead srbDbTableRead]
[#srbDbTableWrite srbDbTableWrite]
[#srbDbTableSeek srbDbTableSeek]
[#srbDbTableUnlink srbDbTableUnlink]
  6) MCAT related API: [#srbGetDatasetInfo srbGetDatasetInfo]
[#srbGetDataDirInfo srbGetDataDirInfo]
[#srbRegisterDataset srbRegisterDataset]
[#srbUnregisterDataset srbUnregisterDataset]
[#srbSetAuditTrail srbSetAuditTrail]
[#srbModifyDataset srbModifyDataset]
[#srbChkMdasAuth srbChkMdasAuth]
[#srbChkMdasSysAuth srbChkMdasSysAuth]
[#srbRegisterUserGrp srbRegisterUserGrp]
[#srbRegisterUser srbRegisterUser]
[#srbModifyUser srbModifyUser]
[#srbGetPrivUsers srbGetPrivUsers]
[#srbGetMoreRows srbGetMoreRows]
[#freeSqlResult freeSqlResult]
[#clearSqlResult clearSqlResult]
[#printSqlResult printSqlResult]
[#srbGetContainerInfo srbGetContainerInfo]
[#srbRegisterLocation srbRegisterLocation]
[#srbIngestToken srbIngestToken]
[#srbRegisterResource srbRegisterResource]
[#srbRegisterLogicalResource srbRegisterLogicalResource]
[#srbRegisterReplicateResourceInfo srbRegisterReplicateResourceInfo]
[#srbDeleteValue srbDeleteValue]
[#srbSetupSessionPublicKey srbSetupSessionPublicKey]
[#srbSetupSession srbSetupSession]
  6) Miscellaneous SRB API. [#srb_perror srb_perror]
[#srbVaultInfo srbVaultInfo]
[#srbFreeVaultInfo srbFreeVaultInfo]
[#srbPrintVaultInfo srbPrintVaultInfo]
[#srbHostConfig srbHostConfig]
[#srbPrintHostInfo srbPrintHostInfo]
[#srbFreeHostInfo srbFreeHostInfo]
  [#Beginning Image:Top.gif]   Appendix B - Descriptions of the dataCutter Client API [#sfoCreateIndex sfoCreateIndex]
[#sfoDeleteIndex sfoDeleteIndex]
[#sfoSearchIndex sfoSearchIndex]
[#sfoGetMoreSearchResult sfoGetMoreSearchResult]
[#sfoApplyFilter sfoApplyFilter]
[#sfoGetMoreFilterResult sfoGetMoreFilterResult]
[#sfoFreeIndexResults sfoFreeIndexResults]
[#sfoFreeFilterResults sfoFreeFilterResults]
[#sfoFreeSegmentInfo sfoFreeSegmentInfo]
  [#Beginning Image:Top.gif]   NAME srbConnect SYNOPSIS  

#include "srbClient.h"

srbConn* srbConnect(char *srbHost, char* srbPort, char* srbAuth, char *userName, char *domainName, char *authScheme, char *serverDn);

DESCRIPTION

Establish a connection to a srbServer through the srbMaster at the specified host and port. This API replaces the clConnect () API.

SrbHost

The host address of srbMaster. If the input value in NULL, it will use the env variable "srbHost" if it is defined. If it is not defined, the ~/.srb/.MdasEnv file will be checked next. If not, it will use the hostname of the client machine.

SrbPort

The port number of srbMaster. If the input value in NULL, it will use the env variable "srbPort" if it is defined. Otherwise, the value defined in the ~/.srb/.MdasEnv file will be used.

SrbAuth

The auth string. It is used to define the password for MDAS or SEA authentication. For SEA authentication, this is the password used by the SEA library to decrypt the encrypted private key stored in the file ~/.SEAuuuuu@ddddd (where uuuuu is the user ID and ddddd is the user domain name). This input is not needed if an unencrypted private key is available in the /tmp directory (generated using the 'seaauth auto' command). To provide additional flexibility, a client may also use the env variable "srbAuth" to specify the password. A client may also supply the password in the ~.srb/.MdasAuth file. If a client uses more than one method to specify the password, the value given in this function call will take precedent, then the env variable "srbAuth", and lastly, the ~.srb/.MdasAuth file.

UserName

The user ID of the user. If the input value in NULL, it will use the env variable "srbUser" if it is defined. Otherwise, the vaule defined in the ~/.srb/.MdasEnv file will be used.

DomainName

The domain of the user. If the input value in NULL, it will use the env variable "mdasDomainHome" if it is defined. Otherwise, the vaule defined in the ~/.srb/.MdasEnv file will be used.

AuthScheme

The scheme to use for authentication. If the input value in NULL, the vaule defined in the ~/.srb/.MdasEnv file will be used. Valid values are 'PASSWD_AUTH', 'ENCRYPT1', 'SEA_AUTH', 'SEA_ENCRYPT', 'GSI_AUTH' and 'GSI_SECURE_COMM'

ServerDn

The distinguish name of the server user. This input is valid only for GSI authentication. RETURN VALUES

Returns a srbConn* which is needed for all subsequent client calls. Error if the status field of the connection returned is CONNECTION_BAD. ERRORS CONNECTION_BAD in the status field of srbConn. SEE ALSO [#clConnect clConnect], [#tiUserConnect tiUserConnect], [#clFinish clFinish] and [#clErrorMessage clErrorMessage]. [#Appendix A Top of Client API Table] NAME clConnect SYNOPSIS #include "srbClient.h" srbConn* clConnect(char* srbHost, char* srbPort, char* srbAuth); DESCRIPTION Establish a connection to a srbServer through the srbMaster at the specified host and port. This API is being replaced by the srbConnect () call.

SrbHost

The host address of srbMaster. If the input value in NULL, it will use the env variable "srbHost" if it is defined. If it is not defined, the ~/.srb/.MdasEnv file will be checked next. If not, it will use the hostname of the client machine.

SrbPort

The port number of srbMaster. If the input value in NULL, it will use the env variable "srbPort" if it is defined. If not, it defaults to the default port 5558).

SrbAuth

The auth string. It is used to define the password for MDAS or SEA authentication. For SEA authentication, this is the password used by the SEA library to decrypt the encrypted private key stored in the file ~/.SEAuuuuu@ddddd (where uuuuu is the user ID and ddddd is the user domain name). This input is not needed if an unencrypted private key is available in the /tmp directory (generated using the 'seaauth auto' command). To provide additional flexibility, a client may also use the env variable "srbAuth" to specify the password. A client may also supply the password in the ~.srb/.MdasAuth file. If a client uses more than one method to specify the password, the value given in this function call will take precedent, then the env variable "srbAuth", and lastly, the ~.srb/.MdasAuth file. RETURN VALUES

Returns a srbConn* which is needed for all subsequent client calls. Error if the status field of the connection returned is CONNECTION_BAD. ERRORS CONNECTION_BAD in the status field of srbConn. SEE ALSO [#srbConnect srbConnect], [#tiUserConnect tiUserConnect], [#clFinish clFinish] and [#clErrorMessage clErrorMessage]. [#Appendix A Top of Client API Table] NAME tiUserConnect SYNOPSIS #include "srbClient.h" srbConn* tiUserConnect(char *srbHost, char* srbPort); DESCRIPTION Establish a connection to a srbServer through the srbMaster at the specified host and port by a TICKET USER. Normal authentication will be bypassed for a TICKET USER.

SrbHost

The host address of srbMaster. If the input value in NULL, it will use the env variable "srbHost" if it is defined. If it is not defined, the ~/.srb/.MdasEnv file will be checked next. If not, it will use the hostname of the client machine.

SrbPort

The port number of srbMaster. If the input value in NULL, it will use the env variable "srbPort" if it is defined. If not, it defaults to the default port 5558.

RETURN VALUES Returns a srbConn* which is needed for all subsequent client calls. Error if the status field of the connection returned is CONNECTION_BAD. ERRORS CONNECTION_BAD in the status field of srbConn. SEE ALSO [#srbConnect srbConnect], [#clFinish clFinish] and [#clErrorMessage clErrorMessage]. [#Appendix A Top of Client API Table] NAME clFinish SYNOPSIS #include "srbClient.h" void clFinish (srbConn* conn); DESCRIPTION Close the current connection and free the srbConn data structure.

Conn

The connect to close.

RETURN VALUES None. ERRORS None. SEE ALSO [#srbConnect srbConnect], [#tiUserConnect tiUserConnect] and [#clErrorMessage clErrorMessage]. [#Appendix A Top of Client API Table]

 NAME clErrorMessage SYNOPSIS  

#include "srbClient.h" char* clErrorMessage(srbConn* conn); DESCRIPTION Return the ErrorMessage of a connection. This is the error message from the current client call returned by the SRB server. On encountering error on most client calls, in addition to returning an error code (usually a negative value), a text string describing the error is returned to the caller. The caller must use the clErrorMessage() call to retrieve the error message.

Conn

From the clConnect() call.

RETURN VALUES Returns the pointer to the error message string. Returns a NULL if there is no error message. ERRORS SEE ALSO [#srbConnect srbConnect], [#tiUserConnect tiUserConnect] and [#clFinish clFinish]. [#Appendix A Top of Client API Table]

srbObjOpen

 NAME srbObjOpen SYNOPSIS  

#include "srbClient.h" int srbObjOpen(srbConn* conn, char *objID, int oflag, char *collectionName); DESCRIPTION Open a SRB data object for I/O operation.

Conn

From clConnect call.

ObjID

The SRB object ID to open. The objID to be opened must have already been registered with MCAT (through srbObjCreate call or by explicit registration). One or more conditions can be appended to the objID. Each condition must be preceded by the '&' character. Currently, only one condition is supported. i.e., COPY=n (where n = replica number beginning with 0). e.g. foo&COPY=1 specifies opening replica number 1 of data object "foo".

oflag

Unix type open flag. O_CREAT is not supported.

collectionName

The name of the collection this objID belongs.

RETURN VALUES

Returns the object descriptor. Returns a negative value upon failure.

ERRORS SEE ALSO

[#srbObjOpenWithTicket srbObjOpenWithTicket] and [#srbObjClose srbObjClose].

[#Appendix A Top of Client API Table]

 NAME srbObjOpenWithTicket SYNOPSIS  

#include "srbClient.h"

int srbObjOpenWithTicket (srbConn* conn, char *objID, int oflag,

char *collectionName, char *ticket);

DESCRIPTION

Open a SRB data object using a ticket.

Conn

From clConnect call.

ObjID

The SRB object ID to open. The objID to be opened must have already been registered with MCAT (through srbObjCreate call or by explicit registration). One or more conditions can be appended to the objID. Each condition must be preceded by the '&' character. Currently, only one condition is supported. i.e., COPY=n (where n = replica number beginning with 0). e.g. foo&COPY=1 specifies opening replica number 1 of data object "foo".

Oflag

Unix type open flag. O_CREAT is not supported.

collectionName

The name of the collection this objIDbelongs.

Ticket

The ticket for the object.

RETURN VALUES

Returns the object descriptor. Returns a negative value upon failure.

ERRORS SEE ALSO

[#srbObjOpen srbObjOpen] and [#srbObjClose srbObjClose].

[#Appendix A Top of Client API Table]

 NAME srbObjCreate SYNOPSIS  

#include "srbClient.h"

int srbObjCreate(srbConn* conn, int catType, char *objID,

char *dataTypeName, char *resourceName, char *collectionName,

char *pathName, int dataSize);

 DESCRIPTION  

Create a SRB data object.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

ObjID

The SRB object ID to create. The objID is a user-defined name to be registered with MCAT. This ID will be used for subsequent reference of the data object. One or more conditions can be appended to the objID. Each condition must be preceded by the '&' character. Currently, two conditions are supported:

1) COPIES=MMM where MMM may be:

a) an integer n which means n replica should be created. The "resourceName" input is the logical resource in which this object is to be stored. This logical resource must consist of at least n physical resources. e.g. foo&COPIES=2 specifies the creation of two replica of data object "foo".

b) the keyword RR which means a single copy should be created in one of the physical resources belonging to the input logical resource ("resourceName") chosen in a Round-Robin fashion. e.g. foo&COPIES=RR.

c) the keyword RANDOM produces similar effect as the RR keyword. The only difference is the selection algorithm is random rather than Round-Robin. e.g. foo&COPIES=RANDOM.

2) CONTAINER=containerName. This keyword specifies the object is to be placed in the given container. The container must have already been created using the srbContainerCreate() call.

dataTypeName

Data type. e.g. "generic"

resourceName

The storage resource name. This may be the name of a single resource or a resource group (or logical resource) consisting of two or more physical resources. e.g. "mda18-unix-sdsc"

collectionName

The collection name.

PathName

The file/DB path of the data. If the input is NULL, the SRB server will generate one.

dataSize

The size of the data set if known. 0 = unknown.

RETURN VALUES

Returns the object descriptor. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjUnlink srbObjUnlink], [#srbContainerCreate srbContainerCreate].

[#Appendix A Top of Client API Table]

 NAME srbObjClose SYNOPSIS  

#include "srbClient.h"

int srbObjClose (srbConn* conn, int desc);

DESCRIPTION

Close an opened data object.

Conn

From clConnect call.

Desc

The object descriptor (from the srbObjOpen call) to close.

RETURN VALUES

Returns 0 upon success. Returns a negative value upon failure.

ERRORS SEE ALSO

[#srbObjOpen srbObjOpen] and [#srbObjOpenWithTicket srbObjOpenWithTicket].

[#Appendix A Top of Client API Table]

 NAME srbObjUnlink SYNOPSIS  

#include "srbClient.h"

int srbObjUnlink (srbConn* conn, char *objID, char *collectionName);

DESCRIPTION

Delete a SRB data object.

Conn

From clConnect call.

ObjID

The SRB object ID to unlink.

collectionName

The name of the collection this objID belongs.

RETURN VALUES

Returns 0 upon success. Returns a negative value upon failure.

ERRORS SEE ALSO

[#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME  

srbObjRead

SYNOPSIS

1. include "srbClient.h"

int srbObjRead(srbConn *conn, int desc, char *buf, int len);

DESCRIPTION

Read len bytes of the SRB data object into buf. The caller must have allocated enough space to hold the data read.

Conn

From clConnect call.

Desc

The object descriptor (from a srbObjOpen call) to read.

Buf

The input buffer.

Len

The number of bytes to read.

RETURN VALUES

Returns the length of bytes read. Returns a negative value upon failure.

ERRORS

SEE ALSO [#srbObjOpen srbObjOpen]and [#srbObjWrite srbObjWrite]

[#Appendix A Top of Client API Table]

 NAME  

srbObjSeek

SYNOPSIS

#include "srbClient.h"

int srbObjSeek(srbConn *conn, int desc, int offset, int whence);

DESCRIPTION

Change the current read or write location on an opened SRB data object.

Conn

From clConnect call.

Desc

The object descriptor (from the srbObjOpen call) to seek.

Offset

The position of the next operation.

Whence

Same definition as in Unix.

SEEK_SET - pointer is set to the value of the Offset parameter. SEEK_CUR - pointer is set to its current location plus the value of the Offset parameter. SEEK_END - pointer is set to the size of the file plus the value of the Offset parameter.

RETURN VALUES

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjOpen srbObjOpen], [#srbObjWrite srbObjWrite] and [#srbObjRead srbObjRead].

[#Appendix A Top of Client API Table]

 NAME srbObjSync SYNOPSIS  

#include "srbClient.h"

int srbObjSync(srbConn* conn, int desc);

DESCRIPTION

Sync a SRB object.

Conn

From clConnect call.

Desc

The SRB object descriptor to sync (from srbObjOpen or srbObjCreate).

RETURN VALUES

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjOpen srbObjOpen], [#srbObjCreate srbObjCreate], [#srbObjUnlink srbObjUnlink], [#srbObjClose srbObjClose], [#srbObjRead srbObjRead] and [#srbObjWrite srbObjWrite].

[#Appendix A Top of Client API Table]

 NAME srbObjStat SYNOPSIS  

#include "srbClient.h"

int srbObjStat(srbConn* conn, int catType,

char *path, struct stat *statbuf);

DESCRIPTION

Get the status of an SRB object. The result is placed in statbuf.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

path

The full Path name of the SRB object to stat. The path must be an absolute path.

Statbuf

Pointer to a user-supplied local FS stat struct where the stat result will be put.

RETURN VALUES

Stat result in statbuf.

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjStat64 srbObjStat64], [#srbObjOpen srbObjOpen] and [#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME srbObjStat64 SYNOPSIS  

#include "srbClient.h"

int srbObjStat64 (srbConn* conn, int catType,

char *path, struct stat64 *statbuf);

DESCRIPTION

Get the status of an SRB object. The result is placed in statbuf.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

path

The full Path name of the SRB object to stat. The path must be an absolute path.

Statbuf

Pointer to a user-supplied local FS stat struct where the stat result will be put.

RETURN VALUES

Stat result in statbuf.

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjStat srbObjStat], [#srbObjOpen srbObjOpen] and [#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME srbObjGetdents SYNOPSIS  

#include "srbClient.h"

int srbObjGetdents(srbConn* conn, int catType,

int fd, dirent_t *buf, size_t nbyte);

DESCRIPTION

The SRB equivalent of the UNIX getdents call. The function attempts to read "nbyte" bytes from the collection associated with the descriptor "fd" and to format them as file system independent directory entries in the buffer pointed to by buf. Since the collection entries are of variable lengths, in most cases the actual number of bytes returned will be less than "nbyte".

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

Fd

The descriptor of the opened collection from the srbObjOpen() call.

Buf

Pointer to a user-supplied local FS dirent_t struct where the getdents result will be put.

Nbyte

The maximum number of bytes to output to buf.

RETURN VALUES

Getdents result in buf.

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjOpen srbObjOpen], [#srbObjGetdents64 srbObjGetdents64] and [#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME srbObjGetdents64 SYNOPSIS  

#include "srbClient.h"

int srbObjGetdents64(srbConn* conn, int catType,

int fd, dirent64_t *buf, size_t nbyte);

DESCRIPTION

The SRB equivalent of the UNIX getdents64 call which is the same as srbObjGetdents except the results are given in dirent64_t instead of dirent_t. The function attempts to read "nbyte" bytes from the collection associated with the descriptor "fd" and to format them as file system independent directory entries in the buffer pointed to by buf. Since the collection entries are of variable lengths, in most cases the actual number of bytes returned will be less than "nbyte".

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

Fd

The descriptor of the opened collection from the srbObjOpen() call.

Buf

Pointer to a user-supplied local FS dirent64_t struct where the getdents64 result will be put.

Nbyte

The maximum number of bytes to output to buf.

RETURN VALUES

Getdents64 result in buf.

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjOpen srbObjOpen], [#srbObjGetdents srbObjGetdents] and [#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME srbObjProxyOpr SYNOPSIS  

#include "srbClient.h"

int srbObjProxyOpr (srbConn *conn, ProxyOprId operation,

char *inputStr1, char *inputStr2);

DESCRIPTION

Perform a proxy Operation. Some operations can be more efficiently done by the SRB server without much involvement by the client. An example is the copy operation where it is more efficient for the server to do all the read and write operations on behalf of the client than passing the data read to the client and then for the client passing it back to the server for the write operation. A general framework for handling proxy operations has been set up to facilitate the building of new proxy functions. The input of the API consists of a ProxyOprId which identifies the type of proxy operation to be carried out and two input strings. The current implementation supports only one type of proxy operation, i.e., the "Copy" operation. Additional proxy operations can be implemented within this framework.

Conn

From clConnect call.

Operation

The type of proxy operation. Valid operations:

OPR_COPY

Copy from the object descriptor given in InputStr1 to the object descriptor given in inputStr2. If successful, the number of bytes copied is returned. A negative value means failure. Normally, InputStr1 contains the object descriptor obtained from a srbObjOpen() call and inputStr2 contains the object descriptor obtained from a srbobjCreate call.

InputStr1

Input String 1.

InputStr2

Input String 2.

RETURN VALUES

Returns 0 or a positive value upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjReplicate srbObjReplicate], [#srbObjMove srbObjMove], [#srbObjOpen srbObjOpen] and [#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME srbExecCommand SYNOPSIS  

#include "srbClient.h"

int srbExecCommand (srbConn *conn, char *command,

char *commandArgv, char *proxyAddr, int portalFlag);

DESCRIPTION

This is a special case of proxy operation. It performs the remote execution of arbitrary commands(executables) installed in a specific predefined directory on the remote host. Currently, this predefined directory is hard-coded as "commands" in the directory where the srbMaster and srbServer executables are installed. For example, if the srbMaster is installed in the /usr/local/srb/bin directory, the proxy commands should be installed in the /usr/local/srb/bin/commands directory.

The input argument "command" specifies the proxy command to be executed. Input arguments for the command is specified with the "commandArgv" argument. The argument "proxyAddr" specifies the host address where the proxy command is to be executed. If no address is specified, the default is the host where the client is connected to.

The input argument "portalFlag" specifies the mode of communication between the proxy command and the client. Valid values are PORTAL_OFF, PORTAL_ON and PORTAL_STD_IN_OUT. A value of PORTAL_OFF means there will be no communication between the proxy command and the client. PORTAL_ON means a socket will be created between the proxy command and the client. This call returns the descriptor of the socket which can be used by the client to communicate with the proxy command. On the server side, the socket descriptor is passed onto the proxy command through the environment variable defined by PORTAL_ENV. The proxy command can use this socket to communicate with the client. A value of PORTAL_STD_IN_OUT has a similar effect as PORTAL_ON except on the server side, this socket is now associated with the stdin, stdout and stderr of the proxy command. i.e., all stdout and stderr of the proxy command will be sent to the client through this socket and the client can use this socket to send messages to the stdin of the proxy command.

Conn

From clConnect call.

command

the proxy command to be executed.

commandArgv

Input arguments for the proxy command.

proxyAddr

the host address where the proxy command is to be executed. A NULL value means on the host where the client is currently connected to.

portalFlag

The portal flag. Valid flags are - PORTAL_OFF, PORTAL_ON and PORTAL_STD_IN_OUT.

RETURN VALUES

Upon success, returns 0 if the "portalFlag" is PORTAL_OFF, and the portal socket descriptor if the "portalFlag" is PORTAL_ON or PORTAL_STD_IN_OUT. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjReplicate srbObjReplicate], [#srbObjMove srbObjMove], [#srbObjOpen srbObjOpen] and [#srbObjCreate srbObjCreate].

[#Appendix A Top of Client API Table]

 NAME  

srbObjReplicate

SYNOPSIS

#include "srbClient.h"

int srbObjReplicate (srbConn* conn, int catType, char *objID,

char *collectionName, char *newResourceName, char *newPathName);

DESCRIPTION

Replicate a SRB data object.

Conn

From clConnect call.

CatType

catalog type. e,g., MDAS_CATALOG.

ObjID

The SRB object ID to replicate.

collectionName

The name of the collection this objID belongs.

newResourceName

The storage resource name of the new copy. e.g. "mda18-unix-sdsc"

newPathName

The file/DB path of the new copy. If the input is NULL, the SRB server will generate one for the client.

RETURN VALUES

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbSyncData" srbSyncData], [#srbObjMove srbObjMove] and [#srbObjProxyOpr srbObjProxyOpr].

[#Appendix A Top of Client API Table]

 NAME srbObjMove SYNOPSIS  

#include "srbClient.h"

int srbObjMove (srbConn* conn, int catType, char *objID, char *collectionName,

char *newResourceName, char *newPathName);

DESCRIPTION

Move a copy of an SRB object to a new location.

Conn

From clConnect call.

CatType

catalog type. e,g., MDAS_CATALOG.

ObjID

The SRB object ID to move.

collectionName

The name of the collection this objID belongs.

newResourceName

The storage resource name of the new copy. e.g. "mda18-unix-sdsc"

newPathName

The file/DB path of the new copy. If the input is NULL, the SRB server will generate one for the client.

RETURN VALUES

Returns 0 upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjReplicate srbObjReplicate] and [#srbObjProxyOpr srbObjProxyOpr].

[#Appendix A Top of Client API Table]

 NAME  

srbObjWrite

SYNOPSIS

#include "srbClient.h"

int srbObjWrite(srbConn *conn, int desc, char *buf, int len);

DESCRIPTION

Write len bytes of buf into the Object fd

Conn

From clConnect call.

Desc

The Object descriptor to write (from svrObjOpen or svrObjCreate).

Buf

The output buffer.

Len

The length to write.

RETURN VALUES

Returns the number of bytes written. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbObjOpen srbObjOpen], [#srbObjCreate srbObjCreate] and [#srbObjRead srbObjRead].

[#Appendix A Top of Client API Table]

 NAME  

srbCreateCollect

SYNOPSIS

#include "srbClient.h"

int srbCreateCollect (srbConn* conn, int catType, char *parentCollect,

char *newCollect);

DESCRIPTION Create a new collect.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

ParentCollect

The parent collection in which to create the new collection.

newCollect

The name of the collection to create.

RETURN VALUES

Returns 0 - success. Returns negative - failure.

ERRORS

SEE ALSO

[#srbModifyCollect srbModifyCollect] and [#srbListCollect srbListCollect].

[#Appendix A Top of Client API Table]

 NAME  

srbListCollect

SYNOPSIS

#include "srbClient.h"

int srbListCollect (srbConn* conn, int catType, char *collectionName,

char *flag, mdasC_sql_result_struct *listResult, int rowsWanted);

DESCRIPTION

List the content of a SRB collection.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

CollectionName

The collection to list.

Flag

The list flag. "C" - non-recursive. "R" – recursive.

ListResult

A pointer to a user supplied mdasC_sql_result_struct. This is where the result of the srbListCollect operation will be put.

RETURN VALUES

Returns 0 - success. Returns negative - failure.

ERRORS

SEE ALSO

[#srbObjCreate srbObjCreate] and [#srbModifyCollect srbModifyCollect].

[#Appendix A Top of Client API Table]

 NAME  

srbModifyCollect

SYNOPSIS

#include "srbClient.h"

int srbModifyCollect (srbConn* conn, int catType, char *collectionName,

char *dataValue1, char *dataValue2, char *dataValue3, int retractionType);

DESCRIPTION

Modify a SRB collection.

Conn

From clConnect call.

CatType

catalog type. e,g., MDAS_CATALOG.

collectionName

The name of the collection this objID belongs.

dataValue1

Input value 1.

dataValue2

Input value 2.

dataValue3

Input value 3.

retractionType

The type of retraction. See srbC_mdas_externs.h for the retractionType definition.

RETURN VALUES

Returns 0 - success. Returns negative value - failure.

ERRORS

SEE ALSO

[#srbObjCreate srbObjCreate], [#srbListCollect srbListCollect].

[#Appendix A Top of Client API Table]

 NAME  

srbIssueTicket

SYNOPSIS

#include "srbClient.h"

int srbIssueTicket (srbConn* conn, char *objID, char *collectionName,

char *collectionFlag, char *beginTime, char *endTime, int accessCnt,

char *ticketUser, char **ticket);

DESCRIPTION

Issue a ticket for a SRB data object or collection.

Conn

From clConnect call.

ObjID

The data object ID. NULL if the ticket is for a collection.

collectionName

The collection name. NULL if the ticket is for a data object.

collectionFlag

The collect flag if CollectionName is non NULL. "R" - the ticket is for all dataset and sub-collection recursively. "D" - the ticket is for the datasets directly beneath the colle