This chapter describes a set of client routines to access the functionality of 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.
Version: 1.0e
Public calls: srbStart; 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 (libSrbClient.a)
Date: 2005
Origin: A.L. Braimah, CCLRC Daresbury Laboratory
Language: C
Conditions on external use: Standard, see separate chapter
You will need to statically link your program with growl_srb.a and libSrbClient.a, the correct PORTNAME_ compile flag must be defined (see SRB documentation). Your calling code must #include the files srbClient.h and then growl_srb.h.
This function is used to initialise an SRB session and must be called before any of the other functions in the API. Without calling this, the effects of the other functions are undefined.
[frame=single] int srbStart(void)
None
0=success,
ALREADY_CONNECTED=There is already an active connection which
must be closed by srbEnd(),
CONNECTION_ERROR=Failed to connect
Used to end the SRB session.
[frame=single] void srbEnd(void)
None
None
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(void)
None
NULL=no active connection
non-NULL=Pointer to the active connection
This function is used to get the size of the buffer used in file reading and writing operations.
[frame=single] int srbGetTransferBufferSize(void)
None
Desired buffer size, in bytes.
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(int size)
destination
On entry: Desired buffer size, in bytes.
None
This is used to copy a file already on the SRB system to another location within it.
[frame=single] int srbCopyFile(char *destination, char *source)
destination
On entry: Fully qualified name of the destination file.
source
On entry: Fully qualified name of the source file.
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.
This function is used to delete an SRB file.
[frame=single] int srbDeleteFile(char *filename)
filename
On entry: The fully-qualified name of the file.
0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.
This function allows you to obtain information on a file within SRB; e.g size, owner, etc.
[frame=single] int srbFileInfo(char **output, char *file, int field)
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.
0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function
failed,
0=Internal SRB failure.
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(char* destination, char *source)
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.
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.
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(char* destination, char *source, char *container)
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.
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.
This function is used to rename a file within an SRB directory.
[frame=single] int srbRenameFile(char *old_name,char *new_name)
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).
0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.
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(char *file, char* type)
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.
0=success,
BAD_PARAMETERS=invalid inputs to function,
0=Internal SRB failure.
This is used to create a directory on the SRB server.
[frame=single] int srbCreateDirectory(char* directory)
directory
On entry: Fully qualified name of the directory to be created
0=success,
BAD_PARAMETERS=invalid inputs to function,
0=Internal SRB failure.
This function is used to take an SRB directory and download a copy to the local file system.
[frame=single] int srbGetDirectory(char* destination, char *source)
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.
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.
This function takes the specified source directory on the local file system and uploads it onto the SRB server.
[frame=single] int srbPutDirectory(char* destination, char *source)
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.
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.
This is used to delete a directory on the SRB server, including all subdirectories.
[frame=single] int srbDeleteDirectory(char* directory)
directory
On entry: Fully qualified name of the directory to be deleted
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.
This function is used to rename an SRB directory.
[frame=single] int srbRenameDirectory(char *old_name,char *new_name)
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).
0=success
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function failed,
0=Internal SRB failure.
This function allows you to obtain information on a directory within SRB.
[frame=single] int srbDirectoryInfo(char **output, char *directory, int field)
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.
0=success,
BAD_PARAMETERS=invalid inputs to function,
OUT_OF_MEMORY=a call to malloc() inside the function
failed,
0=Internal SRB failure.
This function is used to specify the preferred SRB resource for file creation and writing operations.
[frame=single] int srbSetCurrResource(char* resource)
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.
0=success,
OUT_OF_MEMORY=a call to malloc() inside the function
failed.
This function is used to find which SRB resource is currently being used for file creation and writing operations.
[frame=single] char* srbGetCurrResource(void)
None
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.
Workspace: none
Use of globals: none
Other routines called directly: none
Input/ output: none
Restrictions: Only one SRB connection can be active at once per
program compiled with this library.
Notes:
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;
//Initialise the session
status=srbStart();
if(0==status) {
// Set the resource for file creation; otherwise the environment
// variable defaultResource is used.
srbSetCurrResource(DEFAULT_RESOURCE);
// Set the transfer block size to 64KB. Without this line, default
// buffer size
srbSetTransferBufferSize(65536);
//Start by uploading a local file to the root of the home directory
status=srbPutFile(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(&string_pointer, SRB_HOME_DIRECTORY "/uploaded_file",
SIZE);
printf("File size = %s bytes\n",string_pointer);
free(string_pointer);
srbFileInfo(&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("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(SRB_HOME_DIRECTORY "/created_directory");
if(0==status) {
// assume all of these uploads work; these are just for illustration
// really
(void)srbPutFile(SRB_HOME_DIRECTORY
"/created_directory/file1",EXISTING_FILE,NULL);
(void)srbPutFile(SRB_HOME_DIRECTORY
"/created_directory/file2",EXISTING_FILE,NULL);
(void)srbPutFile(SRB_HOME_DIRECTORY
"/created_directory/file3",EXISTING_FILE,NULL);
(void)srbPutFile(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("./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(SRB_HOME_DIRECTORY
"/uploaded_directory","./downloaded_directory");
(void)srbRenameDirectory(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();
return status;
}
