SRB 2.0.0 Overview

From SRB

(Difference between revisions)

Revision as of 18:30, 6 March 2006

SRB - The Storage Resource Broker (Version 2.0.0)

(This was readme.dir/web/SRB.htm. I've converted it to wiki and inserted it, but we'll need to rework this. Perhaps different sections should be their own pages, and some of this removed as replaced by other pages that are more recent.)

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

1.0 The SRB Architecture

1.1 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 set of UNIX like utilities (e.g., ls, cp, chmod, etc) for manipulating and querying collections and datasets in the SRB space.

5) 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.

6) 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.

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

8) The container abstraction Due to the relative high overhead of creating/opening files in archival storage systems such as HPSS, they are not suitable for storing large amount of small files typically found in digital library systems. The container concept was specifically created to handle this type limitation. Through the use of containers, many small files can be aggregated in the cache system before storage in the archival storage system. A caching system has been designed to handle container I/O. The current version of the SRB server has been designed to handle multiple archival and cache storage resources.

9) "Server driven" parallel I/O - The "Server driven" parallel I/O scheme has been implemented throughout the SRB infrastructure. It is the preferred data transfer mechanism for data import, export, copy and replication. The parallel I/O uses the more efficient "mover" APIs and protocol to access HPSS resources.

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 four authentication schemes - The SRB can now support four authentication schemes - GSI, SEA (developed at SDSC), plain text password 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). SEA is a authentication and encryption scheme developed at SDSC based on RSA key encryption scheme. (http://www.npaci.edu/DICE/Software/SEA/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) Bulk Ingestion - A bulk ingestion mode has been implemented. This feature enables, a user to create a container and register the requisite metadata in parallel and in bulk. The system has been tested at SDSC to ingest into SRB medium-sized data files in large directory structures at more than 400 files per second. The feature is available through the command called Sbload.

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

18) srbMon - a SRB server monitoring daemon. The srbMon 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.

19) UNIX Transparency - This involves using the PRELOAD feature of the Solaris and Linux platform to trap UNIX I/O system calls and replaced them with SRB I/O calls so that regular UNIX commands and applications can be used to access and manipulate data stored in SRB without recompiling. Please read README.transparency for more info on this subject.

20) Support file size larger than 2GB - The SRB software will now support file size larger than 2 GB for the Solaris, Linix, Aix and C90 platforms.

21) Prespawning server processes - To improve interactivity, the SRB servers can now be configured to prespawn a specific number of server processes.

22) Platforms supported The SRB has been implemented on AIX, Sun Solaris(32 and 64 bits address), Linux 32 and 64 bits address), SunOs, DEC OSF, SGI, MacOS X and the Cray C90. The MCAT catalog now runs on both the Oracle and DB2 DBMS.

