Subsections


SRB

References [#!srb!#].

Summary

This chapter describes a set of client routines to access the functionality of SRB [#!srb!#], the Storage Resource Broker. They are designed to allow the most commonly used operations to be carried out with relatively simple function calls, removing most of the complexity of the SDSC C API. This does not, however, pretend to be a fully featured interface, and for some applications the use of SCommands, MySRB or even direct calls to the existing SDSC API may be more appropriate.

It should be noted that for the sake of simplification, some of the SRB terminology has been eliminated within this interface, and hence this document. In the places where we refer to ``files'' and ``directories'', the SRB documentation generally uses the strictly correct terms ``data objects'' and ``collections''. For the purposes of this library, the distinction will be overlooked.

Attributes

Version: 2.0a
Public calls: srbStart; srbStartManual; srbEnd; srbGetActiveConnectionPtr;srbRenameFile; srbGetFile; srbPutFile; srbDeleteFile; srbCopyFile; srbFileInfo; srbGetDirectory; srbPutDirectory; srbCreateDirectory;srbDeleteDirectory; srbRenameDirectory; srbDirectoryInfo;srbGetCurrResource; srbSetCurrResource; srbGetTransferBufferSize;srbSetTransferBufferSize
Public modules: growl_srb.a
Other modules required: SRB v3.3.1 or higher(libSrbClient.a)
Date: 2006
Origin: A.L. Braimah, CCLRC Daresbury Laboratory
Language: C
Restrictions: Only one SRB connection can be active at once per program compiled with this library.
Conditions on external use: Standard, see separate chapter

How to use the Package

You will need to statically link your program with growl_srb.o and libSrbClient.a, and the correct PORTNAME_ compile flag must be defined (see SRB documentation). Your calling code must #include the file growl.h before stdio.h.

Specification of SRB Module

Specification of srbStart

This function is used to initialise an SRB session with the configuration files and environment variables on the calling machine. This or srbStartManual() must be called before any of the other functions in the API. Without calling either, the effects of the other functions are undefined.

[frame=single]
t_srb_session* srbStart(void)

Argument List

None

Return Values

NULL=failure,
Non-NULL= Connection successful; a pointer to the active session is returned, and can be closed by a call to srbEnd().

Specification of srbStartManual

This function is used to initialise an SRB session with a supplied set of credentials, rather than using the configuration files and environment variables on the calling machine. This or srbStart() must be called before any of the other functions in the API. Without calling either, the effects of the other functions are undefined.

[frame=single]
t_srb_session* srbStartManual(char* host, char* port, char* auth, char* user
                              char* domain, char* auth_scheme, char* server_dn)

Argument List

See SRB documentation for full details on acceptable contents for the parameters specified below.

host
On entry: Name of the SRB host to connect to.

port
On entry: Port number to connect to.

auth
On entry: Authorisation credential (usually a password).

user
On entry: User identification.

domain
On entry: SRB domain.

auth_scheme
On entry: Denotes the appropriate authorisation scheme, e.g. "`ENCRYPT1"'

server_dn
On entry: Server distinguished name.

Return Values

NULL=failure,
Non-NULL= Connection successful; a pointer to the active session is returned, and can be closed by a call to srbEnd().

Specification of srbEnd

Used to end the SRB session.

[frame=single]
void srbEnd(t_srb_session* session)

Argument List

session
On entry: Pointer to an SRB session.

Return Values

None

Specification of srbGetActiveConnectionPtr

This function will return a pointer to the active SRB connection, if there is one. It is provided in order to allow users to make direct calls to the underlying SDSC API if needed; virtually all such calls take a connection pointer as a parameter.

[frame=single]
srbConn* srbGetActiveConnectionPtr(t_srb_session* session)

Argument List

session
On entry: Pointer to an SRB session.

Return Values

NULL=no active connection
non-NULL=Pointer to the active connection

Specification of srbGetTransferBufferSize

This function is used to get the size of the buffer used in file reading and writing operations.

[frame=single]
int srbGetTransferBufferSize(t_srb_session* session)

Argument List

session
On entry: Pointer to an SRB session.

Return Values

Desired buffer size, in bytes.

Specification of srbSetTransferBufferSize

This function is used to set the size of the buffer used in file reading and writing operations. The buffer size can be increased to improve performance, or decreased if reading/writing functions are failing with BUFFER_SIZE_TOO_LARGE errors.

[frame=single]
void srbSetTransferBufferSize(t_srb_session* session, int size)

Argument List

session
On entry: Pointer to an SRB session.

destination
On entry: Desired buffer size, in bytes.

Return Values

None

Specification of srbCopyFile

This is used to copy a file already on the SRB system to another location within it.

[frame=single]
int srbCopyFile(t_srb_session *session, char *destination, char *source)

Argument List

session
On entry: Pointer to an SRB session.

destination
On entry: Fully qualified name of the destination file.

source
On entry: Fully qualified name of the source file.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
REMOTE_FILE_ERROR=There was a problem opening or creating a file on the SRB system,
0=Internal SRB failure.

Specification of srbDeleteFile

This function is used to delete an SRB file.

[frame=single]
int srbDeleteFile(t_srb_session *session, char *filename)

Argument List

session
On entry: Pointer to an SRB session.

filename
On entry: The fully-qualified name of the file.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.

Specification of srbFileInfo

This function allows you to obtain information on a file within SRB; e.g size, owner, etc.

[frame=single]
int srbFileInfo(t_srb_session* session, char **output, char *file, int field)

Argument List

session
On entry: Pointer to an SRB session.

file
On entry: Fully qualified name of the file being queried.

field
On entry: ID of the field being queried - see SRB Data Discovery API documentation for further details.

output
On exit: Pointer to a string containing the returned information, or NULL if an error occurred. This will need to be freed by the user.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.

Specification of srbGetFile

This is used to get a file from the SRB data store and save a copy on the local file system.

[frame=single]
int srbGetFile(t_srb_session *session, char *destination, char *source)

Argument List

session
On entry: Pointer to an SRB session.

destination
Filename (and pathname if necessary) of the local target file. If it does not already exist, it will be created.

source
On entry: Fully qualified name of the SRB file.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
BUFFER_SIZE_TOO_LARGE=the currently set transfer buffer size could not be allocated,
LOCAL_FILE_ERROR=There was a problem creating the file on the local file system,
REMOTE_FILE_ERROR=There was a problem opening the file on the SRB system,
0=Internal SRB failure.

Specification of srbPutFile

This is used to take a file from the local file system and upload a copy to the SRB system. If a file with the same name already exists at the specified location, it will be overwritten.

[frame=single]
int srbPutFile(t_srb_session *session, char *destination, char *source, char *container)

Argument List

session
On entry: Pointer to an SRB session.

destination
On entry: Fully qualified name of the target file. If it does not already exist, it will be created.

source
On entry: Name and path (if necessary) of local file

container
On entry: Currently unused; supply a NULL pointer for this parameter.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
BUFFER_SIZE_TOO_LARGE=the currently set transfer buffer size could not be allocated,
LOCAL_FILE_ERROR=There was a problem reading the file on the local file system,
REMOTE_FILE_ERROR=There was a problem writing to the file on the SRB system,
0=Internal SRB failure.

Specification of srbRenameFile

This function is used to rename a file within an SRB directory.

[frame=single]
int srbRenameFile(t_srb_session *session, char *old_name,char *new_name)

Argument List

session
On entry: Pointer to an SRB session.

old_name
On entry: The fully-qualified original name of the file.

new_name
On entry: The new name for the file (not including path).

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.

Specification of srbSetFileType

This function allows you to set a metadata entry for a file indicating the exact file type, e.g. PDF document, TAR archive, etc.

[frame=single]
int srbFileInfo(t_srb_session *session, char *file, char* type)

Argument List

session
On entry: Pointer to an SRB session.

file
On entry: Fully qualified name of the file being modified.

type
On entry: String holding type name. The list of valid strings is controlled by your system administrator.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
0=Internal SRB failure.

Specification of srbCreateDirectory

This is used to create a directory on the SRB server.

[frame=single]
int srbCreateDirectory(t_srb_session *session, char* directory)

Argument List

session
On entry: Pointer to an SRB session.

directory
On entry: Fully qualified name of the directory to be created

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
0=Internal SRB failure.

Specification of srbGetDirectory

This function is used to take an SRB directory and download a copy to the local file system.

[frame=single]
int srbGetDirectory(t_srb_session *session, char* destination, char *source)

Argument List

session
On entry: Pointer to an SRB session.

destination
On entry: Path to the target directory. If it does not already exist, it will be created.

source
On entry: Fully qualified pathname of the source directory.

Return Values

Always returns 0; due to limitations of the underlying API, success and failure cannot be determined with return values. In the event of bug fixes at the lower level, the API will be updated accordingly.

Specification of srbPutDirectory

This function takes the specified source directory on the local file system and uploads it onto the SRB server.

[frame=single]
int srbPutDirectory(t_srb_session *session, char* destination, char *source)

Argument List

session
On entry: Pointer to an SRB session.

destination
On entry: Fully qualified path to the target directory. If it does not already exist, it will be created.

source
On entry: Pathname of the directory to be uploaded.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
BUFFER_SIZE_TOO_LARGE=the currently set transfer buffer size could not be allocated,
LOCAL_FILE_ERROR=There was a problem reading a file or folder on the local file system,
REMOTE_FILE_ERROR=There was a problem writing a file or directory on the SRB system,
0=Internal SRB failure.

Specification of srbDeleteDirectory

This is used to delete a directory on the SRB server, including all subdirectories.

[frame=single]
int srbDeleteDirectory(t_srb_session *session, char* directory)

Argument List

session
On entry: Pointer to an SRB session.

directory
On entry: Fully qualified name of the directory to be deleted

Return Values

Always returns 0; due to limitations of the underlying API, success and failure cannot be determined with return values. In the event of bug fixes at the lower level, the API will be updated accordingly.

Specification of srbRenameDirectory

This function is used to rename an SRB directory.

[frame=single]
int srbRenameDirectory(t_srb_session *session, char *old_name,char *new_name)

Argument List

session
On entry: Pointer to an SRB session.

old_name
On entry: The fully-qualified original name of the directory.

new_name
On entry: The new name for the directory (not including path).

Return Values

0=success
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.

Specification of srbDirectoryInfo

This function allows you to obtain information on a directory within SRB.

[frame=single]
int srbDirectoryInfo(t_srb_session *session, char **output, char *directory, int field)

Argument List

session
On entry: Pointer to an SRB session.

directory
On entry: Fully qualified name of the file being queried.

field
On entry: ID of the field being queried - see SRB Data Discovery API documentation for further details.

output
On exit: Pointer to a string containing the returned information, or NULL if an error occurred. This will need to be freed by the user.

Return Values

0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.

Specification of srbSetCurrResource

This function is used to specify the preferred SRB resource for file creation and writing operations.

[frame=single]
int srbSetCurrResource(t_srb_session *session, char* resource)

Argument List

session
On entry: Pointer to an SRB session.

resource
On entry: The name of the resource to be used. If a NULL pointer is supplied, operations will be carried out on the default resource (specified as the environment variable defaultResource.

Return Values

0=success,
OUT_OF_MEMORY=a call to malloc() inside the function failed.

Specification of srbGetCurrResource

This function is used to find which SRB resource is currently being used for file creation and writing operations.

[frame=single]
char* srbGetCurrResource(t_srb_session *session)

Argument List

session
On entry: Pointer to an SRB session.

Return Values

A pointer to a string containing the name of the current resource. This should not be freed by the caller. A NULL pointer or an empty string indicates that there is no resource currently specified.

Example

The example below shows a typical set of commands being carried out; upload and download operations for both files and directories, directory creation, and retrieving file information.

[frame=single]
#include <stdio.h>
#include "srbClient.h"
#include "growl_srb.h"

// Replace below definitions
#define SRB_HOME_DIRECTORY "/home/alb23.eminerals"
#define DEFAULT_RESOURCE "CCLRCFS"
#define EXISTING_FILE "myfile.txt"

int main(void) {
  int status;
  char* string_pointer;
  t_srb_session* session;
  
//Initialise the session
  session=srbStart();
  
/*or, for example...
  session=srbStart("`eminerals.dl.ac.uk"',"'5544"',"'my_password"',"'my_user"',"'minerals,
                   "`ENCRYPT1"',"'"')
*/
  
  if(null!=session) {

// Set the resource for file creation; otherwise the environment
// variable defaultResource is used. 
    srbSetCurrResource(session, DEFAULT_RESOURCE);
    
// Set the transfer block size to 64KB. Without this line, default
// buffer size 
    srbSetTransferBufferSize(session, 65536);
    
//Start by uploading a local file to the root of the home directory 
    status=srbPutFile(session,SRB_HOME_DIRECTORY "/uploaded_file",EXISTING_FILE,NULL);
    if(0==status) {
      printf(SRB_HOME_DIRECTORY "/uploaded_file was uploaded successfully.\n");
      
// Show some information on this file
      srbFileInfo(session,&string_pointer, SRB_HOME_DIRECTORY "/uploaded_file",
                  SIZE);
      printf("File size = %s bytes\n",string_pointer);
      free(string_pointer);
      srbFileInfo(session,&string_pointer, SRB_HOME_DIRECTORY "/uploaded_file",
                  DATA_OWNER);
      printf("Data owner = %s\n",string_pointer);
      free(string_pointer);
    
// Download the same file but store it under a different name
      status=srbGetFile(session,"downloaded_file", SRB_HOME_DIRECTORY "/uploaded_file");
      if(0==status) {
        printf(SRB_HOME_DIRECTORY "/uploaded_file was downloaded
               successfully as \"downloaded_file\".\n"); 
        
// Create an SRB directory and put some files into it.
        status=srbCreateDirectory(session,SRB_HOME_DIRECTORY "/created_directory");
        if(0==status) {
// assume all of these uploads work; these are just for illustration
//        really 
          (void)srbPutFile(session,SRB_HOME_DIRECTORY
                   "/created_directory/file1",EXISTING_FILE,NULL); 
          (void)srbPutFile(session,SRB_HOME_DIRECTORY
                   "/created_directory/file2",EXISTING_FILE,NULL); 
          (void)srbPutFile(session,SRB_HOME_DIRECTORY
                   "/created_directory/file3",EXISTING_FILE,NULL); 
          (void)srbPutFile(session,SRB_HOME_DIRECTORY
                   "/created_directory/file4",EXISTING_FILE,NULL); 
          
// as documented, the function below always returns a success value, so
// we ignore this return too. 
          (void)srbGetDirectory(session,"./downloaded_directory",
                   SRB_HOME_DIRECTORY "/created_directory"); 
          
// this function does return proper status values, but in this
// example, if it fails here we're not going to handle it.
          (void)srbPutDirectory(session,SRB_HOME_DIRECTORY
                   "/uploaded_directory","./downloaded_directory"); 
          (void)srbRenameDirectory(session,SRB_HOME_DIRECTORY
                  "/uploaded_directory",SRB_HOME_DIRECTORY
                  "/renamed_directory");  
        } else {
          printf("Directory creation failed, status = %d\n",status);
        }
      } else {
        printf("File download failed, status = %d\n",status);  
      }
    } else {
      printf("File upload failed, status = %d\n",status);
    }
  }

// close down the session  
  srbEnd(session);
  return status;
}

Rob Allan 2009-11-10