How To Use The Client Library

From SRB

This is a short note on how to use the SRB client library. (This was the README.client document before the Wiki system.) In addition, comments and prototyping of the client API given in the clStubExtern.h and clConnectExtern.h files may be useful.


1) Setting up the client user environment - Before a user can connect to the SRB server, some SRB user environment parameters need to be set up. See section 2) of User Environment for details.


2) Setting up user authentication - See section 3) of User Environment for details of authentication setup.

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

An example of the Makefile can be found in test/examples/Makefile.in.

4) The client uses the srbConnect(char *srbHost, char* srbPort, char* srbAuth, char *userName, char *domainName, char *authScheme, char *serverDn) call to connect to the SRB server. The definition of the input parameters are given in 1). NULL inputs are acceptable in which case they will default to the values given in the .MdasEnv and .MdasAuth files or through the use of UNIX environment varibles.

5) After a connection to the SRB server has been opened, the connection can be used by the client to issue requests to the SRB server using the client APIs.

6) Upon completion, the client should issue a clFinish(conn) call to close the connection to the SRB server.

7) 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 pointer type return values, A NULL returned value implies error. The error code for integer type returns are given in include/srbErrno.h and catalog/include/mdas_errno.h. Typically, these are error codes that are internally generated by the SRB and MDAS.

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

An example of using clErrorMessage():

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

       if (dirDesc < 0) {
           fprintf(stderr,"Unable to srbOpendir . \n");
           fprintf(stderr,"%s",clErrorMessage(conn));
           exit (1);
       }

8) Some client examples:

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


sconnect.c - Connect to the default srbSrever.

sget.c - Export a file from srb to local fs.

sput.c - Import a local file into srb

sgetcopy.c - Export a replica from srb to local fs.

squery.c - replicate a srb file.

sreplicate.c - replicate a srb file.

sstat.c - get the stat a srb file.


In addition to these client examples, if may be helpful to examine client code in the test/testsuite and utilities/src directories.