[#Beginning Image:Top.gif] '

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

[#Beginning Image:Top.gif] '

1.3 Implementation details

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

[#Beginning Image:Top.gif] '

1.3.2 Federated 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 clients 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.

[#Beginning Image:Top.gif] '

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

[#Beginning Image:Top.gif]

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

[#Beginning Image:Top.gif] '

2.0 The SRB client API

2.1 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. Based on the type of data sets they operate on, these API may be classified into two groups, 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.

The low-level API can be subdivided further into file-type and DB-type API because of the different types of operation they support.

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

[#Beginning Image:Top.gif] '

2.2 Description of API

A brief description of the SRB client API is given below. The API are grouped into six categories according to functionality and the type of data set they operate on. 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.

[#clConnect clConnect] - Initiate a connection to a SRB server.

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

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

[#clErrorMessage 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 srbObjOpen] - Open a SRB data set.

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

[#srbObjCreate srbObjCreate] - Create a SRB data set.

[#srbObjClose srbObjClose] - Close an opened data set.

[#srbObjUnlink srbObjUnlink] - Unlink a data set.

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

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

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

[#srbObjSync srbObjSync] - Sync an opened SRB object.

[#srbObjStat srbObjStat] - Stat an SRB object.

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

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

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

[#srbObjProxyOpr srbObjProxyOpr] - Proxy Operation request.

[#srbExecCommand srbExecCommand] - Remote execution of command.

[#srbObjReplicate srbObjReplicate] - Make a copy of a data set.

[#srbObjMove srbObjMove] - Move a copy of a data set to a new location.

[#srbCreateCollect srbCreateCollect] - Create a SRB collection.

[#srbListCollect srbListCollect] - List a SRB collection.

[#srbModifyCollect srbModifyCollect] - Modify a SRB collection.

[#srbIssueTicket srbIssueTicket] - Issue a ticket.

[#srbRemoveTicket srbRemoveTicket] - Cancel a ticket.

[#srbContainerCreate srbContainerCreate] - Create a container.

[#srbRmContainer srbRmContainer] - Remove a container.

[#srbSyncContainer srbSyncContainer] - Synchronize copies of a container.

[#srbReplContainer srbReplContainer] - Replicate/stage a container.

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

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

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

3) Low-Level File-type API:

[#srbFileOpen srbFileOpen] - Opens a file.

[#srbFileCreate srbFileCreate] - Create a file.

[#srbFileUnlink srbFileUnlink] - Unlink a file.

[#srbFileClose srbFileClose] - Close a file.

[#srbFileRead srbFileRead] - Read a block of data from a file into buffer.

[#srbFileWrite srbFileWrite] - Write content of a buffer to a file.

[#srbFileSeek srbFileSeek] - Change the current read or write location on a file.

[#srbFileSync srbFileSync] - Sync a file.

[#srbFileStat srbFileStat] Get the status of a file.

[#srbFileFstat srbFileFstat] Get the status of a file descriptor.

[#srbFileMkdir srbFileMkdir] - Create a new directory.

[#srbFileChmod srbFileChmod] - Change the mode of a file or directory.

[#srbFileRmdir srbFileRmdir] - Remove a directory.

[#srbOpendir srbOpendir] - Opens a directory

[#srbClosedir srbClosedir] - Close an opened directory

[#srbReaddir srbReaddir] - Read a directory entry

[#srbSetStorAttri srbSetStorAttri] - Set Attributes for a Storage System; establish connection.

Only used by FTP file type,

4) Lower-level DB-type API:

[#srbDbLobjOpen srbDbLobjOpen] - Open a DB Large Object.

[#srbDbLobjCreate srbDbLobjCreate] Create a DB Large Object.

[#srbDbLobjClose srbDbLobjClose] - Close a DB Large Object.

[#srbDbLobjRead srbDbLobjRead] - Read a block of data from a DB large object into buffer.

[#srbDbLobjWrite srbDbLobjWrite] - Write content of a buffer to a DB large object.

[#srbDbLobjSeek srbDbLobjSeek] - Change the current read or write location of a DB large object.

[#srbDbLobjUnlink srbDbLobjUnlink] - Unlink a DB large object.

5) Lower-level DB table object API:

[#srbDbTableOpen srbDbTableOpen] - Open a DB Table Object.

[#srbDbTableCreate srbDbTableCreate] Create a DB Table Object.

[#srbDbTableClose srbDbTableClose] - Close a DB Table Object.

[#srbDbTableRead srbDbTableRead] - Read a block of data from a DB Table object into buffer.

[#srbDbTableWrite srbDbTableWrite] - Write content of a buffer to a DB Table object.

[#srbDbTableSeek srbDbTableSeek] - Change the current read or write location of a DB Table object.

[#srbDbTableUnlink srbDbTableUnlink] - Unlink a DB Table object.

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

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

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

[#srbRegisterDataset srbRegisterDataset] - Register a SRB data object.

[#srbUnregisterDataset srbUnregisterDataset] - Unregister a SRB data object.

[#srbSetAuditTrail srbSetAuditTrail] - Setting and Unsetting Audit Trail.

[#srbModifyDataset srbModifyDataset] - Modify a SRB data set

[#srbChkMdasAuth srbChkMdasAuth] - Authenticate a userName/passwd.

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

[#srbRegisterUserGrp srbRegisterUserGrp] - Register a user group

[#srbRegisterUser srbRegisterUser] - Register a user.

[#srbModifyUser srbModifyUser] - Modify a user info.

[#srbGetPrivUsers srbGetPrivUsers] - Read the privileged users list.

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

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

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

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

[#srbGetContainerInfo srbGetContainerInfo] - Query metadata associated with a container.

[#srbRegisterLocation srbRegisterLocation] - Register/create a new location.

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

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

[#srbRegisterLogicalResource srbRegisterLogicalResource] - Register/create a new logical resource.

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

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

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

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

6) Miscellaneous SRB API:

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

[#srbVaultInfo srbVaultInfo] - Get Info on the SRB storage vault.

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

[#srbPrintVaultInfo srbPrintVaultInfo] - Print out the VaultInfo link list.

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

[#srbPrintHostInfo srbPrintHostInfo] - Print the HostInfo link list.

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

[#Beginning Image:Top.gif] '

3.0 Setting up Client Environment

3.1 Building and installing the SRB client library

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

It should be noted that 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 the URL http://www.npaci.edu/DICE/Software/SEA/index.html, must be built first.

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 parameters are self-explanatory through the comments given in this file. Some of the more important parameters are discussed below:

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. i.e., valid PORTNAME's are : PORTNAME_solaris, PORTNAME_sunos, PORTNAME_aix, PORTNAME_linux, PORTNAME_osx, PORTNAME_alpha, PORTNAME_c90 and PORTNAME_sgi.

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

MDAS_AUTH - defines whether the MDAS authorization scheme will be supported for authentication. If used, the user/passwd pair registered with the MDAS catalog will be used to authenticate a user. Comment it out if your SRB server should not support MDAS authorization. It is ON (not commented out) by default.

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

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. This is commented out by default.

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.

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

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.

2) "cd" to the the main SRB directory and type in "gmake clean" and then "gmake" to make the SRB software.

3) 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.

[#Beginning Image:Top.gif] '

3.2 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:

'PASSWD_AUTH' - Use the plain text password Mdas Authentication. If this option is chosen, an additional file containing the password the the .MdasAuth is required.

'ENCRYPT1' - Same as PASSWD_AUTH except the passwords are encrypted using a self contained scheme.

'SEA_AUTH' - Use the SEA authentication scheme.

'SEA_ENCRYPT' - Use the SEA authentication scheme plus encryption.

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

'GSI_SECURE_COMM' - Use the GSI authentication scheme and use the GSI I/O library for all socket communication between client and server. If this option is chosen, an additional parameter SERVER_DN given below is required.

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

2) Setting up user authentication - The SRB software can be built to support the GSI, SEA and password authentication schemes. 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) SEA authentication setup A client needs to register him/herself with the SEA server by running the following command:

seaauth reg

This is a one time exercise which in effect, triggers the registration of the user and obtaining a password encrypted private key which will be placed in a file named ~/.SEAuuuuu@ddddd (where uuuuu is the user ID and ddddd is the user domain name). Then type in the following command:

seaauth auto

to generate an unencrypted private key in the /tmp directory which can be used directly by the SEA library routines to authenticate the user.

b) Password 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.

c) 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.

[#Beginning Image:Top.gif] '

3.3 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

[#Beginning Image:Top.gif] '

4.0 Client Programming

 4.1 Connecting and disconnecting to the SRB Server

The client uses the clConnect(char* srbHost, char* srbPort, char* srbAuth) call to connect to the SRB server. srbHost specifies the host where the SRB server is running. 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.

The srbPort input defines the port number (in character string) to connect to the SRB server. If the input value in NULL, it will use the env variable "srbPort" if it is defined. If not, it defaults to "5558".

The srbAuth input 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. This file should only be readable by the file owner. If a client uses more than one method to specify the password, the value given in the clConnect () call will take precedent, then the env variable "srbAuth", and lastly, the ~.srb/.MdasAuth file.

After a connection to the SRB server has been opened, the client can then use the connection to issue requests to the SRB server.

Upon completion, the client should issue a clFinish(conn) call to

close the connection to the SRB server.

[#Beginning Image:Top.gif] '

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

[#Beginning Image:Top.gif] '

4.3 Client programming examples:

Examples of SRB client can be found in the test/examples/src directory of the distribution.

The following are examples of using the High-Level Object API:

testsrb.c - Example of using a mixed bag of High Level Object API - [#srbSetAuditTrail srbSetAuditTrail], [#srbObjOpen srbObjOpen], [#srbObjRead srbObjRead], [#srbObjClose srbObjClose], [#srbListCollect srbListCollect], [#srbGetMoreRows srbGetMoreRows], [#srbGetDatasetInfo srbGetDatasetInfo], etc.

srbcat.c - Cat a High Level Object - [#srbObjOpen srbObjOpen], [#srbObjRead srbObjRead], [#srbObjClose srbObjClose].

testcoll.c - Example of using High Level Object API to manipulate collections - [#srbListCollect srbListCollect], [#srbGetMoreRows srbGetMoreRows], [#srbCreateCollect srbCreateCollect], [#srbModifyCollect srbModifyCollect], etc.

testcre.c - Example of creating High Level Object - [#srbObjCreate srbObjCreate], [#srbObjWrite srbObjWrite], [#srbObjClose srbObjClose], etc.

testunlink.c - Example of removing High Level Object - [#srbObjUnlink srbObjUnlink].

testrepl.c - Example of making replicate of an object - [#srbObjReplicate srbObjReplicate].

testmove.c - Example of moving a High Level Object from one physical location to another - [#srbObjMove srbObjMove].

testproxy.c - Example of a proxy copy operation - [#srbObjOpen srbObjOpen], [#srbObjCreate srbObjCreate], [#srbObjProxyOpr srbObjProxyOpr].

issuetick.c - Example of issuing a ticket - [#srbIssueTicket srbIssueTicket].

rmtick.c - Example of removing a ticket - [#srbRemoveTicket srbRemoveTicket].

usetick.c - Example of using a ticket to read a dataset - [#srbObjOpenWithTicket srbObjOpenWithTicket] and [#srbObjRead srbObjRead].

testtick.c - Example of a using a mixed bag of ticket type API - [#srbIssueTicket srbIssueTicket], [#tiUserConnect tiUserConnect], [#clConnect clConnect], [#srbObjOpenWithTicket srbObjOpenWithTicket], [#srbRemoveTicket srbRemoveTicket], [#srbObjRead srbObjRead], [#srbObjClose srbObjClose].

testddir.c - Example of using the srbGetDataDirInfo call to query MCAT information - [#srbGetDataDirInfo srbGetDataDirInfo].

testuser.c - Example of using sys admin API to query and manipulate MCAT user information - [#srbChkMdasSysAuth srbChkMdasSysAuth], [#srbRegisterUser srbRegisterUser], [#srbRegisterUserGrp srbRegisterUserGrp] and [#srbRegisterUser srbRegisterUser].

The following are examples of using the Low-Level File-type API:

testexf.c - Example of using a mixed bag of Extended File API - [#srbFileMkdir srbFileMkdir], [#srbFileRmdir srbFileRmdir], [#srbFileChmod srbFileChmod], [#srbFileUnlink srbFileUnlink], [#srbFileCreate srbFileCreate], [#srbFileWrite srbFileWrite], [#srbFileClose srbFileClose], [#srbFileStat srbFileStat], etc.

exfls.c - Example of using [#srbOpendir srbOpendir], [#srbReaddir srbReaddir] and [#srbFileStat srbFileStat].

exfrm.c - Remove an extended file - [#srbFileUnlink srbFileUnlink].

testftp.c - Example of using the File-type API for the FTP file type.

testhttp.c - Example of using the File-type API for the HTTP file type.

The following are examples of using the Low-Level DB-type Large Object API:

testLobj.c - Example of using the DB-type Large Object calls - [#srbDbLobjCreate srbDbLobjCreate], [#srbDbLobjUnlink srbDbLobjUnlink], [#srbDbLobjOpen srbDbLobjOpen] and [#srbDbLobjClose srbDbLobjClose].

Other examples can be found in the test/testsuite and utilities/src directories.

The following gives a few specific examples of using the SRB client API:

1) An example for using [#clConnect clConnect()], [#clFinish clFinish()] and [#clErrorMessage clErrorMessage()]:

#include "srbClient.h"

/* Use the srbAuth and srbHost values defined in ~/.srb/.MdasEnv */

#define SRB_AUTH NULL

#define HOST_ADDR NULL

main(int argc, char **argv)

{

srbConn *conn;

int dirDesc;

int storSysType;

/* Connect to the SRB server */

conn = clConnect (HOST_ADDR, NULL ,SRB_AUTH);

/* check to see if the connection was successful */

if (clStatus(conn) != CLI_CONNECTION_OK) {

fprintf(stderr,"Connection to SRB server failed.\n");

fprintf(stderr,"%s",clErrorMessage(conn));

exit_nicely(conn);

}

/* Open a file-type directory */

dirDesc = srbOpendir (conn, storSysType, HOST_ADDR, ".");

if (dirDesc < 0) {

fprintf(stderr,"Unable to srbOpendir . \n");

fprintf(stderr,"%s",clErrorMessage(conn));

exit_nicely(conn);

}

/* Disconnect */

clFinish(conn);

2) An example for creating a high-level data object and writing to it.

This example assumed a connection has already been made using example 1). The object is created in a storage resource named "unix-sdsc". This resource must have already been registered in MCAT.

#define DATATYPE "ascii text"

#define RESOURCE "unix-sdsc"

#define COLLECTION "/srbtest"

int in_fd, out_fd;

int nbytes, tmp;

char buf[BUFSIZE];

/* Create a data object with objID = argv[1] */

out_fd = srbObjCreate (conn, MDAS_CATALOG, argv[1],

DATATYPE, RESOURCE ,COLLECTION, NULL, 0);

if (out_fd < 0) { /* error */

fprintf(stderr, "can't create obj \"%s\", status = %d\n", argv[1],

out_fd);

fprintf(stderr,"%s",clErrorMessage(conn));

exit_nicely(conn);

}

/* Open a local file with filename = inFileName. */

in_fd = open (inFileName, O_RDONLY, 0);

if (in_fd < 0) { /* error */

fprintf(stderr, "can't open file\"%s\"\n",

inFileName);

exit_nicely(conn);

}

/* Read from the local file and write to the just created data object */

while ((nbytes = read(in_fd, buf, BUFSIZE)) > 0) {

/* Write to the data object */

tmp = srbObjWrite(conn, out_fd, buf, nbytes);

if (tmp < nbytes) {

fprintf(stderr, "Error: Read %d bytes, Wrote %d bytes.\n ",

nbytes, tmp);

exit_nicely(conn);

}

srbObjClose (conn, out_fd);

close (in_fd);

3) An example for creating and listing collections.

This example creates a new collection in a parent collection, and then the parent collection is listed.

Include "srbClient.h"

#define PARRENT_COLLECTION "/srbtest"

#define NEW_COLLECTION "foo"

#define ROWS_WANTED 2

char * parentCollection, newCollection;

int status;

mdasC_sql_result_struct *collResult;

parentCollection = PARRENT_COLLECTION;

newCollection = NEW_COLLECTION;

/* Create a new collection */

if ((status = srbCreateCollect (conn, MDAS_CATALOG, parentCollection,

newCollection)) < 0) {

fprintf(stderr, "can't srbCreateCollect, status = %d\n", status);

exit_nicely(conn);

}

/* List the parent collection */

collResult = malloc (sizeof (mdasC_sql_result_struct));

if ((status = srbListCollect (conn, 0, COLLECTION, "R",

collResult, ROWS_WANTED)) < 0) {

fprintf(stderr, "can't srbListCollect, status = %d\n", status);

exit_nicely(conn);

}

printSqlResult (collResult); /* print the result */

clearSqlResult (collResult); /* clear the content of collResult */

/* Any more result ? */

while (collResult->continuation_index >= 0) {

/* Yes, we have more. Get the next ROWS_WANTED rows */

if ((status = srbGetMoreRows(conn, 0,

collResult->continuation_index, collResult, ROWS_WANTED)) < 0)

break;

/* Dump the result */

printSqlResult (collResult);

clearSqlResult (collResult);

}

4) An example for a proxy copy operation.

This example performs a proxy copy operation. The source data object is opened and the destination data object is created first. Then a proxy copy operation is initiated.

#include "srbClient.h"

#define DATATYPE "ascii text"

#define RESOURCE "unix-sdsc"

#define COLLECTION "/srbtest"

int i, nbytes, tmp, in_fd, out_fd;

char in_fd_str[SML_BUF_SZ], out_fd_str[SML_BUF_SZ];

int status, nbytes;

/* open the source object with objID = argv[1] */

in_fd = srbObjOpen (conn, argv[1], O_RDONLY, COLLECTION);

if (in_fd < 0) { /* error */

fprintf(stderr, "can't open obj\"%s\"\n", argv[1]);

exit_nicely(conn);

}

/* Create the destination object with objID = argv[2] */

out_fd = srbObjCreate (conn, MDAS_CATALOG, argv[2],

DATATYPE, RESOURCE, COLLECTION, NULL, 0);

if (out_fd < 0) { /* error */

fprintf(stderr, "can't create obj \"%s\", status = %d\n", argv[2],

out_fd);

fprintf(stderr,"%s",clErrorMessage(conn));

exit_nicely(conn);

}

/* Convert fd to string */

sprintf (in_fd_str, "%d", in_fd);

sprintf (out_fd_str, "%d", out_fd);

/* Do a proxy copy operation */

nbytes = srbObjProxyOpr (conn, OPR_COPY, in_fd_str, out_fd_str);

printf ("\n\nBytes written: %d\n", nbytes);

srbObjClose (conn, out_fd);

srbObjClose (conn, in_fd);

5) An example for issuing tickets and using tickets to open and read data objects.

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.

In this example, the client issues a ticket on a data object to unregistered users meaning any user may use the ticket to open and read the data object. This example then makes a second connection to the SRB as an unregistered user ("ticketuser") and use the ticket to open and read the data object.

#include "srbClient.h"

#define BUFSIZE 4096

#define srbAuth NULL

#define HOST_ADDR NULL

#define COLLECTION "/srbtest"

#define BEGINTIME NULL

#define ENDTIME NULL

#define ACCESSCNT 1 /* Ticket is only good for 1 time access */

#define ROWS_WANTED 2

srbConn *conn, *conn1;

int nbytes, in_fd, out_fd;

char buf[BUFSIZE];

int status;

char *ticket;

char *ticketUser;

/* Set up the first connection to issue a ticket */

conn = clConnect (HOST_ADDR, NULL, srbAuth);

/* check to see that the backend connection was successfully made */

if ((status = clStatus(conn)) != CLI_CONNECTION_OK) {

fprintf(stderr,"Connection to SRB server failed.\n");

fprintf(stderr,"%s",clErrorMessage(conn));

exit_nicely(conn);

}

/* Issue a ticket on objID = argv[1] to any user, even unregistered */

ticketUser = ""; /* Any user */

if ((status = srbIssueTicket (conn, argv[1], COLLECTION, COLLFLAG,

BEGINTIME, ENDTIME, ACCESSCNT, ticketUser, &ticket)) < 0) {

fprintf(stderr, "can't srbIssueTicket obj\"%s\", %d\n",

argv[1], status);

exit_nicely(conn);

}

/* Print the ticket */

printf ("ticket = %s\n", ticket);

/* Make a second connection as a unregistered user ("ticketuser") */

conn1 = tiUserConnect (HOST_ADDR, NULL);

if ((status = clStatus(conn1)) != CLI_CONNECTION_OK) {

fprintf(stderr,"Connection to srbMaster failed.\n");

fprintf(stderr,"%s",clErrorMessage(conn));

srbRemoveTicket (conn, ticket);

exit_nicely(conn);

}

/* Use the 2nd connection and open the data object with the ticket */

in_fd = srbObjOpenWithTicket (conn1, argv[1], O_RDONLY, COLLECTION,

ticket);

if (in_fd < 0) { /* error */

fprintf(stderr, "can't open obj\"%s\"\n", argv[1]);

srbRemoveTicket (conn, ticket);

exit_nicely(conn);

}

/* Read the data object */

while ((nbytes = srbObjRead (conn1, in_fd, buf, BUFSIZE)) > 0) {

printf ("Content of the object: \n%s\n", buf);

}

srbObjClose (conn1, in_fd);

clFinish(conn1); /* Close the second connection */

/* remove the ticket */

status = srbRemoveTicket (conn, ticket);

if (status < 0) {

fprintf(stderr, "srbRemoveTicket error. status = %d\n", status);

fprintf(stderr,"%s",clErrorMessage(conn));

}

ClFinish(conn); /* Close the first connection */

6) An example for querying the MCAT catalog for information.

This example uses the [#srbGetDataDirInfo srbGetDataDirInfo()] call to query the MCAT catalog. This query selects the resource name, resource type, network address and path name, given the name of a data object.

#include "srbClient.h"

#define srbAuth NULL

#define HOST_ADDR NULL

#define COLLECTION "/srbtest"

#define ROWS_WANTED 2

mdasC_sql_result_struct *myresult;

char qval[MAX_DCS_NUM][MAX_TOKEN];

int selval[MAX_DCS_NUM];

int i;

int status;

/* Initialize the selval and qval array. */

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

selval[i] = 0;

sprintf(qval[i],"");

}

/* set up the query: Given the Data Object Name, select the path name,

* resource name, the network address and the resource type.

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

selval[PATH_NAME] = 1;

selval[RSRC_NAME] = 1;

selval[RSRC_ADDR_NETPREFIX] = 1;

selval[RSRC_TYP_NAME] = 1;

myresult = malloc (sizeof (mdasC_sql_result_struct));

/* Send the query request */

if ((status = srbGetDataDirInfo(conn, 0, qval, selval, myresult,

ROWS_WANTED)) < 0) {

fprintf(stderr, "can't srbGetDataDirInfo. status = %d.\n",

status);

exit_nicely(conn);

}

/* Dump the result */

printSqlResult (myresult);

clearSqlResult (myresult); /* clear the content of myresult */

/* Print any additional rows */

while (myresult->continuation_index >= 0) {

if ((status = srbGetMoreRows(conn, 0,

myresult->continuation_index, myresult, ROWS_WANTED)) < 0)

break;

/* Dump the result */

printSqlResult (myresult);

clearSqlResult (myresult);

}

freeSqlResult (myresult);

7) An example for creating a container and put an object in the container.

This example uses the [#srbContainerCreate srbContainerCreate()] call to create a container and the [#srbObjCreate srbObjCreate()] call to create an inContainer object.

#include "srbClient.h"

#define srbAuth NULL

#define HOST_ADDR NULL

#define COLLECTION "/srbtest"

#define DATATYPE "generic"

#define LOG_RESC "test-log-resc"

#define CONTAINER_NAME "testContainer"

#define CONTAINER_SZ 1000000

#define OBJECT_NAME "foo"

char objName[MAX_TOKEN];

int status, fd;

/* Create the container */

if ((status = srbContainerCreate (conn, MDAS_CATALOG, CONTAINER_NAME,

DATATYPE, LOG_RESC, CONTAINER_SZ)) < 0) {

fprintf(stderr, "can't srbContainerCreate. status = %d.\n",

status);

exit_nicely(conn);

}

/* Create the inContainer obj */

sprintf (objName, "%s&CONTAINER=%-s", OBJECT_NAME, CONTAINER_NAME);

out_fd = srbObjCreate (conn, MDAS_CATALOG, objName,

DATATYPE, "" ,COLLECTION, NULL, 0);

if (fd < 0) { /* error */

fprintf(stderr, "can't create obj \"%s\", status = %d\n", OBJECT_NAME,

fd);

fprintf(stderr,"%s",clErrorMessage(conn));

exit_nicely(conn);

}

[#Beginning Image:Top.gif] '

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:

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]

 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

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

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

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

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

[#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.

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

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 users 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

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

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

Retrieved from "http://www.sdsc.edu/srb/index.php/SRB_2.0.0_Overview"

 <br />[README.first.htm Release Notes for Version 2.0.0]
-<br />[#Major features of the SRB 1.0 The SRB Architecture]
-[#Major features of the SRB 1.1 Major features of the SRB ]<br />[#An Overview of the SRB architecture  1.2 An Overview of the SRB architecture]<br />[#Implementation details 1.3 Implementation details][#The SRB process model 1.3.1 The SRB process model]<br />[#Federated SRB servers 1.3.2 Federated SRB servers]<br />[#The SRB agent design details 1.3.3 The SRB agent design details]<br />[#The SRB container design 1.3.4 The SRB container design]
-[#The SRB client API 2.0 The SRB client API]
-[#Overview 2.1 Overview]<br />[#Description of API 2.2 Description of API]
-[#Setting up Client Environment 3.0 Setting up Client Environment]
-[#Building and installing the SRB client library 3.1 Building and installing the SRB client library]<br />[#Setting up the client user environment 3.2 Setting up the client user environment]<br />[#Locations of the SRB client library and header files 3.3 Locations of the SRB client library and header files]
-[#Client Programming 4.0 Client Programming]
-[#Connecting and disconnecting to the SRB Server 4.1 Connecting and disconnecting to the SRB Server]<br />[#Error handling 4.2 Error handling]<br />[#Client programming examples 4.3 Client programming examples]
-[#Installing and configuring the SRB servers 5.0 Installing and configuring the SRB servers]
-[#Building and installing the SRB server 5.1 Building and installing the SRB server]<br />[#Configuring the SRB servers 5.2 Configuring the SRB servers]<br />[#Quick server setup 5.2.1 Quick server setup]<br />[#Detailed server setup 5.2.2 Detailed server setup] <br />[#Starting the SRB server 5.3 Starting the SRB server]<br />[#Running the test suite 5.4 Running the test suite]
-<br />[#Building and Running the srbBrowser 6.0 Building and Running the JAVA based srbBrowser ]
-<br />[#Building the srbBrowser 6.1 Building the JAVA based srbBrowser ]<br />[#Running the srbBrowser 6.2 Running the JAVA based srbBrowser ]
-<br />[#Building and Running the srbMon 7.0 Building and Running srbMon - a SRB server monitoring program]
-[#Appendix A Appendix A - Descriptions of the SRB Client API]
-[#Appendix B Appendix B - Descriptions of the DataCutter Client API]
 == 1.0 The SRB Architecture ==

SRB 2.0.0 Overview

From SRB

Revision as of 18:30, 6 March 2006

SRB - The Storage Resource Broker (Version 2.0.0)

1.0 The SRB Architecture

1.1 Major features of the SRB

Views

Personal tools

Navigation

SRB Clients

Search

Toolbox