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

BeginTime

The beginning time when the ticket becomes effective. A NULL means no time limit.

EndTime

The ending time of the ticket.

AccessCnt

The number of time the ticket can be used to access the dataset.

TicketUser

The user/userGroup that will use the ticket. Multiply users can be specified with the following format:

user1@domain1&user2@domain2 .... If it is NULL, => all users.

Ticket

The address to put the output ticket.

RETURN VALUES

Returns 0 - success. Returns negative - failure.

ERRORS

SEE ALSO

[#srbRemoveTicket srbRemoveTicket].

[#Appendix A Top of Client API Table]

 NAME  

srbRemoveTicket

SYNOPSIS

#include "srbClient.h"

int srbRemoveTicket (srbConn* conn, char *ticket);

DESCRIPTION

Cancel a ticket.

Conn

From clConnect call.

Ticket

The ticket to remove.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbIssueTicket srbIssueTicket].

[#Appendix A Top of Client API Table]

 NAME  

srbContainerCreate

SYNOPSIS

#include "srbClient.h"

int srbContainerCreate (srbConn* conn, int catType, char *containerName, char *containerType, char *resourceName, int containerSize);

DESCRIPTION

Create a container with the given container name in the given logical resource. The logical resource should contain two physical resources: a "permanent" (e.g., HPSS) and a "temporary" or "cache" (e.g., UNIX disk file system) resource. Once a container has been created, the srbObjCreate() call may be used to create objects in the container using the CONATINER keyword. The normal srbObjWrite() and srbObjRead() calls can be used to perform write/read operations to the container. Internally, all I/O are done only to the "cache" copy of the container. If the "cache" copy does not exist (e.g., purged), a replicate of the "permanent" copy will be made to the "cache" resource before any I/O operation can be made. The srbSyncContainer() call is used to synchronize the "cache" copy with the permanent copy. When a container is full (max container size exceeded), the SRB server automatically renames the full container by appending a unique integer (clock in seconds) to the container name and creates a new container with the original name. This way, the client does not have to worry about filling up containers.

Conn

From clConnect call.

catType

The catalog type. e,g., MDAS_CATALOG.

containName

The name of the container to be created.

containerType

The Data type of the container. e.g. "generic".

resourceName

The storage resource name. This should be is a logical resource (resource group) consisting of two physical resources, a TEMPORARY_RES_CL and a PERMANENT_RES_CL class.

containerSize

The size of the container to be created. A zero value means the default size should be used

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbRmContainer srbRmContainer, [#srbSyncContainer srbSyncContainer, [#srbReplContainer srbReplContainer and [#srbGetContainerInfo srbGetContainerInfo].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbRmContainer

SYNOPSIS

#include "srbClient.h"

int srbRmContainer (srbConn* conn, int catType, char *containerName);

DESCRIPTION

Remove an existing container. All inContainer objects stored in the given container must be removed first before making this call

Conn

From clConnect call.

catType

catalog type. e,g., MDAS_CATALOG.

containName

The container to remove.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbContainerCreate srbContainerCreate, [#srbSyncContainer srbSyncContainer, [#srbReplContainer srbReplContainer and [#srbGetContainerInfo srbGetContainerInfo].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbSyncContainer

SYNOPSIS

#include "srbClient.h"

int srbSyncContainer (srbConn* conn, int catType, char *containerName, int syncFlag);

DESCRIPTION

Synchronize the "permanent" copies of the container with the "cache" copy. When an inContainer object is created or opened for I/O, all I/O are done only to the "cache" copy. This call allows the synchronization of different copies. Valid values of the syncFlag are PURGE_FLAG and PRIMARY_FLAG. If PURGE_FLAG is set, the "cache" copy will be purged once the copies has been synchronized. If PRIMARY_FLAG is set, synchronization is done only to the primary archival resource. The default is to synchronize all archival resources.

Conn

From clConnect call.

catType

catalog type. e,g., MDAS_CATALOG.

containName

The container to sync.

syncFlag

valid values are: PURGE_FLAG and PRIMARY_FLAG. Both can be set at the same time by ORing the 2 flags. e.g., PURGE_FLAG|PRIMARY_FLAG.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbContainerCreate srbContainerCreate, [#srbRmContainer srbRmContainer and [#srbGetContainerInfo srbGetContainerInfo].]]

[#Appendix A Top of Client API Table]

 NAME  

srbReplContainer

SYNOPSIS

#include "srbClient.h"

int srbReplContainer (srbConn* conn, int catType, char *containerName, char *resourceName);

DESCRIPTION

Replicate or stage a copy of a container onto the specified physical resource. The specified physical resource must be a member of the logical resource associated with the container. The srbSyncContainer() call can be used to replicate copies to either the primary archival resource or to all resources, but not to a specific non-primary resource. This call can be used to synchronize a container to a specific non-primary archival resource or stage a container to a specific non-primary cache resource.

Conn

From clConnect call.

catType

catalog type. e,g., MDAS_CATALOG.

containerName

The name of the container to replicate.

resourceName

The physical resource to replicate to.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbContainerCreate srbContainerCreate, [#srbRmContainer srbRmContainer, [#srbSyncContainer srbSyncContainer and [#srbGetContainerInfo srbGetContainerInfo].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbObjGet

SYNOPSIS

#include "srbClient.h"

int srbObjGet (srbConn* conn, char *srcObjID, char *srcCollection, char *locFilePath);

DESCRIPTION

Download a dataset from SRB to the local file system using server-directed parallel I/O

Conn

From clConnect call.

srcObjID

The SRB file to be downloaded

srcCollection

The collection of the SRB file.

locFilePath

The local UNIX file path of the downloaded file.

RETURN VALUES

Returns: the number of bytes downloaded - success, negative - failure.

ERRORS

SEE ALSO

[#srbObjPut srbObjPut].

[#Appendix A Top of Client API Table]

 NAME  

srbObjPut

SYNOPSIS

#include "srbClient.h"

int srbObjPut (srbConn* conn, char *destObjID, char *destCollection, char *destResLoc, char *dataType, char *destPath, char *locFilePath, srb_long_t size);

DESCRIPTION

Upload a dataset from the local file system to SRB using server-directed parallel I/O

Conn

From clConnect call.

destObjID

The SRB file name of the uploaded file.

destCollection

The SRB collection of the uploaded file.

destResLoc

The destination resource.

dataType

Data type. e.g. "generic".

destPath

The UNIX file path of the uploaded file. If the input is NULL, the SRB server will generate one.

locFilePath

The UNIX file path of the local file to be uploaded..

size

The size of the file being uploaded.

RETURN VALUES

Returns: the number of bytes uploaded - success, negative - failure.

ERRORS

SEE ALSO

[#srbObjGet srbObjGet].

[#Appendix A Top of Client API Table]

 NAME  

srbSyncData

SYNOPSIS

#include "srbClient.h"

int srbSyncData (srbConn* conn, int catType, char *objID, char *collectionName, char *resource);

DESCRIPTION

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

Conn

From clConnect call.

catType

catalog type. e,g., MDAS_CATALOG.

objID

The SRB file to be synchronized.

collectionName

The collection of the SRB file to be synchronized.

resource

The resource for the object to synchronize to. A NULL or empty string means synchronize the existing copies with the most recently modified version.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbObjReplicate srbObjReplicate].

[#Appendix A Top of Client API Table]

 NAME  

srbGetContainerInfo

SYNOPSIS

#include "srbClient.h"

int srbGetContainerInfo (srbConn* conn, int catType, char *containerName, mdasC_sql_result_struct *myresult, int rowsWanted);

DESCRIPTION

Query the metadata associated with a container.

Conn

From clConnect call.

catType

catalog type. e,g., MDAS_CATALOG.

containName

The container to query.

Myresult

A pointer to a user supplied mdasC_sql_result_struct where result of the query will be placed.

RowsWanted

The number of rows to be returned.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbContainerCreate srbContainerCreate, [#srbRmContainer srbRmContainer and [#srbSyncContainer srbSyncContainer].]]

[#Appendix A Top of Client API Table]

 NAME  

srbRegisterLocation

SYNOPSIS

#include "srbClient.h"

int srbRegisterLocation(srbConn* conn, char *locName, char *fullAddr, char *parentLoc, char *serverUser, char *serverUserDomain);

DESCRIPTION

Register location information

conn

From clConnect call.

locName

The location name.

fullAddr

Full Address.

parentLoc

Parent location.

serverUser

Server User.

serverUserDomain

Server User Domain.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbIngestToken srbIngestToken, [#srbRegisterResource srbRegisterResource, [#srbRegisterLogicalResource srbRegisterLogicalResource, [#srbRegisterReplicateResourceInfo srbRegisterReplicateResourceInfo], and [#srbDeleteValue srbDeleteValue].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbIngestToken

SYNOPSIS

#include "srbClient.h"

int srbIngestToken(srbConn* conn, char *typeName, char *newValue, char *parentValue);

DESCRIPTION

Ingest Token

conn

From clConnect call.

typeName

The type name for the type of token being inserted.

newValue

The new token name.

parentValue

The parent token.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbRegisterLocation srbRegisterLocation, [#srbRegisterResource srbRegisterResource, [#srbRegisterLogicalResource srbRegisterLogicalResource, [#srbRegisterReplicateResourceInfo srbRegisterReplicateResourceInfo], and [#srbDeleteValue srbDeleteValue].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbRegisterResource

SYNOPSIS

#include "srbClient.h"

int srbRegisterResource(srbConn* conn, char *rescName, char *rescType, char *location, char *phyPath, char *class, int size);

DESCRIPTION

Register/create a new resource (physical or compound)

conn

From clConnect call.

rescName

The resource name.

rescType

Resource type.

location

The location of the new resource.

phyPath

The default physical path.

class

The resource class.

size

The maximum object size in the resource.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbRegisterLocation srbRegisterLocation, [#srbIngestToken srbIngestToken, [#srbRegisterLogicalResource srbRegisterLogicalResource, [#srbRegisterReplicateResourceInfo srbRegisterReplicateResourceInfo], and [#srbDeleteValue srbDeleteValue].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbRegisterLogicalResource

SYNOPSIS

#include "srbClient.h"

int srbRegisterLogicalResource(srbConn* conn, char *rescName, char *rescType, char *phyResc, char *phyPath);

DESCRIPTION

Register/create a new logical resource

conn

From clConnect call.

rescName

The resource name.

rescType

Resource type.

phyResc

The physical resource that is part of this logical resource.

phyPath

The default physical path.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbRegisterLocation srbRegisterLocation, [#srbIngestToken srbIngestToken, [#srbRegisterResource srbRegisterResource, [#srbRegisterReplicateResourceInfo srbRegisterReplicateResourceInfo], and [#srbDeleteValue srbDeleteValue].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbRegisterReplicateResourceInfo

SYNOPSIS

#include "srbClient.h"

int srbRegisterReplicateResourceInfo( srbConn* conn, char *physicalRescName, char *rescType, char *oldLogicalRescName, char *indefaultPath);

DESCRIPTION

Add another physical resource to a logical or compound resource

conn

From clConnect call.

physicalRescName

The physical resource name.

rescType

Resource type.

oldLogicalRescName

The existing logical or compound resource name.

indefaultPath

The default path.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbRegisterLocation srbRegisterLocation, [#srbIngestToken srbIngestToken, [#srbRegisterResource srbRegisterResource, [#srbRegisterLogicalResource srbRegisterLogicalResource], and [#srbDeleteValue srbDeleteValue].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbDeleteValue

SYNOPSIS

#include "srbClient.h"

int srbDeleteValue(srbConn* conn, int valueType, char *deleteValue);

DESCRIPTION

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

conn

From clConnect call.

valueType

the value (token) type.

deleteValue

The value (name) that is being deleted.

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbRegisterLocation srbRegisterLocation, [#srbIngestToken srbIngestToken, [#srbRegisterResource srbRegisterResource, [#srbRegisterLogicalResource srbRegisterLogicalResource], and [#srbRegisterReplicateResourceInfo srbRegisterReplicateResourceInfo].]]]

[#Appendix A Top of Client API Table]

 NAME  

srbSetupSessionPublicKey

SYNOPSIS

#include "srbClient.h"

int srbSetupSessionPublicKey (srbConn *conn, char *publicKey);

DESCRIPTION

Get the MCAT-enabled server's public key in preparation for transferring encryptioned information. Also see the sscSetupSessionPublicKey library routine.

conn

From clConnect call.

RETURN VALUES

Returns positive - success or not-supported, negative - for some failures.

Returns a string representation of the publicKey in publicKey. If Secure Communications is not supported on the server side, an error message is returned in publicKey.

ERRORS

SEE ALSO

[#srbSetupSession srbSetupSession].

[#Appendix A Top of Client API Table]

 NAME  

srbSetupSession

SYNOPSIS

#include "srbClient.h"

int srbSetupSession (srbConn *conn, char *sessionKey);

DESCRIPTION Set up a session (for encryption) with the MCAT-enabled server. Also see the sscSetupSession library routine.

conn

From clConnect call.

sessionKey

A string representation of the session key from sscSetupSession (which is encrypted in the public key returned by srbSetupSessionPublicKey).

RETURN VALUES

Returns 0 - success, negative - failure.

ERRORS

SEE ALSO

[#srbSetupSessionPublicKey srbSetupSessionPublicKey].

[#Appendix A Top of Client API Table]

 NAME srbFileOpen SYNOPSIS  

#include "srbClient.h"

int srbFileOpen(srbConn* conn, int storSysType, char *hostAddr,

char *filename, int flags, int mode);

DESCRIPTION

Opens a file-type file.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP, 4 = HTTP.

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The file Path name to open. The path must be an absolute path.

Flags

Same definition as in unix.

Mode

Same definition as in unix.

RETURN VALUES

Returns the file descriptor for use in subsequent calls. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbFileCreate srbFileCreate], [#srbFileClose srbFileClose], [#srbFileRead srbFileRead] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table]

 NAME srbFileCreate SYNOPSIS  

#include "srbClient.h"

int srbFileCreate(srbConn* conn, int storSysType, char *hostAddr,

char *filename, int mode, int size);

DESCRIPTION

Create a File-type file.

Conn

From clConnect function.

StorSysType

Storage system type. 0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The file Path name to create. The path must be an absolute path.

Mode

Same definition as in unix.

Size

File size. Only valid for HPSS storage system type for determining the Class Of Service (COS). -1 => don't know and the default COS will be used.

RETURN VALUES

Returns the file descriptor for use in subsequent calls. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileUnlink srbFileUnlink], [#srbFileClose srbFileClose], [#srbFileRead srbFileRead] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table]

 NAME  

srbFileUnlink

SYNOPSIS

#include "srbClient.h"

int srbFileUnlink(srbConn* conn, int storSysType, char *hostAddr,

char *filename);

DESCRIPTION

Unlink a File-type file.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The file Path name to unlink. The path must be an absolute path.

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileCreate srbFileCreate], [#srbFileClose srbFileClose], [#srbFileRead srbFileRead] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table]

 NAME  

srbFileClose

SYNOPSIS

#include "srbClient.h"

int srbFileClose(srbConn* conn, int fd);

DESCRIPTION

Close a File-type file.

Conn

From clConnect call.

Fd

The file descriptor to close (from srbFileOpen or srbFileCreate).

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileCreate srbFileCreate], [#srbFileUnlink srbFileUnlink], [#srbFileRead srbFileRead] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table] NAME

srbFileRead

SYNOPSIS

#include "srbClient.h"

int srbFileRead(srbConn *conn, int fd, char *buf, int len);

DESCRIPTION

Read len bytes of the File-type file into buf. The caller must have allocated enough space to hold the data read.

Conn

From clConnect ().

Fd

The file descriptor to read (from srbFileOpen or srbFileCreate).

Buf

The input buffer.

Len

The length to read.

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileCreate srbFileCreate], [#srbFileUnlink srbFileUnlink], [#srbFileClose srbFileClose] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table]

 NAME srbFileWrite SYNOPSIS  

#include "srbClient.h"

int srbFileWrite(srbConn *conn, int fd, char *buf, int len);

DESCRIPTION

Write len bytes of buf into the File-type file fd.

Conn

From clConnect ().

Fd

The file descriptor to write (from srbFileOpen or srbFileCreate).

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

[#srbFileOpen srbFileOpen], [#srbFileCreate srbFileCreate], [#srbFileUnlink srbFileUnlink], [#srbFileClose srbFileClose], [#srbFileRead srbFileRead].

[#Appendix A Top of Client API Table]

 NAME srbFileSeek SYNOPSIS  

#include "srbClient.h"

int srbFileSeek(srbConn *conn, int fd, int offset, int whence);

DESCRIPTION

Change the current read or write location on a File-type file.

Conn

From clConnect call.

Fd

The file descriptor to seek (from srbFileOpen or srbFileCreate).

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 the resulting pointer location, measured in bytes from the beginning of the file upon success. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileCreate srbFileCreate], [#srbFileUnlink srbFileUnlink], [#srbFileClose srbFileClose], [#srbFileRead srbFileRead] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table]

 NAME srbFileSync SYNOPSIS  

#include "srbClient.h"

int srbFileSync(srbConn* conn, int fd);

DESCRIPTION

Sync a File-type file.

Conn

From clConnect call.

Fd

The file descriptor to sync (from srbFileOpen or srbFileCreate).

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileCreate srbFileCreate], [#srbFileUnlink srbFileUnlink], [#srbFileClose srbFileClose], [#srbFileRead srbFileRead] and [#srbFileWrite srbFileWrite].

[#Appendix A Top of Client API Table]

 NAME srbFileStat SYNOPSIS  

#include "srbClient.h"

int srbFileStat(srbConn* conn, int storSysType, char *hostAddr,

char *filename, struct srbStat *statbuf);

DESCRIPTION

Get the status of a File-type file.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The file Path name to stat. The path must be an absolute path.

Statbuf

Pointer to a user-supplied srbStat struct where the stat result is put.

RETURN VALUES

Stat result in statbuf.

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

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen] and [#srbFileCreate srbFileCreate].

[#Appendix A Top of Client API Table]

 NAME srbFileFstat SYNOPSIS  

#include "srbClient.h"

int srbFileFstat(srbConn* conn, int storSysType, char *hostAddr,

int fd, struct srbStat *statbuf);

DESCRIPTION

Get the status of a File-type file.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Fd

The file descriptor to stat (from srbFileOpen or srbFileCreate).

Statbuf

Pointer to a user-supplied srbStat struct where the stat result is put.

RETURN VALUES

Stat result in statbuf.

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

ERRORS

SEE ALSO

[#srbFileOpen srbFileOpen], [#srbFileStat srbFileStat] and [#srbFileCreate srbFileCreate].

[#Appendix A Top of Client API Table]

 NAME srbFileMkdir SYNOPSIS  

#include "srbClient.h"

int srbFileMkdir(srbConn* conn, int storSysType, char *hostAddr,

char *filename, int mode);

DESCRIPTION

Create a new file-type directory.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The Path name of the new directory. The path must be an absolute path.

Mode

Same definition as in Unix.

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbFileRmdir srbFileRmdir].

[#Appendix A Top of Client API Table]

 NAME  

srbFileChmod

SYNOPSIS

#include "srbClient.h"

int srbFileChmod(srbConn* conn, int storSysType, char *hostAddr,

char *filename, int mode);

DESCRIPTION

Change the mode of a file-type file or directory.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The Path name of the file or directory. The path must be an absolute path.

Mode

Same definition as in Unix.

RETURN VALUES

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

ERRORS

SEE ALSO [#Appendix A Top of Client API Table] NAME srbFileRmdir SYNOPSIS

#include "srbClient.h"

int srbFileRmdir(srbConn* conn, int storSysType, char *hostAddr,

char *filename);

DESCRIPTION

Remove a file-type directory.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The SRB Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Filename

The Path name of the directory to remove. The path must be an absolute path.

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbFileMkdir srbFileMkdir].

[#Appendix A Top of Client API Table]

 NAME srbSetStorAttri SYNOPSIS  

#include "srbClient.h"

int srbSetStorAttri(srbConn* conn, int storSysType,

char *hostAddr, char *userAuth, char *dirPath);

DESCRIPTION

Set Attributes for a Storage System. Currently only defined for FTP files, connects to an FTP Server and/or sets the current directory.

Conn

From clConnect call.

StorSysType

Storage system type.

3 = FTP. Currently only defined for FTP.

HostAddr

The FTP Server address followed by optional ":" and port, eg "ftp.sdsc.edu:21"

UserAuth

The User id and optional password, eg "anonymous:schroede@sdsc.edu"

DirPath

Directory to change to (cd) (dirPath or vaultAddr may be null to leave unchanged, if both are null the SRB will disconnect from the ftp server (gracefully logout))

RETURN VALUES

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

ERRORS

SEE ALSO

[#Appendix A Top of Client API Table]

 NAME srbOpendir SYNOPSIS  

#include "srbClient.h"

int srbOpendir(srbConn* conn, int storSysType, char *hostAddr, char *dirname);

DESCRIPTION

Open a file-type directory.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = Unix, 1 = UniTree, 2 = HPSS, 3 = FTP (not supported for HTTP).

HostAddr

The FTP Server address followed by optional ":" and port, eg "ftp.sdsc.edu:5556"

Dirname

The dir Path name to open. The path must be an absolute path.

RETURN VALUES

Returns the file descriptor for use in subsequent client calls. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbClosedir srbClosedir] and [#srbReaddir srbReaddir].

[#Appendix A Top of Client API Table]

 NAME  

srbClosedir

SYNOPSIS

#include "srbClient.h"

extern int srbClosedir(srbConn* conn, int fd);

DESCRIPTION

Close an opened file-type directory.

Conn

From clConnect ().

Fd

The file directory descriptor to close (from srbOpendir).

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbOpendir srbOpendir] and [#srbReaddir srbReaddir].

[#Appendix A Top of Client API Table]

 NAME  

srbReaddir

SYNOPSIS

#include "srbClient.h"

struct srbDirent *srbReaddir(srbConn* conn, int dirDesc);

DESCRIPTION

Read a file-type directory entry.

Conn

From clConnect call.

Fd

The file descriptor to read (from srbOpendir)

RETURN VALUES

A pointer to struct srbDirent - The dirent read.

ERRORS

SEE ALSO

[#srbOpendir srbOpendir] and [#srbClosedir srbClosedir].

[#Appendix A Top of Client API Table]

 NAME srbDbLobjOpen SYNOPSIS  

#include "srbClient.h"

int srbDbLobjOpen(srbConn* conn, int storSysType,

char *resourceLoc, char *dataPath, int flags, int mode);

DESCRIPTION

Open a DB Large Object.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = DB2, 1 = Illustra, 5 = Oracle.

ResourceLoc

Resource location. Format : host:database:instance.

DataPath

Data path. Format : /tablename/objectID. If only the objectID is given, the tablename will default to "/srbVault".

Flags

Same definition as in unix.

Mode

Not currently used.

RETURN VALUES

Returns the file descriptor for use in later srbDbLobj* calls. Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjClose srbDbLobjClose], [#srbDbLobjRead srbDbLobjRead], [#srbDbLobjWrite srbDbLobjWrite] and [#srbDbLobjUnlink srbDbLobjUnlink].

[#Appendix A Top of Client API Table]

 NAME  

srbDbLobjCreate

SYNOPSIS

#include "srbClient.h"

int srbDbLobjCreate(srbConn* conn, int storSysType,

char * ResourceLoc, char *filename, int mode);

DESCRIPTION

Create a DB Large Object.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = DB2, 1 = Illustra, 5 = Oracle.

ResourceLoc

Resource location. Format : host:database:instance.

DataPath

data path. Format : /tablename/objectID. If only the objectID is given , the tablename will default to "/srbVault".

Mode

Not currently used.

RETURN VALUES

Returns the file descriptor for use in later srbDbLobj* calls.

Returns a negative value upon failure.

ERRORS

SEE ALSO

[#srbDbLobjOpen srbDbLobjOpen], [#srbDbLobjClose srbDbLobjClose], [#srbDbLobjRead srbDbLobjRead], [#srbDbLobjWrite srbDbLobjWrite] and [#srbDbLobjUnlink srbDbLobjUnlink].

[#Appendix A Top of Client API Table]

 NAME  

srbDbLobjClose

SYNOPSIS

#include "srbClient.h"

int srbDbLobjClose(srbConn* conn, int fd);

DESCRIPTION

Close an opened DB Large Object.

Conn

From clConnect call.

Fd

The dbLobj descriptor to close (from srbDbLobjOpen or srbDbLobjCreate).

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbDbLobjOpen srbDbLobjOpen], [#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjRead srbDbLobjRead], [#srbDbLobjWrite srbDbLobjWrite] and [#srbDbLobjUnlink srbDbLobjUnlink].

[#Appendix A Top of Client API Table]

 NAME srbDbLobjRead SYNOPSIS  

#include "srbClient.h"

int srbDbLobjRead(srbConn *conn, int fd, char *buf, int len);

DESCRIPTION

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

Conn

From clConnect call.

Fd

The object descriptor (from the srbDbLobjOpen 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

[#srbDbLobjOpen srbDbLobjOpen], [#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjClose srbDbLobjClose], [#srbDbLobjWrite srbDbLobjWrite] and [#srbDbLobjUnlink srbDbLobjUnlink].

[#Appendix A Top of Client API Table]

 NAME  

srbDbLobjWrite

SYNOPSIS

#include "srbClient.h"

int srbDbLobjWrite(srbConn *conn, int fd, char *buf, int len);

DESCRIPTION

Write len bytes of buf into the dbLobj fd.

Conn

From clConnect ().

Fd

The dbLobj descriptor to write (from srbDbLobjOpen or srbDbLobjCreate).

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

[#srbDbLobjOpen srbDbLobjOpen], [#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjClose srbDbLobjClose], [#srbDbLobjRead srbDbLobjRead] and [#srbDbLobjUnlink srbDbLobjUnlink].

[#Appendix A Top of Client API Table]

 NAME  

srbDbLobjSeek

SYNOPSIS

#include "srbClient.h"

int srbDbLobjSeek(srbConn *conn, int fd, int offset, int whence);

DESCRIPTION

Change the current read or write location of dbLobj.

Conn

From clConnect call.

Fd

The dbLobj descriptor (from the srbDbLobjOpen 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

[#srbDbLobjOpen srbDbLobjOpen], [#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjClose srbDbLobjClose], [#srbDbLobjRead srbDbLobjRead], [#srbDbLobjWrite srbDbLobjWrite] and [#srbDbLobjUnlink srbDbLobjUnlink].

[#Appendix A Top of Client API Table]

 NAME  

srbDbLobjUnlink

SYNOPSIS

#include "srbClient.h"

int srbDbLobjUnlink(srbConn* conn, int storSysType, char *resourceLoc,

char *dataPath);

DESCRIPTION

Unlink a DB large object.

Conn

From clConnect call.

StorSysType

Storage system type.

0 = DB2, 1 = Illustra, 5 = Oracle.

ResourceLoc

Resource location Format : host:database:instance.

DataPath

Data path. Format : tablename/objectID.

RETURN VALUES

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

ERRORS

SEE ALSO

[#srbDbLobjOpen srbDbLobjOpen], [#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjClose srbDbLobjClose], [#srbDbLobjRead srbDbLobjRead] and [#srbDbLobjWrite srbDbLobjWrite].

[#Appendix A Top of Client API Table]

NAME

srbGetDatasetInfo

SYNOPSIS

#include "srbClient.h"

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

char *collectionName, mdasC_sql_result_struct *myresult, int rowsWanted);

DESCRIPTION

Get some specific Info on a SRB data object. This call is normally used by the SRB server to check for access permission of data objects. If the permission checked out, it returns attributes such as "Resource Location", "Resource Type" and "Data Path Name" of the data object. These attributes are needed for subsequent access of the data by low-level drivers.

Conn

From clConnect call.

CatType

The catalog type - 0 = MDAS_CATALOG.

ObjID

The SRB data object ID to query.

CollectionName

The collection name.

Myresult

A pointer to a user supplied mdasC_sql_result_struct where the result of the query will be put.

RowsWanted

The number of rows of result wanted.

RETURN VALUES

Return 0 - success; myresult->continuation_index >= 0, ==> more results from the query. Use srbGetMoreRows() to retrieve more rows.

A negative value – failure.

ERRORS

SEE ALSO

[#srbGetDataDirInfo srbGetDataDirInfo] and [#srbGetMoreRows srbGetMoreRows].

[#Appendix A Top of Client API Table]

 NAME  

srbGetDataDirInfo

SYNOPSIS

#include "srbClient.h"

int srbGetDataDirInfo(srbConn* conn, int catType, char qval[][MAX_TOKEN],

int *selval, mdasC_sql_result_struct *myresult, int rowsWanted);

DESCRIPTION

This is the general API for querying the MCAT catalog. The server uses the input qval[][] and selval[] array to generate and execute SQL queries and returns the query result in myresult. The selval[] array specifies a list of attributes 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 to search. e.g., sprintf(qval[DATA_NAME],"'%s'", "unixFileObj1"); means that the search condition includes the term (data_name = "unixFileObj1").

An example of srbGetDataDirInfo:

mdasC_sql_result_struct myresult;

char qval[MAX_DCS_NUM][MAX_TOKEN];

int selval[MAX_DCS_NUM];

for (i = 0; i < MAX_DCS_NUM; i++) {

selval[i] = 0;

sprintf(qval[i],"");

}

sprintf(qval[DATA_NAME],"'%s'",argv[2]);

selval[PATH_NAME] = 1;

selval[RSRC_NAME] = 1;

.

.

if (srbGetDataDirInfo(conn, MDAS_CATALOG, qval, selval, &myresult) < 0) {

fprintf(stderr, "can't srbGetDataDirInfo \n");

exit_nicely(conn);

}

conn

From clConnect call.

CatType

The catalog type - 0 = MDAS_CATALOG

qval[][MAX_TOKEN]

A point to a user supplied char qval[MAX_DCS_NUM][MAX_TOKEN] array.

Selval

A pointer to a user supplied selval[MAX_DCS_NUM] array.

Myresult

A pointer to a user supplied mdasC_sql_result_struct where the result of the query will be put.

RowsWanted

number of rows of result wanted.

RETURN VALUES

Return 0 - success; myresult->continuation_index >= 0, ==> more results from the query. Use srbGetMoreRows() to retrieve more rows.

A negative value means failure.

ERRORS

SEE ALSO

[#srbGetMoreRows srbGetMoreRows] and [#srbGetDatasetInfo srbGetDatasetInfo].

[#Appendix A Top of Client API Table]

 NAME srbRegisterDataset SYNOPSIS  

#include "srbClient.h"

int srbRegisterDataset (srbConn* conn, int catType, char *objID, char *dataTypeName, char *resourceName, char *collectionName, char *pathName, srb_long_t dataSize);

DESCRIPTION

Register an SRB object.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

objID

The SRB data object ID.

dataTypeName

The 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 of this SRB object.

pathName

The file/DB path of the data being registered.

dataSize

The size in bytes of the data being registered.

RETURN VALUES

Returns 0 - success. A negative value - failure.

ERRORS

SEE ALSO

[#srbUnregisterDataset srbUnregisterDataset], [#srbModifyDataset srbModifyDataset] and [#srbGetDatasetInfo srbGetDatasetInfo].

[#Appendix A Top of Client API Table]

 NAME srbUnregisterDataset SYNOPSIS  

#include "srbClient.h"

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

DESCRIPTION

Unregister an SRB object.

Conn

From clConnect call.

objID

The SRB data object ID to unregister.

collectionName

The collection name of this SRB object.

RETURN VALUES

Returns 0 - success. A negative value - failure.

ERRORS

SEE ALSO

[#srbRegisterDataset srbRegisterDataset], [#srbModifyDataset srbModifyDataset] and [#srbGetDatasetInfo srbGetDatasetInfo].

[#Appendix A Top of Client API Table]

 NAME srbSetAuditTrail SYNOPSIS  

#include "srbClient.h"

int srbSetAuditTrail (srbConn* conn, int set_value);

DESCRIPTION

Set and Unset Audit Trail.

Conn

From clConnect call.

set_value

The Audit Trail value to set.

AUDIT_TRAIL_OFF - turn on audit trail. AUDIT_TRAIL_ON - turn on audit trail. GET_AUDIT_TRAIL_SETTING - return the current audit trail setting without modifying the setting.

RETURN VALUES

Returns the currently audit trail setting (after processing the latest change request).

ERRORS

SEE ALSO

[#Appendix A Top of Client API Table]

 NAME  

srbModifyDataset

SYNOPSIS

#include "srbClient.h"

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

char *collectionName, char *resourceName, char *pathName,

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

 DESCRIPTION  

Modify a SRB data object.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

ObjID

The SRB object ID to modify. The objID must already have been registered with the MCAT catalog.

collectionName

The name of the collection this objID belongs.

resourceName

The storage resource name. e.g. "mda18-unix-sdsc"

pathName

The file/DB path of the data.

dataValue1

Input value 1. See the prototype for the modify_dataset_info() function in catalog/include/mdasPrototypes.h for the definition of dataValue1, dataValue2 and retractionType.

DataValue2

Input value 2.

retractionType

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

RETURN VALUES

Returns 0 - success. Returns negative - failure.

ERRORS

SEE ALSO

[#srbGetDatasetInfo srbGetDatasetInfo] and [#srbGetDataDirInfo srbGetDataDirInfo].

[#Appendix A Top of Client API Table]

 NAME srbChkMdasAuth SYNOPSIS  

#include "srbClient.h"

int srbChkMdasAuth (srbConn* conn, char *userName, char *srbAuth,

char *mdasDomain);

DESCRIPTION

Authenticate a userName/passwd for normal access. This is a call normally used by the SRB server to authenticate a user.

Conn

From clConnect call.

userName

srbAuth

The userName/passwd pair to authenticate.

MdasDomain

The user’s Domain.

RETURN VALUES

Returns 0 – success. The user is authenticated.

Returns negative - failure.

ERRORS

SEE ALSO

[#srbChkMdasSysAuth srbChkMdasSysAuth].

[#Appendix A Top of Client API Table]

 NAME  

srbChkMdasSysAuth

SYNOPSIS

#include "srbClient.h"

int srbChkMdasSysAuth (srbConn* conn, char *userName, char *srbAuth,

char *mdasDomain);

DESCRIPTION

Authenticate a userName/passwd for sys admin access. This is a call normally used by the SRB server to authenticate a special user.

conn

From clConnect call.

userName

srbAuth

The userName/passwd pair to authenticate.

MdasDomain

The user Domain.

RETURN VALUES

Returns 0 – success. The user is authenticated.

Returns negative - failure.

ERRORS

SEE ALSO

[#srbChkMdasAuth srbChkMdasAuth].

[#Appendix A Top of Client API Table]

 NAME  

srbRegisterUserGrp

SYNOPSIS

#include "srbClient.h"

int srbRegisterUserGrp (srbConn* conn, int catType, char *userGrpName,

char *userGrpPasswd, char *userGrpType, char* userGrpAddress, char* userGrpPhone, char* userGrpEmail); DESCRIPTION

Register a user group with MCAT.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

UserGrpName

The name of the user group to register.

UserGrpPasswd

The user group passwd.

UserGrpType

The user group type. Currently, at SDSC valid userType are:

"staff", "sdsc staff", "sdsc staff scientist", "sdsc senior staff scientist", "pto staff", "ucsd staff" "student", "sdsc student", "uva student", "project", "umd student", "public", "sysadmin", " deleted".

userGrpAddress

The mailing address of the user group.

userGrpPhone

The phone number of the user group.

userGrpEmail

The Email address of the user group.

RETURN VALUES

Returns 0 - success. Returns negative - failure.

ERRORS

SEE ALSO

[#srbRegisterUser srbRegisterUser].

[#Appendix A Top of Client API Table]

 NAME  

srbRegisterUser

SYNOPSIS

#include "srbClient.h"

int srbRegisterUser (srbConn* conn, int catType, char *userName,

char *userDomain, char *userPasswd, char *userType, char* userAddress, char* userPhone, char* userEmail); DESCRIPTION

Register a user with MCAT.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

UserName

The name of the user to register.

UserDomain

The domain of the user to register.

UserPasswd

The user passwd.

UserType

The user type. Currently, at SDSC valid userType are:

"staff", "sdsc staff", "sdsc staff scientist", "sdsc senior staff scientist", "pto staff", "ucsd staff", "student", "sdsc student", "uva student", "project", "umd student", "public", "sysadmin", " deleted"

UserAddress

The mailing address of the user.

UserPhone

The phone number of the user.

UserEmail

The Email address of the user.

RETURN VALUES

Returns 0 - success. Returns negative - failure.

ERRORS

SEE ALSO

[#srbRegisterUserGrp srbRegisterUserGrp] and [#srbModifyUser srbModifyUser].

[#Appendix A Top of Client API Table]

 NAME  

srbModifyUser

SYNOPSIS

#include "srbClient.h"

int srbModifyUser (srbConn* conn, int catType, char *dataValue1,

char *dataValue2, int retractionType);

DESCRIPTION

Modify a user’s metadata.

Conn

From clConnect call.

CatType

Catalog type. e,g., MDAS_CATALOG.

dataValue1

dataValue2

retractionType

DataValue1, dataValue2 and retractionType are used to specify the user attributes to modify. A normal user may use it to modify his/her own passwd and a limited set of attributes. A user with MDAS sys admin privilege can also use these input values to modify other user's attributes. Descriptions of retractionType supported and the expected values for dataValue1 and dataValue2 can be found in mdasPrototypes.h.

RETURN VALUES

Returns 0 - success. Returns negative – failure.

ERRORS

SEE ALSO

[#srbRegisterUser srbRegisterUser].

[#Appendix A Top of Client API Table]

 NAME  

srbGetPrivUsers

SYNOPSIS

#include "srbClient.h"

int srbGetPrivUsers(srbConn *conn, int catalog,

mdasC_sql_result_struct *myresult, int rowsWanted);

DESCRIPTION

Read the privileged users list and put it in a user supplied char srbUserList[MAX_TOKEN][MAX_TOKEN].

Conn

From clConnect call.

Catalog

The catalog type. e.g., MDAS_CATALOG.

SrbUserList

A pointer to a user supplied mdasC_sql_result_struct where the result of the query will be placed.

RowsWanted

The number of rows to be returned.

RETURN VALUES

Return 0 - success; SrbUserList ->continuation_index >= 0, ==> more results from the query. Use srbGetMoreRows() to retrieve more rows.

A negative value – failure.

ERRORS

SEE ALSO [#srbGetMoreRows srbGetMoreRows].

[#Appendix A Top of Client API Table]

 NAME  

srbGetMoreRows

SYNOPSIS

#include "srbClient.h"

Int srbGetMoreRows(srbConn *conn, int catalog,

int contDesc, mdasC_sql_result_struct *myresult, int rowsWanted);

DESCRIPTION

Get more rows of result from a srbGetDatasetInfo, srbGetDataDirInfo, srbListCollect or srbGetPrivUsers call, and put the results in a user supplied mdasC_sql_result_struct.

Conn

From clConnect call.

Catalog

The catalog type. e.g., MDAS_CATALOG.

ContDesc

The continuation descriptor. This is a non negative integer returned from a srbGetDatasetInfo, srbGetDataDirInfo, srbListCollect or srbGetPrivUsers call in myresult->continuation_index.

Myresult

A pointer to a user supplied mdasC_sql_result_struct where result of the query will be placed.

RowsWanted

The number of rows to be returned.

RETURN VALUES

Returns 0 - success. Returns negative – failure.

ERRORS

SEE ALSO

[#srbGetDatasetInfo srbGetDatasetInfo], [#srbGetDataDirInfo srbGetDataDirInfo], [#srbListCollect srbListCollect] and [#srbGetPrivUsers srbGetPrivUsers].

[#Appendix A Top of Client API Table]

 NAME  

freeSqlResult

SYNOPSIS

#include "srbClient.h"

void freeSqlResult (mdasC_sql_result_struct *myresult);

DESCRIPTION

Free the content of myresult and then free myresult itself.

Myresult

The mdasC_sql_result_struct to be cleared.

RETURN VALUES

None.

ERRORS

SEE ALSO

[#clearSqlResult clearSqlResult] and [#printSqlResult printSqlResult].

[#Appendix A Top of Client API Table]

 NAME  

clearSqlResult

SYNOPSIS

#include "srbClient.h"

void clearSqlResult (mdasC_sql_result_struct *myresult);

DESCRIPTION

Clear the content of myresult. Myresult is not freed itself.

Myresult

The mdasC_sql_result_struct to be cleared.

RETURN VALUES

None

ERRORS

SEE ALSO

[#freeSqlResult freeSqlResult] and [#printSqlResult printSqlResult].

[#Appendix A Top of Client API Table]

 NAME  

printSqlResult

SYNOPSIS

#include "srbClient.h"

void printSqlResult (mdasC_sql_result_struct *myresult);

DESCRIPTION

Print the content of myresult.

Myresult

The mdasC_sql_result_struct to be printed.

RETURN VALUES

None.

ERRORS

SEE ALSO

[#freeSqlResult freeSqlResult] and [#clearSqlResult clearSqlResult].

[#Appendix A Top of Client API Table]

 NAME srb_perror SYNOPSIS  

#include "srbClient.h"

void srb_perror(int fd, int error_id, char *error_mnenomic, int flags);

DESCRIPTION

Print an SRB error message corresponding to the SRB error referred to by or (if non-null). If both and are passed, will take precedence. The message is emitted to the file descriptor referred to by . If is invalid, the error will be emitted to the stderr (fd 2). Optional behavior of srb_perror is controlled by the parameter.

fd

The file description to which the message should be emitted. If fd is invalid, the message will be emitted to stderr.

error_id

A SRB error id from the SRB error message table contained within srb_error.h. If the error id is invalid, the error SRB_NO_ERROR will be emitted.

error_mnenomic

A SRB error mnenomic from the SRB error message table contained within srb_error.h. If the error_mnenomic is invalid, the error SRB_NO_ERROR will be emitted.

flags

Contains the OR'ed value of the flags. SRB_LONG_MSG = Emit the SRB error long message. SRB_RCMD_ACTION = Emit the SRB recommended action.

RETURN VALUES

None.

ERRORS

SEE ALSO

[#clErrorMessage clErrorMessage].

[#Appendix A Top of Client API Table]

 NAME srbVaultInfo SYNOPSIS  

#include "srbClient.h"

struct vaultQueElement *srbVaultInfo(srbConn* conn);

DESCRIPTION

Get Info on the SRB storage vault of a SRB server. The output is the head element of a link list of struct vaultQueElement. This call basically returns the content of the data/vaultConfig file.

Conn

From clConnect call.

' RETURN VALUES A pointer to the vaultQueElement struct. This is the head of a link list of struct vaultQueElement. A NULL return means no result. ERRORS SEE ALSO [#srbFreeVaultInfo srbFreeVaultInfo] and [#srbPrintVaultInfo srbPrintVaultInfo]. [#Appendix A Top of Client API Table]

 NAME  

srbFreeVaultInfo SYNOPSIS #include "srbClient.h" void srbFreeVaultInfo(struct vaultQueElement *vaultQueHead); DESCRIPTION Free the memory taken by the vaultQueElement link list obtained from a vaultInfo call.

VaultQueHead

The head of the link list to be freed.

RETURN VALUES None. ERRORS SEE ALSO [#srbVaultInfo srbVaultInfo] and [#srbPrintVaultInfo srbPrintVaultInfo]. [#Appendix A Top of Client API Table]

 NAME  

srbPrintVaultInfo SYNOPSIS #include "srbClient.h" void srbPrintVaultInfo(struct vaultQueElement *vaultQueHead); DESCRIPTION Print the info represented by the vaultQueElement link list obtained from a vaultInfo call.

VaultQueHead

The head of the vaultQueElement link list to be printed.

RETURN VALUES None. ERRORS SEE ALSO [#srbVaultInfo srbVaultInfo] and [#srbFreeVaultInfo srbFreeVaultInfo]. [#Appendix A Top of Client API Table]

 NAME  

srbHostConfig SYNOPSIS #include "srbClient.h" struct clHostElement *srbHostConfig(srbConn* conn); DESCRIPTION Get the host configuration of the SRB server. This call basically returns the content of the data/hostConfig file. The output is the head of a link list of clHostElement struct.

Conn

From clConnect call.

RETURN VALUES A pointer to the clHostElement struct. This is the head of a link list of clHostElement struct. A NULL return means no result. ERRORS SEE ALSO [#srbPrintVaultInfo srbPrintVaultInfo] and [#srbFreeHostInfo srbFreeHostInfo]. [#Appendix A Top of Client API Table] NAME srbPrintHostInfo SYNOPSIS #include "srbClient.h" void srbPrintHostInfo(struct clHostElement *vaultQueHead); DESCRIPTION Print the info represented by the clHostElement link list obtained from a srbHostConfig call.

VaultQueHead

The queue head of the vaultQueElement link list to be printed.

RETURN VALUES None. ERRORS SEE ALSO [#srbHostConfig srbHostConfig] and [#srbFreeHostInfo srbFreeHostInfo]. [#Appendix A Top of Client API Table]

 NAME  

srbFreeHostInfo SYNOPSIS #include "srbClient.h" void srbFreeHostInfo(struct clHostElement *hostQueHead); DESCRIPTION Free memory taken by the clHostElement link list obtained from a srbHostConfig call.

VaultQueHead

The queue head of the vaultQueElement link list to be freed.

RETURN VALUES Returns a 0 upon success, a negative value upon failure. ERRORS SEE ALSO [#srbVaultInfo srbVaultInfo] and [#srbPrintHostInfo srbPrintHostInfo]. [#Appendix A Top of Client API Table]

 NAME  

sfoCreateIndex SYNOPSIS #include "srbClient.h" int sfoCreateIndex (srbConn *conn, sfoClass class, int catType, char *hostName, char *inIndexName, char *outIndexName, char *resourceName) DESCRIPTION Creates an index for a set of data files stored in the SRB. Metadata about the data files to be indexed and the linear index files must have already been created in the collection "inIndexName" in the SRB. The resulting index files are stored in the collection "outIndexName" in the SRB. If the collection "outIndexName" does not exist, it will be created by the indexing service.

Conn

From clConnect call.

Class

Subsetting class. Currently, the only valid class is DC_CLASS - dataCutter.

CatType

The catalog type. e.g., MDAS_CATALOG.

hostName

The the host address where this operation is to be performed. A NULL value means on the host where the client is currently connected to.

inIndexName

The SRB collection containing the input linear index files.

outIndexName

The SRB collection where the output index files to be created will be stored.

resourceName

The SRB resource on which the output index files will be created.

RETURN VALUES Returns DC_OK upon success, a negative value upon failure. ERRORS

DC_DATACAT_ERR - Cannot access/read dataset catalog file.

DC_INDEXCAT_ERR - Cannot access/read index catalog file.

DC_RTREE_ERR - Cannot create the R-tree index file.

DC_INTER_ERR - Datacutter internal error - buffer allocation, internal state, etc.

SEE ALSO [#sfoDeleteIndex sfoDeleteIndex] and [#sfoSearchIndex sfoSearchIndex]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoDeleteIndex SYNOPSIS #include "srbClient.h" int sfoDeleteIndex (srbConn *conn, sfoClass class, int catType, char *hostName, char *indexName) DESCRIPTION Deletes an index that has been created by the sfoCreateIndex() call.

Conn

From clConnect call.

Class

Subsetting class. Currently, the only valid class is DC_CLASS - dataCutter.

CatType

The catalog type. e.g., MDAS_CATALOG.

hostName

The the host address where this operation is to be performed. A NULL value means on the host where the client is currently connected to.

indexName

The SRB collection containing the index files.

RETURN VALUES Returns DC_OK upon success, a negative value upon failure. ERRORS

DC_INDEXDEL_ERR - Cannot delete the index.

DC_INTER_ERR - Datacutter internal error - buffer allocation, internal state, etc.

SEE ALSO [#sfoCreateIndex sfoCreateIndex] and [#sfoSearchIndex sfoSearchIndex]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoSearchIndex SYNOPSIS #include "srbClient.h" int sfoDeleteIndex (srbConn *conn, sfoClass class, char *hostName, char *indexName, void *query, indexSearchResult **myresult, int maxSegCount) DESCRIPTION Performs a search in the "indexName" to find the segments that intersect the range query given in the query parameter. The resulting segment metadata is written in a indexSearchResult type struct and the pointer to this struct is returned in the "myresult" parameter. The segment metadata is stored in the segments array of the "segmentInfo" struct of "myresult". The segments array is allocated by the indexing service of the server and the calling program is responsible for freeing the segment array. The "segmentCount" of "myresult" gives the number of entries in the segments array which may be less than "maxSegCount" input parameter. The returned "continueIndex" field of "myresult" will be greater than or equal to zero if there are more results to return; a -1 is returned if there is no more result. The DataCutter indexing service maintains an internal state for the query so that subsequent call of sfoGetMoreSearchResult() can return more results. If there are no more results to return, the indexing service deletes the internal query state and sets the "continueIndex" field of myresult to -1. "maxSegCount" limits the maximum number of segments to be returned from a single call to the sfoSearchIndex() function.

Conn

From clConnect call.

Class

Subsetting class. Currently, the only valid class is DC_CLASS - dataCutter.

hostName

The the host address where this operation is to be performed. A NULL value means on the host where the client is currently connected to.

indexName

The SRB collection containing the index files.

query

The spatial query input - a pointer to a "rangeQuery" type

myresult

The output of the spatial query - a double pointer to a indexSearchResult type.

maxSegCount

The maximum number of seqments to return. If the query result contains more than "maxSegCount" segments, "maxSegCount" segments will be returned in the current call and the "continueIndex" will be set to greater than or equal to 0. The sfoGetMoreSearchResult() function should be used subsequently to get the remaining segments.

RETURN VALUES Returns DC_OK upon success, a negative value upon failure. ERRORS

DC_DATACAT_ERR - Cannot read the dataset catalog file.

DC_INDEXCAT_ERR - Cannot read the index catalog file.

DC_RTREE_ERR - Cannot access the R-tree index file.

DC_QUERY_ERR - The number of query dimensions does not match the number of dataset dimensions.

DC_SEGINFO_ERR - Cannot create segment information data structures - e.g., memory allocation error.

DC_INTER_ERR - Datacutter internal error - buffer allocation, internal state, etc.

SEE ALSO [#sfoCreateIndex sfoCreateIndex], [#sfoGetMoreSearchResult sfoGetMoreSearchResult] and [#sfoDeleteIndex sfoDeleteIndex]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoGetMoreSearchResult SYNOPSIS #include "srbClient.h" int sfoGetMoreSearchResult (srbConn *conn, sfoClass class, char *hostName, int continueIndex, indexSearchResult **myresult, int maxSegCount) DESCRIPTION Used to get more results after calling the sfoSearchIndex() function. The input parameter "continueIndex" should be greater than or equal to zero and set to the returned "continueIndex" value of a previous sfoSearchIndex() call to get more results. If it is set to -1, the DataCutter indexing service should close out the internal state of this query and return no more result. The definitions of the "myresult" and "maxSegCount" are the same as those of the sfoSearchIndex() function. It should be noted that in the current implementation, the dataCutter service maintains an internal state of the current query. Thus, only one query can be active at a time for a given client connection. Another call to sfoSearchIndex() will replace the state of the current query and any subsequent calls to sfoGetMoreSearchResult() will return results for the last query.

Conn

From clConnect call.

Class

Subsetting class. Currently, the only valid class is DC_CLASS - dataCutter.

hostName

The the host address where this operation is to be performed. A NULL value means on the host where the client is currently connected to.

continueIndex

If set to greater than or equal to zero, returns more query results(up to "maxSegCount"). A -1 means the dataCutter service should close out the state of the current query.

myresult

The output of the spatial query - a double pointer to a indexSearchResult type

maxSegCount

The maximum number of seqments to return in the current call. If the query result contains more than "maxSegCount" segments, "maxSegCount" segments will be returned in the current call and the "continueIndex" will be set to greater than or equal to 0. The sfoGetMoreSearchResult() function should be called repeatedly to get the remaining segments.

RETURN VALUES Returns DC_OK upon success, a negative value upon failure. ERRORS

DC_RTREE_ERR - Cannot access the R-tree index file.

DC_QUERY_ERR - The number of query dimensions does not match the number of dataset dimensions.

DC_SEGINFO_ERR - Cannot create segment information data structures - e.g., memory allocation error.

DC_NOTINIT_ERR - The sfoSearchIndex() function has not yet been called. It must be called before the sfoGetMoreSearchResult() call is made.

DC_INTER_ERR - Datacutter internal error - buffer allocation, internal state, etc.

SEE ALSO [#sfoCreateIndex sfoCreateIndex], [#sfoSearchIndex sfoSearchIndex] and [#sfoDeleteIndex sfoDeleteIndex]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoApplyFilter SYNOPSIS #include "srbClient.h" int sfoApplyFilter (srbConn *conn, sfoClass class, char *hostName, int filterID, char *filterArg, int numberOfInputSeg, segmentInfo *inputSeg, filterDataResult **myresult, int maxSegCount) DESCRIPTION Applies the filtering operation represented by the "filterID" input parameter to the segments given in the "inputSeg" input. The parameter "numberOfInputSeg" specifies the number of segments in the "inputSeg". Results of the filtering operation is written in a filterDataResult type struct and the pointer to this struct is returned in the "myresult" parameter. The returned "continueIndex" field of "myresult" will be greater than zero if there are more results to return; a -1 is returned if there is no more result. The DataCutter indexing service maintains an internal state for the operation so that subsequent call of sfoGetMoreFilterResult() can return more results. If there are no more results to return, the indexing service deletes the internal query state and sets the "continueIndex" field of myresult to -1. "maxSegCount" limits the maximum number of segments to be returned from a single call to the sfoApplyFilter() function.

Conn

From clConnect call.

Class

Subsetting class. Currently, the only valid class is DC_CLASS - dataCutter.

hostName

The the host address where this operation is to be performed. A NULL value means on the host where the client is currently connected to.

filterID

The ID of the filtering operation to perform.

filterArg

The argument string for the filtering operation

myresult

Results of the filtering operation - a double pointer to a filterDataResult type

maxSegCount

The maximum number of seqments to return. If the filtering result contains more than "maxSegCount" segments, "maxSegCount" segments will be returned in the current call and the "continueIndex" will be set to greater than or equal to 0. The sfoGetMoreFilterResult() function should be used subsequently to get the remaining segments.

RETURN VALUES Returns DC_OK upon success, a negative value upon failure. ERRORS

DC_FILTERID_ERR - Invalid filterID.

DC_FILTER_ERR - Error in carrying the filtering operation.

DC_SEGMENT_ERR - Cannot read or process a segment in the input list.

DC_INTER_ERR - Datacutter internal error - buffer allocation, internal state, etc.

SEE ALSO [#sfoSearchIndex sfoSearchIndex], and [#sfoGetMoreFilterResult sfoGetMoreFilterResult]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoGetMoreFilterResult SYNOPSIS #include "srbClient.h" int sfoGetMoreFilterResult (srbConn *conn, sfoClass class, char *hostName, int continueIndex, filterDataResult **myresult, int maxSegCount) DESCRIPTION Used to get more results after calling the sfoApplyFilter() function. The input parameter "continueIndex" should be greate than or equal to zero and set to the returned "continueIndex" value of a previous sfoApplyFilter() call to get more results. If it is set to -1, the DataCutter indexing service would close out the internal state of this operation and return no more result. The definitions of the "myresult" and "maxSegCount" are the same as those of the sfoApplyFilter() function. It should be noted that in the current implementation, the dataCutter service manintains an internal state of the current filtering operation. Thus, only one operation can be active at a time for a given client connection. Another call to sfoApplyFilter() will replace the state of the current operation and any subsequent calls to sfoGetMoreFilterResult() will return results for the last filtering operation.

Conn

From clConnect call.

Class

Subsetting class. Currently, the only valid class is DC_CLASS - dataCutter.

hostName

The the host address where this operation is to be performed. A NULL value means on the host where the client is currently connected to.

continueIndex

If set to greater than or equal to zero, returns more results(up to "maxSegCount"). A -1 means the dataCutter service should close out the state of the current operation.

myresult

The output of the filtering operation - a double pointer to a indexSearchResult type.

maxSegCount

The maximum number of seqments to return in the current call. If the result contains more than "maxSegCount" segments, "maxSegCount" segments will be returned in the current call and the "continueIndex" will be set to greater than or equal to 0. The sfoFreeFilterResults() function should be called repeatedly to get the remaining segments.

RETURN VALUES Returns DC_OK upon success, a negative value upon failure. ERRORS

DC_NOTINIT_ERR - The sfoApplyFilter() function has not yet been called. It must be called before the sfoGetMoreFilterResult() call is made.

DC_FILTER_ERR - Error in carrying the filtering operation.

DC_SEGMENT_ERR - Cannot read or process a segment in the input list.

DC_INTER_ERR - Datacutter internal error - buffer allocation, internal state, etc.

SEE ALSO [#sfoGetMoreSearchResult sfoGetMoreSearchResult] and [#sfoSearchIndex sfoSearchIndex].

rP>

[#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoFreeIndexResults SYNOPSIS #include "srbClient.h" int sfoFreeIndexResults (indexSearchResult *myresult) DESCRIPTION Free all memory associated with a indexSearchResult type struct.

myresult

The indexSearchResult type struct to free.

RETURN VALUES Returns 0 upon success, a negative value upon failure. ERRORS SEE ALSO [#sfoApplyFilter sfoApplyFilter] and [#sfoSearchIndex sfoSearchIndex]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoFreeFilterResults SYNOPSIS #include "srbClient.h" int sfoFreeIndexResults (filterDataResult *myresult) DESCRIPTION Free all memory associated with a filterDataResult type struct.

myresult

The filterDataResult type struct to free.

RETURN VALUES Returns 0 upon success, a negative value upon failure. ERRORS SEE ALSO [#sfoApplyFilter sfoApplyFilter] and [#sfoGetMoreFilterResult sfoGetMoreFilterResult]. [#Appendix B Top of Client API Table - Appendix B]

 NAME  

sfoFreeSegmentInfo SYNOPSIS #include "srbClient.h" int sfoFreeSegmentInfo (segmentInfo *seg_i) DESCRIPTION Free all memory associated with a segmentInfo type struct.

seg_i

The segmentInfo type struct to free.

RETURN VALUES Returns 0 upon success, a negative value upon failure. ERRORS SEE ALSO [#sfoApplyFilter sfoApplyFilter] and [#sfoSearchIndex sfoSearchIndex]. [#Appendix B Top of Client API Table - Appendix B]