The Storage Resource Manager
Interface Specification

Version 2.2

 

 

25 September 2009

 

 

Collaboration Web:

http://sdm.lbl.gov/srm-wg

Document Location:

http://sdm.lbl.gov/srm-wg/doc/SRM.v2.2.html

 

Editors:

Alex Sim

Lawrence Berkeley National Laboratory

Arie Shoshani

Lawrence Berkeley National Laboratory

 

Authors/Contributors:

Paolo Badino

Olof Barring

Jean-Philippe Baud

Flavia Donno

Maarten Litmaath

European Organization for Nuclear Research (CERN), Switzerland

Timur Perelmutov

Don Petravick

Fermi National Accelerator Laboratory (FNAL), USA

Ezio Corso

Luca Magnoni

International Centre for Theoretical Physics (ICTO), Italy

Istituto Nazionale di Fisica Nucleare (INFN), Italy

Junmin Gu

Lawrence Berkeley National Laboratory (LBNL), USA

Shaun De Witt

Jens Jensen

Rutherford Appleton Laboratory (RAL), England

Michael Haddox-Schatz

Bryan Hess

Andy Kowalski
Chip Watson

Thomas Jefferson National Accelerator Facility (TJNAF), USA

 

 


Table of Contents

 

Abstract. 5

Introduction.. 5

1. Common Type Definitions.. 7

1.1. Meaning of terms.. 7

1.2. File Storage Type.. 7

1.3. File Type.. 8

1.4. Retention Policy.. 8

1.5. Access Latency.. 8

1.6. Permission Mode.. 8

1.7. Permission Type.. 9

1.8. Request Type.. 9

1.9. Overwrite Mode.. 9

1.10. File Locality.. 9

1.11. Access Pattern.. 10

1.12. Connection Type.. 10

1.13. Status Codes.. 10

1.14. Retention Policy Info.. 11

1.15. Request Token.. 11

1.16. User Permission.. 11

1.17. Group Permission.. 11

1.18. Size in Bytes.. 11

1.19. UTC Time.. 12

1.20. Time in Seconds (Lifetime and RequestTime). 12

1.21. SURL.. 12

1.22. TURL.. 12

1.23. Return Status.. 12

1.24. Return Status for SURL.. 12

1.25. File MetaData.. 13

1.26. Space MetaData.. 13

1.27. Directory Option.. 14

1.28. Extra Info.. 14

1.29. Transfer Parameters.. 14

1.30. File Request for srmPrepareToGet. 15

1.31. File Request for srmPrepareToPut. 15

1.32. File Request for srmCopy.. 15

1.33. Return File Status for srmPrepareToGet. 15

1.34. Return File Status for srmBringOnline.. 15

1.35. Return File Status for srmPrepareToPut. 15

1.36. Return File Status for srmCopy.. 16

1.37. Request Summary.. 16

1.38. Return Status for SURL.. 16

1.39. Return File Permissions.. 17

1.40. Return Permissions on SURL.. 17

1.41. Return Request Tokens.. 17

1.42. Supported File Transfer Protocol. 17

2. Space Management Functions.. 18

2.1. srmReserveSpace.. 18

2.2. srmStatusOfReserveSpaceRequest. 20

2.3. srmReleaseSpace.. 21

2.4. srmUpdateSpace.. 23

2.5. srmStatusOfUpdateSpaceRequest. 24

2.6. srmGetSpaceMetaData.. 25

2.7. srmChangeSpaceForFiles.. 26

2.8. srmStatusOfChangeSpaceForFilesRequest. 29

2.9. srmExtendFileLifeTimeInSpace.. 31

2.10. srmPurgeFromSpace.. 32

2.11. srmGetSpaceTokens.. 34

3. Permission Functions.. 36

3.1. srmSetPermission.. 36

3.2. srmCheckPermission.. 37

3.3. srmGetPermission.. 38

4. Directory Functions.. 40

4.1. srmMkdir.. 40

4.2. srmRmdir.. 40

4.3. srmRm.... 41

4.4. srmLs.. 43

4.5. srmStatusOfLsRequest. 45

4.6. srmMv.. 47

5. Data Transfer Functions.. 49

5.1. srmPrepareToGet. 49

5.2. srmStatusOfGetRequest. 52

5.3. srmBringOnline.. 55

5.4. srmStatusOfBringOnlineRequest. 59

5.5. srmPrepareToPut. 61

5.6. srmStatusOfPutRequest. 65

5.7. srmCopy.. 68

5.8. srmStatusOfCopyRequest. 72

5.9. srmReleaseFiles.. 75

5.10. srmPutDone.. 77

5.11. srmAbortRequest. 78

5.12. srmAbortFiles.. 80

5.13. srmSuspendRequest. 81

5.14. srmResumeRequest. 82

5.15. srmGetRequestSummary.. 83

5.16. srmExtendFileLifeTime.. 84

5.17. srmGetRequestTokens.. 86

6. Discovery Functions.. 87

6.1. srmGetTransferProtocols.. 87

6.2. srmPing.. 87

7. Storage Resource Managers Concepts.. 89

7.1. Summary.. 89

7.2. Overview... 89

7.3. The Basic Concepts.. 90

7.4. Additional concepts introduced with v2.2.. 92

7.5. SRM Implementations.. 94

8. Appendix I : Current SRM Implementations Based on v2.2 specification.. 96

8.1. BeStMan – Berkeley Storage Manager.. 96

8.2. Castor-SRM... 96

8.3. dCache-SRM... 97

8.4. DPM – Disk Pool Manager.. 97

8.5. StoRM - Storage Resource Manager.. 97

9. Appendix II : WLCG use case.. 97

Introduction.. 97

9.1. Storage classes.. 98

9.2. Removal policies.. 99

9.3. Protocol negotiation.. 99

9.4. Information discovery.. 99

9.5. srmReserveSpace.. 99

9.6. srmChangeSpaceForFiles.. 99

9.7. srmPurgeFromSpace.. 100

9.8. srmRm.... 100

9.9. srmLs.. 100

9.10. srmPrepareToGet. 101

9.11. srmBringOnline.. 101

9.12. srmPrepareToPut. 102

9.13. srmCopy.. 102

10. Contributors.. 103

11. Acknowledgement. 103

12. Copyright Notice.. 103

13. OGF Disclaimer.. 104

14. OGF Intellectual Property Statement. 104

15. OGF Copyright Notice.. 104

16. References.. 104

17. Revision History.. 105

17.1. From 080925 version to 090925.. 105

 

 


Abstract

 

Storage management is one of the most important enabling technologies for large-scale scientific investigations. Having to deal with multiple heterogeneous storage and file systems is one of the major bottlenecks in managing, replicating, and accessing files in distributed environments. Storage Resource Managers (SRMs), named after their web services protocol, provide the technology needed to manage the rapidly growing distributed data volumes, as a result of faster and larger computational facilities. SRMs are Grid storage services providing interfaces to storage resources, as well as advanced functionality such as dynamic space allocation and file management on shared storage systems. They call on transport services to bring files into their space transparently and provide effective sharing of files. SRMs are based on a common specification that emerged over time and evolved into an international collaboration. This approach of an open specification that can be used by various institutions to adapt to their own storage systems has proven to be a remarkable success – the challenge has been to provide a consistent homogeneous interface to the Grid, while allowing sites to have diverse infrastructures. In particular, one of the main goals to the SRM web service is to support optional features while preserving interoperability.

 

Introduction

 

This document contains the concepts and interface specification of SRM 2.2. It incorporates the functionality of SRM 2.0 and SRM 2.1, but is much expanded to include additional functionality, especially in the area of dynamic storage space reservation and directory functionality in client-acquired storage spaces.

 

This document reflects the discussions and conclusions of a 2-day meeting in May 2006 at Fermilab, which followed by a 3-day meeting in September 2006 at CERN. Since that time several smaller meetings have taken place as well as email correspondence and conference calls. The purpose of this activity is to agree on the functionality and standardize the interface of Storage Resource Managers (SRMs) – a Grid middleware component.

This document reflects the current status of the specification, which has been frozen in order to allow multiple implementations to proceed.

 

The document is organized in seven sections. The first describes the main concepts of SRMs as a standard middleware specification for various storage systems. It is intended to support the same interface to simple files systems, as well as sophisticated storage system that include multiple disk caches, robotic tape systems, and parallel file systems.The second, called “Common Type Definitions” contains all the type definitions used to define the functions (or methods). The next 5 sections contain the specification of “Space Management Functions”, “Permission Functions”, “Directory Functions”, “Data Transfer Functions” and “Discovery Functions”. All the “Discovery Functions” are newly added functions.

 

Appendix I lists several implementations of SRM v2.2 around the world, and their deployment in various sites.

 

As can be expected, when a large collaboration decide to use the SRM specification, it may choose to restrict some of the functionality according to their common projects requirements. For example, some collaboration may choose to restrict space reservations to administrators only, and not permit dynamic reservations by other users. Similarly, the collaboration may choose to support only permanent storage files, rather than allow automatic removal of files whose lifetime has expired by the SRM.

 

An interesting and influential collaboration is described in Appendix II. The collaboration is in the High Energy Physics domain, and it purpose is to develop the tools to managed the petabytes of data expected from the Large Hadron Collider (LHC). The collaboration, called Worldwide LHC Computing Grid (WLCG) project, involves implementing Storage Resource Managers on top of various storage systems based on the SRM v2.2 specification described here. Appendix II described the restrictions and behaviors the WLCG project has chosen in order to achieve interoperability of all SRM implementations under a tight time schedule. It is important to note that the WLCG collaboration also added enhancement in terms of functionality and clarity of the specification, an invaluable contribution based on practical requirements.

 

For people not familiar with SRM concepts, it is advisable to read the first chapter. For people familiar with previous versions of SRM specifications, it is advisable to read the document SRM.v2.2.changes.doc posted at http://sdm.lbl.gov/srm-wg before reading this specification.Another SRM-related activity that was recently published is to provide a formal conceptual model of the SRM behavior [ISGC2007].

 

This document is modified from OGF.129 for more readability towards funcional interfaces. OGF.129 document fixes many typos and includes some clarifications from the previous version (2 April 2007).

1. Common Type Definitions

 

NamespaceSRM

 

1.1. Meaning of terms

 

a)     Underlinedattributes are REQUIRED. The required attributes must be parsed correctly and must give proper error messages when not supported.

b)    By “https” we mean http protocol with GSI authentication. It may be represented as “httpg”. At this time, any implementation of http with GSI authentication could be used. It is advisable that the implementation is compatible with Globus Toolkit 3.2 or later versions.

c)     Primitive types used below are consistent with XML build-in schema types: i.e.

o   longis 64bit: (+/-) 9223372036854775807

o   intis 32 bit: (+/-) 2147483647

o   shortis 16 bit: (+/-) 32767

o   unsignedLongranges (inclusive): 0 to18446744073709551615

o   unsignedInt ranges (inclusive): 0 to 4294967295

o   unsignedShort ranges (inclusive):0 to 65535

d)    The definition of the type “anyURI” used below is compliant with the XML standard. See http://www.w3.org/TR/xmlschema-2/#anyURI. It is defined as: "The lexical space of anyURI is finite-length character sequences which, when the algorithm defined in Section 5.4 of [XML Linking Language] is applied to them, result in strings which are legal URIs according to [RFC 2396], as amended by [RFC 2732]".

e)     In “localSURL”, we mean local to the SRM that is processing the request.

f)      authorizationID : from the SASL RFC 2222
During the authentication protocol exchange, the mechanism performs authentication, transmits an authorization identity (frequently known as a userid) from the client to server…. The transmitted authorization identity may be different than the identity in the client’s authentication credentials. This permits agents such as proxy servers to authenticate using their own credentials, yet request the access privileges of the identity for which they are proxying. With any mechanism, transmitting an authorization identity of the empty string directs the server to derive an authorization identity from the client’s authentication credentials.

g)     Regarding file sharing by the SRM, it is a local implementation decision. An SRM can choose to share files by proving multiple users access to the same physical file, or by copying a file into another user’s space. Either way, if an SRM chooses to share a file (that is, to avoid reading a file over again from the source site) the SRM should check with the source site whether the user has a read/write permission. Only if permission is granted, the file can be shared.

h)    The word “pinning” is limited to the “copies” or “states” of SURLs and the Transfer URLs (TURLs).

i)      For each function, status codes are defined with basic meanings for the function. Only those status codes are valid for the function. Specific cases are not stated for each status code. If other status codes need to be defined for a specific function, send an email to the collaboration to discuss the usage.

 

 

1.2. File Storage Type

enum                       TFileStorageType         {VOLATILE, DURABLE, PERMANENT}

 

o   Volatile file has a lifetime and the storage may delete all traces of the file when it expires.

o   Permanent file has no expiration time.

o   Durable file has an expiration time, but the storage may not delete the file, and should raise error condition instead.

 

1.3. File Type

enum                       TFileType                             {FILE, DIRECTORY, LINK}

 

1.4. Retention Policy

enum                 TRetentionPolicy           { REPLICA , OUTPUT , CUSTODIAL }

 

o   Quality of Retention (Storage Class) is a kind of Quality of Service. It refers to the probability that the storage system lose a file. Numeric probabilities are self-assigned.

Š       Replica quality has the highest probability of loss, but is appropriate for data that can be replaced because other copies can be accessed in a timely fashion.

Š       Output quality is an intermediate level and refers to the data which can be replaced by lengthy or effort-full processes.

Š       Custodial quality provides low probability of loss.

o   The type is used to describe retention policy assigned to the files in the storage system, at the moments when the files are written into the desired destination in the storage system. It is used as a property of space allocated through the space reservation function. Once the retention policy is assigned to a space, the files put in the reserved space will automatically be assigned the retention policy of the space. The assigned retention policy on the file can be found through the TMetaDataPathDetail structure returned by the srmLs function.

 

1.5. Access Latency

enum                  TAccessLatency { ONLINE, NEARLINE }

 

o   These terms are used to describe how latency to access a file is improvable. Latency is improved by storage systems replicating a file such that its access latency is online.

Š       The ONLINE cache of a storage system is the part of the storage system which provides file with online latencies.

Š       ONLINE has the lowest latency possible. No further latency improvements are applied to online files.

Š       NEARLINE file can have their latency improved to online latency automatically by staging the file to online cache.

Š       For completeness, we also describe OFFLINE here.

Š       OFFLINE files need a human to be involved to achieve online latency.

o   The type will be used to describe a space property that access latency can be requested at the time of space reservation. The content of the space, files may have the same or “lesser” access latency as the space.

o   For the SRM, ONLINE and NEARLINE are specified, and files may be ONLINE and/or NEARLINE.

 

1.6. Permission Mode

enum                       TPermissionMode        {NONE, X, W, WX, R, RX, RW, RWX}

 

1.7. Permission Type

enum                       TPermissionType         {ADD, REMOVE, CHANGE}

 

1.8. Request Type

enum                       TRequestType                 { PREPARE_TO_GET,

                                                                                          PREPARE_TO_PUT,

                                                                                          COPY,

                                                                                          BRING_ONLINE,

                                                                                          RESERVE_SPACE,

                                                                                          UPDATE_SPACE,

                                                                                          CHANGE_SPACE_FOR_FILES,

LS}

 

1.9. Overwrite Mode

enum                       TOverwriteMode           {NEVER,

ALWAYS,

WHEN_FILES_ARE_DIFFERENT}

 

o   Use case for WHEN_FILES_ARE_DIFFERENT can be that files are different when the declared size for an SURL is different from the actual one, or that the checksum of an SURL is different from the actual one.

o   Overwrite mode on a file is considered higher priority than pinning a file. Where applicable, it allows to mark a valid Transfer URL to become invalid when the owner of the SURL issues an overwrite request.

 

1.10. File Locality

enum                  TFileLocality{ ONLINE,

                                    NEARLINE,

ONLINE_AND_NEARLINE,

LOST,

NONE.

UNAVAILABLE }

 

o   Files may be located online, nearline or both. This indicates if the file is online or not, or if the file reached to nearline or not. It also indicates if there are online and nearline copies of the file.

Š       The ONLINE indicates that there is a file on online cache of a storage system which is the part of the storage system, and the file may be accessed with online latencies.

Š       The NEARLINE indicates that the file is located on nearline storage system, and the file may be accessed with nearline latencies.

Š       The ONLINE_AND_NEARLINE indicates that the file is located on online cache of a storage system as well as on nearline storage system.

Š       The LOST indicates when the file is lost because of the permanent hardware failure.

Š       The NONE value shall be used if the file is empty (zero size).

Š       The UNAVAILABLE indicates that the file is unavailable due to the temporary hardware failure.

o   The type is used to describe a file property that indicates the current location or status in the storage system.

 

1.11. Access Pattern

enum                   TAccessPattern { TRANSFER_MODE, PROCESSING_MODE }

 

o   TAccessPattern may be passed as an input parameter to the srmPrepareToGet and srmBringOnline functions. It provides a hint from the client to SRM how the Transfer URL (TURL) produced by SRM is going to be used. If the parameter value is “ProcessingMode”, the system may expect that client application will perform some processing of the partially read data, followed by more partial reads and a frequent use of the protocol specific “seek” operation. This allows optimizations by allocating files on disks with small buffer sizes. If the value is “TransferMode” the file will be read at the highest speed allowed by the connection between the server and a client.

 

1.12. Connection Type

enum                  TConnectionType { WAN, LAN }

 

o   TConnectionType indicates if the client is connected though a local or wide area network. SRM may optimize the access parameters to achieve maximum throughput for the connection type. This input parameter may be passed to the srmPrepareToGet, srmPrepareToPut and srmBringOnline functions.

 

 

1.13. Status Codes

enum                       TStatusCode    { SRM_SUCCESS,

SRM_FAILURE,

                                                                                          SRM_AUTHENTICATION_FAILURE,

                                                                                          SRM_AUTHORIZATION_FAILURE,

                                                                                          SRM_INVALID_REQUEST,

                                                                                          SRM_INVALID_PATH,

                                                                                          SRM_FILE_LIFETIME_EXPIRED,

                                                                                          SRM_SPACE_LIFETIME_EXPIRED,

SRM_EXCEED_ALLOCATION,

                                                                                          SRM_NO_USER_SPACE,

                                                                                          SRM_NO_FREE_SPACE,

                                                                                          SRM_DUPLICATION_ERROR,

                                                                                          SRM_NON_EMPTY_DIRECTORY,

                                                                                          SRM_TOO_MANY_RESULTS,

                                                                                          SRM_INTERNAL_ERROR,

                                                                                          SRM_FATAL_INTERNAL_ERROR,

                                                                                          SRM_NOT_SUPPORTED,

                                                                                          SRM_REQUEST_QUEUED,

                                                                                          SRM_REQUEST_INPROGRESS,

                                                                                          SRM_REQUEST_SUSPENDED,

                                                                                          SRM_ABORTED,

                                                                                          SRM_RELEASED,

                                                                                          SRM_FILE_PINNED,

                                                                                          SRM_FILE_IN_CACHE,

                                                                                          SRM_SPACE_AVAILABLE,

                                                                                          SRM_LOWER_SPACE_GRANTED,

                                                                                          SRM_DONE,

                                                                                          SRM_PARTIAL_SUCCESS,

                                                                                          SRM_REQUEST_TIMED_OUT,

SRM_LAST_COPY,

SRM_FILE_BUSY,

SRM_FILE_LOST,

SRM_FILE_UNAVAILABLE,

SRM_CUSTOM_STATUS

}

 

o   SRM_NOT_SUPPORTED must be used, in general

Š       If a server does not support a method

Š       If a server does not support particular optional input parameters

 

 

1.14. Retention Policy Info

typedef                   struct { TRetentionPolicy                retentionPolicy,

                                                      TAccessLatency                accessLatency

                                    } TRetentionPolicyInfo

 

o   TRetentionPolicyInfo is a combined structure to indicate how the file needs to be stored.

o   When both retention policy and access latency are provided, their combination needs to match what SRM supports. Otherwise request must be rejected.

 

1.15. Request Token

 

o   The Request Token assigned by SRM is unique and immutable (non-reusable). For example, if the date:time is part of the request token it can be immutable.

o   Request tokens are case-sensitive.

o   Request token is valid until the request is completed. However, SRM may choose to keep the request tokens for a short period of time after the request is completed, and the time period depends on the SRM.

 

1.16. User Permission

typedef                   struct {                   string                                        userID,

                                                      TPermissionMode           mode

} TUserPermission

 

o   userID may represent the associated client’s Distinguished Name (DN) instead of unix style login name. VOMS role may be included.

 

1.17. Group Permission

typedef                   struct {                   string                                        groupID,

                                                      TPermissionMode           mode

} TGroupPermission

 

o   groupID may represent the associated client’s Distinguished Name (DN) instead of unix style login name. VOMS role may be included.

 

1.18. Size in Bytes

 

o   Size in bytes is represented in unsigned long.

 

1.19. UTC Time

 

o   Time is represented in dateTime.

o   Formerly TGMTTime in SRM v2.1

o   date and time in Coordinated Universal Time (UTC, formerly GMT) with no local time extention.

o   Format is same as in XML dateTime type [XSDDATE], except no local time extension is allowed. E.g. 1999-05-31T13:20:00 is ok (for 1999 May 31st, 13:20PM, UTC) but 1999-05-31T13:20:00-5:00 is not.

 

1.20. Time in Seconds (Lifetime and RequestTime)

 

o   Time (lifetime and request time) in seconds is represented in integer.

o   “0” (zero) indicates the site defined default time.

o   A negative value (-1) indicates “infinite (indefinite)” time.

o   Exceptions:

§  Any “remaining” times must have zero (0) second when no lifetime is left.

§  Some special meaning of negative time is defined when needed depending on the operation. E.g. remainingTotalRequestTime in srmStatusOfGetRequest

 

1.21. SURL

 

o   The type definition SURL is represented as anyURI and used for both site URL and the “Storage File Name” (stFN). This was done in order to simplify the notation. Recall that stFN is the file path/name of the intended storage location when a file is put (or copied) into an SRM controlled space. Thus, a stFN can be thought of a special case of an SURL, where the protocol is assumed to be “srm” and the machine:port is assumed to be local to the SRM. For example, when the request srmCopy is made as a pulling case, the source file is specified by a site URL, and the target location can be optionally specified as a stFN. By considering the stFN a special case of an SURL, a srmCopy takes SURLs as both the source and target parameters.

 

1.22. TURL

 

o   TURL is represented in anyURI.

 

1.23. Return Status

typedef struct {TStatusCode       statusCode,

                                                      string                      explanation

} TReturnStatus

 

1.24. Return Status for SURL

typedef                   struct {anyURI                   surl,

                                                      TReturnStatus                    status

} TSURLReturnStatus

 

 

1.25. File MetaData

 

typedef                   struct {string                                        path, // absolute dir and file path

                                                      TReturnStatus                                      status,

                                                      unsigned long                                        size, // 0 if directory

                                                      dateTime                                                  createdAtTime,

                                                      dateTime                                                  lastModificationTime,

                                                      TFileStorageType                               fileStorageType,

                                                      TRetentionPolicyInfo                      retentionPolicyInfo,

                                                      TFileLocality                                         fileLocality,

                                                      string[]                                                                        arrayOfSpaceTokens,

                                                      TFileType                                                type,       // Directory or File

int                                                                  lifetimeAssigned,

                                                      int                                                                  lifetimeLeft, // on the SURL

                                                      TUserPermission                               ownerPermission,

                                                      TGroupPermission                           groupPermission,

                                                      TPermissionMode                             otherPermission,

                                                      string                                                          checkSumType,

                                                      string                                                          checkSumValue,

TMetaDataPathDetail[]             arrayOfSubPaths // optional recursive

} TMetaDataPathDetail

 

o   The TMetaDataPathDetail describes the properties of a file. It is used as an output parameter in srmLs.

o   retentionPolicyInfo indicates the assigned retention policy.

o   fileLocality indicates where the file is located currently in the system.

o   arrayOfSpaceTokens as an array of string indicates where the file is currently located for the client. Only space tokens that the client has authorized to access to read the file must be returned.

o   Permissions on the SURL represent unix-like permissions: e.g. rwxr--r--.

o   ownerPermission describes the owner ID and owner permission on the SURL.

o   groupPermission describes the group permission with group identifier on the SURL.

o   otherPermission describes the other permission on the SURL.

o   For ACL-like permissions, srmGetPermission must be used.

o   lifetimeAssigned is the total lifetime that is assigned on the SURL. It includes all SURL lifetime extensions if extended.

o   lifetimeLeft is the remaining lifetime on the SURL from the current time until expiration.

Š       A negative value (-1) indicates “indefinite” lifetime.

Š       Zero (0) indicates that the file is expired.

 

1.26. Space MetaData

typedef                   struct { string                                                          spaceToken,      

                                                      TReturnStatus                                      status,

                                                      TRetentionPolicyInfo                      retentionPolicyInfo,

string                                                          owner,

                                                      unsigned long                                        totalSize,               // best effort

unsigned long                                        guaranteedSize,                                                     

unsigned long                                        unusedSize,

                                                      int                                                                  lifetimeAssigned,

                                                      int                                                                  lifetimeLeft

} TMetaDataSpace

 

o   TMetaDataSpace is used to describe properties of a space, and is used as an output parameter in srmGetSpaceMetaData.

o   retentionPolicyInfo indicates the information about retention policy and access latency that the space is assigned. retentionPolicyInfo is requested and assigned at the time of space reservation through srmReserveSpace and srmStatusOfReserveSpaceRequest.

o   TMetaDataSpace refers to a single space with retention policy. It does not include the extra space needed to hold the directory structures, if there is any.

o   lifetimeAssigned is the total lifetime that is assigned to the space. It includes all space lifetime extensions if extended.

o   lifetimeLeft is the remaining lifetime that is left on the space.

 

1.27. Directory Option

typedef                   struct {                   boolean                  isSourceADirectory,

                                                      boolean                  allLevelRecursive,            // default = false

                                                      int                              numOfLevels                        // default = 1

} TDirOption

 

1.28. Extra Info

typedef                   struct {                   string                      key,

                                                      string                      value

} TExtraInfo

 

o   TExtraInfo is used where additional information is needed, such as for additional information for transfer protocols of TURLs in srmPing, srmGetTransferProtocols, srmStatusOfGetRequest, and srmStatusOfPutRequest. For example, when it is used for additional information for transfer protocols, the keys may specify access speed, available number of parallelism, and other transfer protocol properties.

o   It is also used where additional information to the underlying storage system is needed, such as for storage device, storage login ID, storage login authorization, but not limited to. Formerly, it was TStorageSystemInfo.

 

1.29. Transfer Parameters

typedef                   struct {                   TAccessPattern                                                     accessPattern,

                                                      TConnectionType                              connectionType,

                                                      string[]                                                                        arrayOfClientNetworks,

                                                      string[]                                                                        arrayOfTransferProtocols

} TTransferParameters

 

o   TTransferParameters is used where arrayOfTransferProtocols was used previously in SRM v2.1.

o   TTransferParameters may be provided optionally in the methods such as srmPrepareToGet, srmBringOnline, srmPrepareToPut and srmReserveSpace. Optional input parameters in TTransferParameters may collide with the characteristics of the space specified. In this case, TTransferParameters as an input parameter must be ignored.

o   File transfer protocols must be specified in a preferred order on all SRM transfer functions.

o   arrayOfClientNetworks provides a hint of the client IPs that SRM/dCache may use for optimization of its internal storage systems based on the client’s accessible IP addresses.

 

1.30. File Request for srmPrepareToGet

typedef                   struct {                   anyURI                                                       sourceSURL,

TDirOption                           dirOption

} TGetFileRequest

 

1.31. File Request for srmPrepareToPut

typedef                   struct {                   anyURI                                     targetSURL,         // local to SRM 

                                                      unsigned long                      expectedFileSize

} TPutFileRequest

 

1.32. File Request for srmCopy

typedef                   struct {                   anyURI                                                       sourceSURL,

                                                      anyURI                                                       targetSURL,

TDirOption                           dirOption

} TCopyFileRequest

 

1.33. Return File Status for srmPrepareToGet

typedef struct {anyURI                                                       sourceSURL,                                          

                                                      TReturnStatus                    status,

                                                      unsigned long                      fileSize,

                                                      int                                                estimatedWaitTime,

int                                                remainingPinTime,

anyURI                                                       transferURL,

TExtraInfo[]                         transferProtocolInfo

} TGetRequestFileStatus

 

o   transferProtocolInfo of type TExtraInfo can provide more information about the transfer protocol so that client can access the TURL efficiently.

o   estimatedWaitTime must be negative value, -1, for unknown.

o   remainingPinTime is the lifetime on the TURL, and 0 means it expired. If a TURL has an indefinite lifetime, then negative value, -1, must be used.

 

1.34. Return File Status for srmBringOnline

typedef struct {anyURI                                                       sourceSURL,                                          

                                                      TReturnStatus                    status,

                                                      unsigned long                      fileSize,

                                                      int                                                estimatedWaitTime,

int                                                remainingPinTime

} TBringOnlineRequestFileStatus

 

o   estimatedWaitTime must be negative value, -1, for unknown.

o   remainingPinTime is the lifetime on the TURL, and 0 means it expired. If a TURL has an indefinite lifetime, then negative value, -1, must be used.

 

1.35. Return File Status for srmPrepareToPut

typedef struct { anyURI                                                      SURL,

                                                      TReturnStatus                    status,

unsigned long                      fileSize,

                                                      int                                                estimatedWaitTime,

int                                                remainingPinLifetime, // on TURL

int                                                remainingFileLifetime, // on SURL

anyURI                                                       transferURL,

                                                      TExtraInfo[]              transferProtocolInfo

} TPutRequestFileStatus

 

o   transferProtocolInfo of type TExtraInfocan provide more information about the prepared transfer protocol so that client may use the information to make an efficient access to the prepared TURL through the transfer protocol.

o   estimatedWaitTime must be negative value, -1, for unknown.

o   remainingPinTime is the lifetime on the TURL, and 0 means it expired. If a TURL has indefinite lifetime, then negative value, -1, must be used.

o   remainingFileLifetime is the lifetime on the SURL, and 0 means it expired. If SURL has an indefinite lifetime, then negative value, -1, must be used.

 

1.36. Return File Status for srmCopy

typedef struct {anyURI                                                       sourceSURL,      

                                                      anyURI                                                       targetSURL,                                            

                                                      TReturnStatus                    status,

                                                      unsigned long                      fileSize,

                                                      int                                                estimatedWaitTime,

int                                                remainingFileLifetime // on target SURL

} TCopyRequestFileStatus

 

o   estimatedWaitTime must be negative value, -1, for unknown.

o   remainingFileLifetime is the lifetime on the SURL, and 0 means it expired. If SURL has an indefinite lifetime, then negative value, -1, must be used.

 

1.37. Request Summary

typedef struct {string                                        requestToken,

                                                      TReturnStatus                    status,

                                                      TRequestType                    requestType,

                                                      int                                                totalNumFilesInRequest,

                                                      int                                                numOfCompletedFiles,

                                                      int                                                numOfWaitingFiles,

                                                      int                                                numOfFailedFiles

} TRequestSummary

 

o   numOfWaitingFiles describes the number of files on the queue.

o   numOfFailedFiles describes the number of failed files and aborted files.

o   numOfCompletedFiles describes the number of successfully completed files, number of failed files and number of aborted files.

o   totalNumFilesInRequest describes the numOfWaitingFiles, numOfCompletedFiles, numOfFailedFiles and number of files in progress.

 

1.38. Return Status for SURL

typedef                   struct {                   anyURI                                                       surl,

                                                      TReturnStatus                                      status,

                                                      int                                                fileLifetime,

                                                      int                                                pinLifetime,

} TSURLLifetimeReturnStatus

 

o   fileLifetime describes the file lifetime on SURL.

o   pinLifetime describes the pin lifetime on TURL, if applicable.

 

 

1.39. Return File Permissions

typedef struct {anyURI                                     surl,

                                                      TReturnStatus                                      status,

                                                      TPermissionMode           permission

} TSURLPermissionReturn

 

1.40. Return Permissions on SURL

typedef                   struct {anyURI                                                       surl, // both dir and file

                                                      TReturnStatus                                      status,

                                                      string                                                          owner,

                                                      TPermissionMode                             ownerPermission,

TUserPermission[]                           arrayOfUserPermissions,

TGroupPermission[]                       arrayOfGroupPermissions,

TPermissionMode                             otherPermission

} TPermissionReturn

 

o   The TPermissionReturn describes the permission properties of a file. It is used as an output parameter in srmGetPermission.

 

1.41. Return Request Tokens

typedef                   struct {                   string                                        requestToken,

                                                      dateTime                                createdAtTime

} TRequestTokenReturn

 

1.42. Supported File Transfer Protocol

typedef struct {string                                           transferProtocol,

                                                      TExtraInfo[]                         attributes

} TSupportedTransferProtocol

 

o   transferProtocol (required): Supported transfer protocol. For example, gsiftp, http.

o   attributes:Informational hints for the paired transfer protocol, such how many number of parallel streams can be used, desired buffer size, etc.

 


2. Space Management Functions

 

summary:

                  srmReserveSpace

                  srmStatusOfReserveSpaceRequest

                  srmReleaseSpace

                  srmUpdateSpace

srmGetSpaceMetaData

srmChangeSpaceForFiles

srmStatusOfChangeSpaceForFilesRequest

srmExtendFileLifeTimeInSpace

srmPurgeFromSpace

srmGetSpaceTokens

 

2.1. srmReserveSpace

                 

This function is used to reserve a space in advance for the upcoming requests to get some guarantee on the file management. Asynchronous space reservation may be necessary for some SRMs.

 

2.1.1. Parameters

 

                  In:            string                                                          authorizationID,

string                                                          userSpaceTokenDescription,

                                    TRetentionPolicyInfo                      retentionPolicyInfo,

unsigned long                                        desiredSizeOfTotalSpace,

unsigned long                                        desiredSizeOfGuaranteedSpace,

int                                                                  desiredLifetimeOfReservedSpace,

unsigned long []                                   arrayOfExpectedFileSizes,

TExtraInfo[]                                           storageSystemInfo,

TTransferParameters                     transferParameters

 

                  Out:        TReturnStatus                                      returnStatus,

string                                                          requestToken,

                                    int                                                                  estimatedProcessingTime,

                                    TRetentionPolicyInfo                      retentionPolicyInfo,

unsigned long                                        sizeOfTotalReservedSpace,          // best effort

unsigned long                                        sizeOfGuaranteedReservedSpace,

int                                                                  lifetimeOfReservedSpace,

string                                                          spaceToken

 

 

2.1.2. Notes on the Behavior

a)     Input parameter userSpaceTokenDescription is case-sensitive. SRM is expected to keep it as client provides. It can be reused by the client. srmGetSpaceTokensmust return all the space tokens that have the same userSpaceTokenDescription.

b)    If the input parameter desiredLifetimeOfReservedSpace is not provided, the lifetime of the reserved space may be set to “infinite (indefinite)” by default, if indefinite lifetime on space is supported by the implementation and local policy.

c)     If particular values of the input parameter retentionPolicyInfo cannot be satisfied by the SRM, SRM_NOT_SUPPORTED or SRM_NO_FREE_SPACE must be returned.

d)    Asynchronous space reservation may be necessary for some SRMs to serve many concurrent requests. In such case, request token must be returned, and space token must not be assigned and returned until space reservation is completed, to prevent the usage of the space token in other interfaces before the space reservation is completed. If the space reservation can be done immediately, request token must not be returned.

e)     When asynchronous space reservation is necessary, the returned status code must be SRM_REQUEST_QUEUED.

f)      Input parameter arrayOfExpectedFileSizeprovides a hint that SRM may use to reserve consecutive storage sizes for the request. At the time of space reservation, if space accounting is done only at the level of the total size, this hint would not help. In such case, the expected file size at the time of srmPrepareToPut providesinformation on how much consecutive storage size is needed for the file. However, some SRMs may get benefits from these hints to make a decision to allocate some blocks in some specific devices.

g)     Optional input parameter storageSystemInfo is needed in case the underlying storage system requires additional access information.

h)    SRM may return its default space size and lifetime if not requested by the client. SRM must return SRM_INVALID_REQUEST if SRM does not support default space sizes.

i)      If input parameter desiredSizeOfTotalSpace is not specified, the SRM may return its default space size.

j)      Output parameter estimateProcessingTime is used to indicate the estimation time to complete the space reservation request, when known.

k)    Output parameter sizeOfTotalReservedSpace is in best effort bases. For guaranteed space size, sizeOfGuaranteedReservedSpace should be checked. These two numbers may match, depending on the storage systems.

l)      Output parameter spaceToken is a reference handle of the reserved space.

m)   If an operation is successful (SRM_SUCCESS or SRM_LOWER_SPACE_GRANTED), sizeOfGuaranteedReservedSpace, lifetimeOfReservedSpace and spaceTokenmust be returned to the client.

n)    Optional input parameters in TTransferParameters may collide with the characteristics of the space specified. In this case, TTransferParameters as an input parameter must be ignored.

 

2.1.3. Return Status Code

SRM_SUCCESS

§  successful request completion. Space is reserved successfully as the client requested.

SRM_REQUEST_QUEUED

§  successful request submission and acceptance. Request token must be returned, and space token must not be assigned and returned.

SRM_REQUEST_INPROGRESS

§  request is being processed.

SRM_LOWER_SPACE_GRANTED

§  successful request completion, but lower space size is allocated than what the client requested

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to reserve space

SRM_INVALID_REQUEST

§  If space size or lifetime is not requested by the client, and SRM does not support default values for space size or lifetime.

§  Some input parameters are invalid.

SRM_NO_USER_SPACE

§  SRM does not have enough user space for the client to reserve.

SRM_NO_FREE_SPACE

§  SRM does not have enough free space for client to reserve.

§  SRM does not have enough free space for the requested retentionPolicyInfo to reserve

SRM_EXCEED_ALLOCATION

§  SRM does not have enough space for the request because the client requests more than the allocated space quota for the client.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  specific values of the input parameter retentionPolicyInfo is not supported by the SRM

§  a specified input parameter is not supported in the SRM

 

 

2.2. srmStatusOfReserveSpaceRequest

 

This function is used to check the status of the previous request to srmReserveSpace, when asynchronous space reservation is necessary with the SRM. Request token must have been provided in response to the previous call for srmReserveSpace.

 

2.2.1. Parameters

 

                  In:            string                                                          authorizationID,

                                    string                                                          requestToken

 

                  Out:        TReturnStatus                                      returnStatus,

int                                                                  estimatedProcessingTime,

                                    TRetentionPolicyInfo                      retentionPolicyInfo,

unsigned long                                        sizeOfTotalReservedSpace,

unsigned long                                        sizeOfGuaranteedReservedSpace,

int                                                                  lifetimeOfReservedSpace,

string                                                          spaceToken

 

 

2.2.2. Notes on the Behavior

a)     If the space reservation is not completed yet, estimateProcessingTimemay be returned when known. The returned status code in such case should be SRM_REQUEST_QUEUED.

b)    See notes for srmReserveSpace for descriptions for output parameters.

c)     If an operation is successful (SRM_SUCCESS or SRM_LOWER_SPACE_GRANTED), sizeOfGuaranteedReservedSpace, lifetimeOfReservedSpace and spaceTokenmust be returned to the client.

 

2.2.3. Return Status Code

SRM_REQUEST_QUEUED

§  successful request submission and the request is still on the queue to be served.

SRM_REQUEST_INPROGRESS

§  the request is being processed.

SRM_LOWER_SPACE_GRANTED

§  successful request completion, but lower space size is allocated than what the client requested

SRM_SUCCESS

§  successful request completion. Space is reserved successfully as the client requested.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to reserve space

SRM_INVALID_REQUEST

§  requestToken does not refer to an existing known request in the SRM.

SRM_EXCEED_ALLOCATION

§  SRM does not have enough space for the request because the client requestsmore than the allocated space for the client.

SRM_NO_USER_SPACE

§  SRM does not have enough user space for the client to reserve.

SRM_NO_FREE_SPACE

§  SRM does not have enough free space for the client to reserve.

§  SRM does not have enough free space for a particular retentionPolicyInfo to reserve

SRM_REQUEST_SUSPENDED

§  request is suspended.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  a specified input parameter is not supported in the SRM

 

 

2.3. srmReleaseSpace

 

srmReleaseSpace() releases an occupied space.

 

2.3.1. Parameters

 

                  In:            string                                        authorizationID,

string                                        spaceToken,

TExtraInfo[]                         storageSystemInfo,

                                    boolean                                    forceFileRelease

 

Out:        TReturnStatus                    returnStatus

 

 

2.3.2. Notes on the Behavior

a)     Inputparameter forceFileReleasemust be false by default. This means that the space will not be released if it has files that are still pinned in the space. To release the space regardless of the files it contains and their status forceFileRelease must be specified to be true.

b)    When space is releasable and forceFileRelease is true, all the files in the space must be released, even in OUTPUT or CUSTODIAL retention quality space.

c)     srmReleaseSpace may not complete right away because of the lifetime of existing files in the space. When space is released, the files in that space are treated according to their types: If file storage types are permanent, keep them until further operation such as srmRm is issued by the client. If file storage types are durable, perform necessary actions at the end of their lifetime. If file storage types are volatile, those files are released at the end of their lifetime.

d)    If space is being released with forceFileRelease option while SURLs are being created with srmPrepareToPut or srmCopy, the file must be removed and SRM_INVALID_PATH must be returned by the srmPutDone, srmStatusOfPutRequest, or srmStatusOfCopyRequest when the file is volatile. If the file has permanent type, the file may be moved to the space that SRM manages, and the space would be successfully released. The subsequent srmPutDone, srmStatusOfPutRequest, or srmStatusOfCopyRequestmust be successful.

e)     If space is being released without forceFileRelease option while SURLs are being created with srmPrepareToPut or srmCopy, SRM_FAILURE must be returned in srmReleaseSpace.

f)      When a "replica" quality space is expired on its lifetime, all files inside must be expired (by definition, file lifetimes are less than and equal to the remaining lifetime of the space).After the space is expired, the space that is associated with the space token no longer exists, along with all files inside - meaning their SURLs disappear from the file system or reflect the expired lifetime.

 

2.3.3. Return Status Code

SRM_SUCCESS

§  successful request completion. Space is successfully released.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to release the space that is associated with the spaceToken

SRM_INVALID_REQUEST

§  spaceToken does not refer to an existing known space in the SRM.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  forceFileRelease is not supported

§  function is not supported

SRM_FAILURE

§  space still contains pinned files.

§  space associated with space token is already released.

§  any other request failure. Explanation needs to be filled for details.

 

 

2.4. srmUpdateSpace

 

srmUpdateSpace is to resize the space and/or extend the lifetime of a space. Asynchronous operation may be necessary for some SRMs.

 

2.4.1. Parameters

 

                  In:            string                                                          authorizationID,

string                                                          spaceToken,

unsigned long                                        newSizeOfTotalSpaceDesired,

unsigned long                                        newSizeOfGuaranteedSpaceDesired,

int                                                                  newLifeTime,

TExtraInfo[]                                           storageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

string                                                          requestToken,

unsigned long                                        sizeOfTotalSpace,              // best effort

unsigned long                                        sizeOfGuaranteedSpace,                                  

int                                                                  lifetimeGranted

 

2.4.2. Notes on the Behavior

a)     If neither size nor lifetime is provided in the input parameters, then the request must be failed, and SRM_INVALID_REQUEST must be returned. The existing values must not be changed.

b)    newSize is the new actual size of the space.

c)     newLifetime is the new lifetime requested regardless of the previous lifetime. It may even be shorter than the remaining lifetime at the time of the call. It is relative to the calling time. Lifetime must be set from the calling time for the specified period.

d)    Output parameter, lifetimeGranted is the new lifetime granted regardless of the previous lifetime. It may even be shorter than the previous lifetime. It is relative to the calling time.

 

2.4.3. Return Status Code

SRM_SUCCESS

§  successful request completion. Space is successfully updated as the client requested.

SRM_ REQUEST_QUEUED

§  successful request submission and acceptance. Request token must be returned.

SRM_LOWER_SPACE_GRANTED

§  successful request completion, but lower space size is allocated than what the client requested

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to update the space that is associated with the spaceToken

SRM_SPACE_LIFETIME_EXPIRED

§  lifetime of the space that is associated with the spaceToken is already expired.

SRM_INVALID_REQUEST

§  spaceToken does not refer to an existing known space in the SRM.

§  input parameter size or lifetime is not provided.

SRM_EXCEED_ALLOCATION

§  SRM does not have enough space for the request because the client requests more than the allocated space for the client.

SRM_NO_USER_SPACE

§  SRM does not have enough user space for the client request

SRM_NO_FREE_SPACE

§  SRM does not have enough free space for the request

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  New requested size is less than currently occupied space.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported

 

 

2.5. srmStatusOfUpdateSpaceRequest

 

This function is used to check the status of the previous request to srmUpdateSpace, when asynchronous space update is necessary with the SRM. Request token must have been provided in response to the previous call for srmUpdateSpace.

 

2.5.1. Parameters

 

                  In:            string                                                          authorizationID,

string                                                          requestToken

 

                  Out:        TReturnStatus                                      returnStatus,

unsigned long                                        sizeOfTotalSpace,              // best effort

unsigned long                                        sizeOfGuaranteedSpace,                                  

int                                                                  lifetimeGranted

 

2.5.2. Notes on the Behavior

a)     Output parameters for new sizes are the new actual sizes of the space.

b)    Output parameter, lifetimeGranted is the new lifetime granted regardless of the previous lifetime. It may even be shorter than the previous lifetime. It is relative to the client request calling time.

 

2.5.3. Return Status Code

SRM_REQUEST_QUEUED

§  successful request submission and the request is still on the queue to be served.

SRM_REQUEST_INPROGRESS

§  the request is being processed.

SRM_SUCCESS

§  successful request completion. Space is successfully updated as the client requested.

SRM_LOWER_SPACE_GRANTED

§  successful request completion, but lower space size is allocated than what the client requested

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to update the space that is associated with the spaceToken

SRM_SPACE_LIFETIME_EXPIRED

§  lifetime of the space that is associated with the spaceToken is already expired.

SRM_INVALID_REQUEST

§  spaceToken does not refer to an existing known space in the SRM.

§  input parameter size or time is not provided.

SRM_EXCEED_ALLOCATION

§  SRM does not have enough space for the request because the client requests more than the allocated space for the client.

SRM_NO_USER_SPACE

§  SRM does not have enough user space for the client request

SRM_NO_FREE_SPACE

§  SRM does not have enough free space for the request

SRM_REQUEST_SUSPENDED

§  request is suspended.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  New requested size is less than currently occupied space.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported

 

 

2.6. srmGetSpaceMetaData

 

This function is used to get information of a space. Space token must be provided, and space tokens are returned upon a completion of a previous space reservation through srmReserveSpace or srmStatusOfReserveSpaceRequest.

 

2.6.1. Parameters

 

                  In:            string                                        authorizationID,

string[]                                                      arrayOfSpaceTokens

 

                  Out:        TReturnStatus                    returnStatus,

TMetaDataSpace[]            arrayOfSpaceDetails

 

2.6.2. Notes on the Behavior

a)     Output parameters unusedSize in TMetaDataSpacemust be 0 if there is no space left in the allocated space.

 

2.6.3. Return Status Code

For request level return Status,

SRM_SUCCESS

§  successful request completion. Information of all requested spaces isreturned successfully.

SRM_PARTIAL_SUCCESS

§  Request is completed. Information of some requested spaces are returned successfully, and some are failed to be returned.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request space information

SRM_TOO_MANY_RESULTS

§  Request produced too many results that SRM cannot handle.

SRM_INVALID_REQUEST

§  arrayOfSpaceToken is empty.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All space requests are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

 

For space level return Status,

SRM_SUCCESS

§  successful request completion for the spaceToken. Space information is successfully returned.

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request information on the space that is associated with the spaceToken

SRM_INVALID_REQUEST

§  spaceToken does not refer to an existing known space in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  The lifetime on the space that is associated with the spaceToken has expired already

SRM_EXCEED_ALLOCATION

§  Space that is associated with spaceToken has no more space left.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 

2.7. srmChangeSpaceForFiles

 

This function is used to change the space property of files to another space property by specifying target space tokens. All files specified by SURLs will have a new space token. SURLs must not be changed. New space token may be acquired from srmReserveSpace. Asynchronous operation may be necessary for some SRMs, and in such case, request token must be returned for later status request. There is no default behavior when target space token is not provided. In such case, the request must be failed, and the return status must be SRM_INVALID_REQUEST.

 

2.7.1. Parameters

 

                  In:            string                                                          authorizationID,

                                    anyURI []                                                  arrayOfSURLs,

                                    string                                                          targetSpaceToken,

                                    TExtraInfo[]                                           storageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

string                                                          requestToken,

                                    int                                                                  estimatedProcessingTime,

                                    TSURLReturnStatus []                    arrayOfFileStatuses

                                   

 

2.7.2. Notes on the Behavior

a)     When space transition is completed successfully, SRM_SUCCESS must be returned for each SURL.

b)    For any forbidden transition, SRM_INVALID_REQUEST must be returned. It includes changing spaces on SURLs that their statuses are SRM_FILE_BUSY.

c)     Asynchronous operation may be necessary for some SRMs. In such case, request token must be returned. If the request can be completed immediately, request token must not be returned.

d)    When asynchronous operation is necessary, the returned status code must be SRM_REQUEST_QUEUED, and arrayOfFileStatuses may not be filled and returned.

e)     All files specified in arrayOfSURLs will be associated with the new space specified by targetSpaceToken.

f)      Space allocation for a new target space token must be done explicitly by the client before using this function.

g)     If a directory path is provided, then the effect is recursive for all files in the directory.

h)    Space de-allocation may be necessary in some cases, and it must be done by the client explicitly after this operation completes.

i)      When a space is successfully changed for a file from one space to another, the file must retain its remaining lifetime, or the file lifetime must be reduced to that of the target space, whichever is the lesser.

j)      If the target space is only large enough to transfer a subset of the files, the request will continue taking place until the target space cannot hold any more files, and the request must be failed. The status of the request must return an error of SRM_EXCEED_ALLOCATION in such case.

 

2.7.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All file requests are successfully completed. All SURLs have new targetSpaceToken.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURL requests have new targetSpaceToken, and some SURL requests are failed to have new targetSpaceToken. Details are on the files status.

SRM_ REQUEST_QUEUED

§  request is submitted and accepted. requestToken must be returned.

§  The status can be checked by srmStatusOfChangeSpaceForFilesRequest.

SRM_ REQUEST_INPROGRESS

§  The request is being processed. Some files are still queued, and some files are completed in space transition.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to change the file types

SRM_INVALID_REQUEST

§  SURL is empty.

§  targetSpaceToken is empty.

§  targetSpaceToken does not refer to an existing space in the SRM.

§  targetSpaceToken refers to a forbidden transition by the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  target space that is associated with targetSpaceToken has an expired lifetime.

SRM_EXCEED_ALLOCATION

§  targetspace that is associated with targetSpaceToken is not enough to hold all SURLs.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All file requests are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  a specified input parameter is not supported in the SRM

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. The SURL has a new targetSpaceToken.

SRM_ REQUEST_QUEUED

§  file request is on the queue.

SRM_ REQUEST_INPROGRESS

§  file request is being processed.

SRM_INVALID_PATH

§  SURL does not refer to an existing file .

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to change the space for the file that is associated with the SURL.

SRM_INVALID_REQUEST

§  targetSpaceToken refers to a forbidden transition for the particular SURL by the SRM.

§  The status of SURL is SRM_FILE_BUSY.

SRM_EXCEED_ALLOCATION

§  target space that is associated with targetSpaceToken is not enough to hold SURL.

SRM_FILE_LOST

§  the requested file with the SURL is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

§  The requested file with the SURL is being used by other clients.

SRM_FILE_UNAVAILABLE

§  the requested file with the SURL is temporarily unavailable.

SRM_FAILURE

§  file request is failed.

§  any other request failure. Explanation needs to be filled for details.

 

 

2.8. srmStatusOfChangeSpaceForFilesRequest

 

This function is used to check the status of the previous request to srmChangeSpaceForFiles, when asynchronous operation was necessary in the SRM. Request token must have been provided in response to the srmChangeSpaceForFiles.

 

2.8.1. Parameters

 

                  In:            string                                                          authorizationID,

                                    string                                                          requestToken

 

                  Out:        TReturnStatus                                      returnStatus,

int                                                                  estimatedProcessingTime,

TSURLReturnStatus []                    arrayOfFileStatuses

 

2.8.2. Notes on the Behavior

a)     When space transition is completed successfully, SRM_SUCCESS must be returned for each SURL.

b)    If changing space is not completed, estimateProcessingTimemay be returned when known.

c)     If all files are still in the queue and none of the files are completed in changing space, the returned status code must be SRM_REQUEST_QUEUED.

d)    If some files are queued, and some files are completed in changing space, SRM_REQUEST_INPROGRESS must be returned as the return status code. Each file must have its own status code.

e)     If the target space is only large enough to transfer a subset of the files, the request will continue taking place until the target space cannot hold any more files, and the request must be failed. The status of the request must return an error of SRM_EXCEED_ALLOCATION in such case.

 

2.8.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All file requests are successfully completed. All SURLs have new targetSpaceToken.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURL requests have new targetSpaceToken, and some SURL requests are failed to have new targetSpaceToken. Details are on the files status.

SRM_ REQUEST_QUEUED

§  Request submission is successful and the entire request is still on the queue.

SRM_ REQUEST_INPROGRESS

§  Some files are still queued, and some files are completed in space transition.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to change the file types

SRM_INVALID_REQUEST

§  requestToken does not refer to an existing known request in the SRM.

§  targetSpaceToken refers to a forbidden transition by the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  target space that is associated with targetSpaceToken has an expired lifetime.

SRM_EXCEED_ALLOCATION

§  target space that is associated with targetSpaceToken is not large enough to hold SURLs.

SRM_REQUEST_SUSPENDED

§  request is suspended.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All file requests are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  a specified input parameter is not supported in the SRM

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. The SURL has a new targetSpaceToken.

SRM_ REQUEST_QUEUED

§  file request is on the queue.

SRM_ REQUEST_INPROGRESS

§  file request is being processed.

SRM_INVALID_PATH

§  SURL does not refer to an existing file request

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to change the space for the file that is associated with the SURL

SRM_INVALID_REQUEST

§  targetSpaceToken refers to a forbidden transition for the particular SURL by the SRM

§  The status of SURL is SRM_FILE_BUSY.

SRM_EXCEED_ALLOCATION

§  target space that is associated with targetSpaceToken is not large enough to hold SURL.

SRM_REQUEST_SUSPENDED

§  file request is suspended.

SRM_FILE_LOST

§  the requested file with the SURL is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

§  The requested file with the SURL is being used by other clients.

SRM_FILE_UNAVAILABLE

§  the requested file with the SURL is temporarily unavailable.

SRM_FAILURE

§  file request is failed.

§  any other request failure. Explanation needs to be filled for details.

 

 

2.9. srmExtendFileLifeTimeInSpace

 

This function is used to extend lifetime of the files (SURLs) in a space.

 

2.9.1. Parameters

 

                  In:            string                                                          authorizationID,

string                                                          spaceToken,

                                    anyURI[]                                                   arrayOfSURLs,

                                    int                                                                  newLifeTime

 

                  Out:        TReturnStatus                                      returnStatus,

                                    TSURLLifetimeReturnStatus [] arrayOfFileStatuses

 

 

2.9.2. Notes on the Behavior

a)     arrayOfSURLsis optional. When SURLs are not provided, all files in the space must have the new extended lifetime.

b)    newLifeTime is relative to the calling time. Lifetime will be set from the calling time for the specified period.

c)     The new file lifetime, newLifeTime must not exceed the remaining lifetime of the space.

d)    The number of lifetime extensions may be limited by SRM according to its policies.

e)     If original lifetime is longer than the requested one, then the new requested one will be assigned.

f)      If newLifeTime is not specified, the SRM must not change the lifetime.

g)     If input parameter newLifeTime exceeds the remaining lifetime of the space, then SRM_SUCCESS is returned at the request and file level, and TSURLLifetimeReturnStatus contains the remaining lifetime.

h)    Lifetime extension must fail on SURLs when their status is SRM_FILE_BUSY.

i)      This method applied only to SURLs, and output parameter pinLifetime in TSURLLifetimeReturnStatus must be null.

 

2.9.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. All SURLs have a new extended lifetime.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURLs have a new extended lifetime, and some SURLS have failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to extend lifetime of files in the space specified by the space token.

SRM_INVALID_REQUEST

§  spaceToken is empty.

§  spaceToken does not refer to an existing known space in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  lifetime of the space that is associated with the spaceToken is already expired.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All file requests updating lifetimes in a space are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  a specified input parameter is not supported in the SRM

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. The SURL has a new extended lifetime.

SRM_INVALID_PATH

§  SURL does not refer to an existing file request

§  SURL does not refer to an existing file request that is associated with the space token

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to extend the lifetime for the file that is associated with the SURL

SRM_FILE_LOST

§  the requested file is permanently lost.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_FILE_LIFETIME_EXPIRED

§  the requested file is expired already.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 

2.10. srmPurgeFromSpace

 

This function is used when removing files from the given space is needed. Difference from srmReleaseFiles and srmAbortFiles is that srmPurgeFromSpace is not associated with a request. This function must not remove the SURLs, but only the "copies" or "states" of the SURLs. srmRm must be used to remove SURLs.

 

2.10.1. Parameters

 

                  In:            string                                                          authorizationID,

                                    anyURI []                                                  arrayOfSURLs,

                                    string                                                          spaceToken,

                                    TExtraInfo[]                                           storageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

TSURLReturnStatus[]                     arrayOfFileStatuses

 

 

2.10.2. Notes on the Behavior

a)     If the specified SURL is the only remaining copy of the file in the storage system, SRM_LAST_COPY must be returned. To remove the last copy of the SURL, srmRmmust be used.

b)    If the client has an administrative role that SRM can accept in an understandable form, the request must forcefully release the pins owned by the group, and remove the “copy” (or “state”) of the file.

c)     In most cases, all pins on files that are associated with the client will be released. In such cases, files may still be pinned by others and SRM_FILE_BUSY must be returned.

d)    SRM must remove only the “copies” (or “state”) of the SURLs associated with the space token.

 

2.10.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. All SURLs are purged from the space specified by the spaceToken.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURLs are successfully purged from the space specified by the spaceToken, and some SURLs are failed to be purged from the space specified by the spaceToken. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to clean up the space that is associated with spaceToken

SRM_INVALID_REQUEST

§  arrayOfSURLs is empty.

§  spaceToken is empty.

§  spaceToken does not refer to an existing known space in the SRM server.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All file requests are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM server

 

For file level return Status,

SRM_SUCCESS

§  successful request completion for the SURL. SURL is purged from the space specified by the spaceToken.

SRM_INVALID_PATH

§  SURL does not refer to an existing file

§  SURL does not refer to an existing file that is associated with the space token

SRM_AUTHORIZATION_FAILURE

§  Client is not authorized to purge SURL in the space that is associated with spaceToken

SRM_FILE_LOST

§  the request file is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

§  The requested file is used by other clients.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_LAST_COPY

§  the requested file is the last copy and will not be purged from the space. srmRm must be used to remove the last copy.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 

2.11. srmGetSpaceTokens

 

srmGetSpaceTokens() returns space tokens for currently allocated spaces for the client.

 

2.11.1. Parameters

 

                  In:            string                                       userSpaceTokenDescription,

                                    string                                        authorizationID

 

                  Out:        TReturnStatus                    returnStatus,

string[]                                                      arrayOfSpaceTokens

 

 

2.11.2. Notes on the Behavior

a)     If userSpaceTokenDescription is null, returns all space tokens theclient owns.

b)    Optional input parameter userSpaceTokenDescription is case-sensitive. SRM is expected to keep it as client provides. It may be reused by the client. srmGetSpaceTokensmust return all the space tokens that have theuserSpaceTokenDescription.

c)     If a client assigns the same descriptionin multiple space reservations, the client may get back multiple space tokens.

 

2.11.3. Return Status Code

SRM_SUCCESS

§  All requests are successfully completed. Space tokens are returned successfully.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request spaceTokens associated with the userSpaceTokenDescription

SRM_INVALID_REQUEST

§  userSpaceTokenDescription does not refer to an existing space description.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

 

 


3. Permission Functions

 

summary:

srmSetPermission

srmCheckPermission

srmGetPermission

 

 

3.1. srmSetPermission

 

srmSetPermission is to set permission on local SURL.

 

3.1.1. Parameters

 

                  In:            string                                        authorizationID,

anyURI                                                       SURL,    

TPermissionType     permissionType,

TPermissionMode           ownerPermission,

TUserPermission[]         arrayOfUserPermissions,

TGroupPermission[]     arrayOfGroupPermissions,

TPermissionMode           otherPermission,

                                    TExtraInfo[]                         storageSystemInfo

 

Out:        TReturnStatus                    returnStatus

 

3.1.2. Notes on the Behavior

a)     Applies to both directories and files.

b)    Support for srmSetPermission is optional.

c)     User permissions are provided in order to support dynamic user-level permission assignment similar to Access Control Lists (ACLs).

d)    Permissions can be assigned to set of users and sets of groups, but only a single owner.

e)     In this version, SRMs do not provide any group operations (setup, modify, remove, etc.)

f)      Groups are assumed to be set up before srmSetPermission is used.

g)     If TPermissionType is ADD or CHANGE, and TPermissionMode is null, then it must be assumed that TPermissionMode is READ only.

h)    If TPermissionType is REMOVE, then the TPermissionModemust be ignored.

i)      if TPermissionType is CHANGE, but it is being applied to a [user|group] which currently does not have permissions set up for it, then the request must work as ADD. It follows the setfacl: Adds one or more new ACL entries to the file, and/or modifies one or more existing ACL entries on the file. If an entry already exists for a specified user or group, the specified permissions must replace the current permissions. If an entry does not exist for the specified user or group, an entry must be created.

j)      srmSetPermission must modify permissions on SURLs even if the statuses of the SURLs are SRM_FILE_BUSY.

 

3.1.3. Return Status Code

SRM_SUCCESS

§  successful request completion. SURL has a new permission.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to set permissions

§  client is not authorized to set permissions on the SURL

SRM_INVALID_PATH

§  SURL does not refer to an existing known path

SRM_INVALID_REQUEST

§  Permissions are provided incorrectly

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  a specified input parameter is not supported in the SRM

 

 

3.2. srmCheckPermission

                 

srmCheckPermission is used to check the client permissions on the SURLs. It only checks for the client for authorization on the SURLs in the local storage.

 

3.2.1. Parameters

 

                  In:            anyURI []                                                  arrayOfSURLs,

                                    string                                                          authorizationID,

                                    TExtraInfo[]                                           storageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

TSURLPermissionReturn[]         arrayOfPermissions

 

 

3.2.2. Notes on the Behavior

a)     SRM checks files in its local online and nearline storage when supported.

 

3.2.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. Permissions on SURLs are checked and returned.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Permissions of some SURLs are successfully checked and returned, but some permission of some SURLs are failed to be checked. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request permission information

SRM_INVALID_REQUEST

§  arrayOfSURL is empty.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM server

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. Permissions on SURL are checked and returned.

SRM_INVALID_PATH

§  SURL does not refer to an existing known path

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request permission information on the SURL

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

3.3. srmGetPermission

                 

srmGetPermission is used to get the permissions on the SURLs. It only checks for the client for authorization on the SURLs in the local storage.

 

3.3.1. Parameters

 

                  In:            anyURI []                                                  arrayOfSURLs,

                                    string                                                          authorizationID,

                                    TExtraInfo[]                                           storageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

TPermissionReturn[]                      arrayOfPermissionReturns

 

 

3.3.2. Notes on the Behavior

b)    SRM checks files in its local online and nearline storage when supported.

 

3.3.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. Permissions on SURLs are returned.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Permissions of some SURLs are successfully returned, but some permission of some SURLs are failed to be returned. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request permission information

SRM_INVALID_REQUEST

§  arrayOfSURL is empty.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM server

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. Permissions on SURL are returned.

SRM_INVALID_PATH

§  SURL does not refer to an existing known path

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request permission information on the SURL

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 


4. Directory Functions

 

summary:

srmMkdir

srmRmdir

srmRm

srmLs

srmStatusOfLsRequest

srmMv

 

 

4.1. srmMkdir

 

srmMkdir creates a directory in local SRM.

 

4.1.1. Parameters

 

                  In:            string                                        authorizationID,                                 

anyURI                                                       SURL,    

                                    TExtraInfo[]                         storageSystemInfo

 

Out:        TReturnStatus                    returnStatus

 

4.1.2. Notes on the Behavior

a)     Consistent with unix file system.Recursive creation of directories is not supported.

b)    SURLmay specify a new directory, as long as all parent directory hierarchy exists.

 

4.1.3. Return Status Code

SRM_SUCCESS

§  All requests are successfully completed. SURLis created.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to create a directory

§  client is not authorized to create a directory as SURL

SRM_INVALID_PATH

§  SURLdoes not refer to a valid path

§  component of SURLdoes not refer to an existing path

SRM_DUPLICATION_ERROR

§  SURLexists already

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

 

 

4.2. srmRmdir

 

srmRmdir removes an empty directory in a local SRM.

 

4.2.1. Parameters

 

                  In:            string                                        authorizationID,

anyURI                                                       SURL,    

                                    TExtraInfo[]                         storageSystemInfo,

                                    boolean                                    recursive

 

Out:        TReturnStatus                    returnStatus

 

4.2.2. Notes on the Behavior

a)     It applies to directories only.To distinguish from srmRm(), this function is for directories only.

b)    Input parameterrecursivemust be false by default.

c)     When only expired volatile files are in the requested directory, srmRmdir must allow the removal of the requested directory regardless of the expired files. The SURL of the expired volatile files must no longer exist in the SRM, and may or may not be removed right away physically depending on the internal policy.

 

4.2.3. Return Status Code

SRM_SUCCESS

§  All requests are successfully completed. SURLis removed.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to remove a directory

§  client is not authorized to remove a directory as SURL

SRM_INVALID_PATH

§  SURLdoes not refer to a valid path

SRM_NON_EMPTY_DIRECTORY

§  SURLis not empty

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

§  input parameter recursive is not supported in the SRM

 

 

4.3. srmRm

 

This function removes SURLs (the name space entries) in the storage system. Difference from srmPurgeFromSpace is that srmPurgeFromSpace removes only previously requested “copies” (or “state”) of the SURL in a particular space, and srmPurgeFromSpacemust not remove SURLs or the name space entries.

 

4.3.1. Parameters

 

                  In:            string                                                          authorizationID,

anyURI[]                                                   arrayOfSURLs

                                    TExtraInfo[]                                           storageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

TSURLReturnStatus[]                     arrayOfFileStatuses

 

4.3.2. Notes on the Behavior

a)     To distinguish from srmRmdir(), this function applies to files only.

b)    srmRm removes all copies or states of SURLs in the storage, and removes the entry from the name space.

c)     When an SURL is removed, all associated pinned TURLs must be all released and removed as well.

d)    srmLs,srmPrepareToGet or srmBringOnlinemust not find these removed files any more. It must set file requests on SURL from srmPrepareToGet as SRM_ABORTED.

e)     srmRm aborts the SURLs from srmPrepareToPut requests not yet in SRM_PUT_DONE state, and must set its file status as SRM_ABORTED.

f)      srmRm must remove SURLs even if the statuses of the SURLs are SRM_FILE_BUSY. In this case, operations such as srmPrepareToPut or srmCopy that holds the SURL status as SRM_FILE_BUSY must return SRM_INVALID_PATH upon status request or srmPutDone.

 

4.3.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. All SURLs are removed.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURLs are successfully removed, and some SURLs are failed to be removed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to remove any files

SRM_INVALID_REQUEST

§  arrayOfSURLs is empty.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. SURL is removed.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file path

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to remove SURL

SRM_FILE_LOST

§  the request file is permanently lost.

SRM_FILE_UNAVAILABLE

§  the request file is temporarily unavailable.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 

4.4. srmLs

 

srmLs() returns a list of files with a basic information. This operation may be asynchronous, and in such case, requestToken must be returned.

 

4.4.1. Parameters

 

                  In:            string                                                          authorizationID,

anyURI []                                                  arrayOfSURLs,

TExtraInfo[]                                           storageSystemInfo,

                                    TFileStorageType                               fileStorageType,

                                    boolean                                                      fullDetailedList,

boolean                                                      allLevelRecursive,

int                                                                  numOfLevels,

int                                                                  offset,

int                                                                  count

 

                  Out:        TReturnStatus                                      returnStatus,

                                    string                                                          requestToken,

TMetaDataPathDetail[]                   details

 

 

4.4.2. Notes on the Behavior

a)     Applies to both directories and files

b)    fullDetailedListmust be false by default.

c)     If fullDetailedList is true, the full details must be returned.

d)    If allLevelRecursive is true, then file lists of all level below current must be provided.

e)     If allLevelRecursive is "true", it dominates, i.e. SRM ignoresnumOfLevels. If allLevelRecursive is "false" or missing, then SRM usesnumOfLevels. If numOfLevels is "0" (zero) or missing, SRM assumes a single level. If both allLevelRecursive and numOfLevels are missing, SRM assumes a single level.

f)      Default value of numOfLevels is 1 when not provided.

g)     If numOfLevels is 0, then information about directory itself must be returned. Negative value must be invalid.

h)    If numOfLevels is 1, then information about files in the directory must be returned. Negative value must be invalid.

i)      For directory path, appending a slash (/) at the end of the path is recommended.

j)      When listing for a particular type specified by “fileStorageType”, if supported, only the files with that type must be returned.

k)    Empty directories must be returned.

l)      For non-existing or system-prohibited file or directory browsing, SRM_INVALID_PATH must be returned. For non-supported file or directory browsing, SRM_NOT_SUPPORTED must be returned. Explanation needs to be filled for details.

m)   When browsing the top directory is not supported by the SRM, SRM_NOT_SUPPORTED must be returned at the file level.

 

4.4.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. All SURLs are checked and the information for all SURLs is returned successfully.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURL request is successfully completed, and some SURL request is failed. Details are on the files status.

SRM_REQUEST_QUEUED

§  successful request submission and acceptance. Request token must be returned.

SRM_REQUEST_INPROGRESS

§  Some files are completed, and some files are still on the queue. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request information

SRM_TOO_MANY_RESULTS

§  srmLs request has generated too many results that SRM cannot handle. In most cases, it needs to be narrowed down with offset and count by the client.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_INVALID_REQUEST

§  Negative value for numOfLevels, offsetorcountis provided.

§  Operation on the path such as non-existing or system-prohibited file or directory may be prohibited.

SRM_NOT_SUPPORTED

§  Requested fileStorageType is notsupported in SRM

§  Filtering fileStorageType is notsupported in SRM

§  Operation on the path such as browsing the top directory is not supported.Explanation needs to be filled for details.

§  Directory operation (directory SURL, allLevelRecursiveor numOfLevels) is not supported in SRM

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. The information for the SURL is checked and returned successfully.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_REQUEST_QUEUED

§  file request is still on the queue.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file path.

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to receive the information of the SURL or to access the directory or sub-directories

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

SRM_FILE_LIFETIME_EXPIRED

§  lifetime on SURL has expired. There is no guarantee of the file still in the cache.

SRM_FILE_IN_CACHE

§  lifetime on SURL has expired, but the file is still in the cache.

SRM_NOT_SUPPORTED

§  Operation on the path such as browsing the top directory is not supported. Explanation needs to be filled for details.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 

4.5. srmStatusOfLsRequest

 

srmStatusOfLsRequest() returns a list of files with a basic information. This is an asynchronous operation of srmLs.

 

4.5.1. Parameters

 

                  In:            string                                                          authorizationID,

string                                                          requestToken,

int                                                                  offset,

int                                                                  count

 

                  Out:        TReturnStatus                                      returnStatus,

TMetaDataPathDetail[]                   details

 

 

4.5.2. Notes on the Behavior

a)     Empty directories must be returned.

b)    For non-existing files or directories in the client request, SRM_INVALID_PATH must be returned.

 

4.5.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. All SURLs are checked and the information for all SURLs is returned successfully.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some SURL request is successfully completed, and some SURL request is failed. Details are on the files status.

SRM_REQUEST_QUEUED

§  successful request submission and all files request is still on the queue.

SRM_REQUEST_INPROGRESS

§  Some files are completed, and some files are still on the queue. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to request information

SRM_TOO_MANY_RESULTS

§  srmLs request has generated too many results that SRM cannot handle. In most cases, it needs to be narrowed down with offset and count by the client.

SRM_INVALID_REQUEST

§  Negative value for offsetorcountis provided.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  Requested fileStorageType is notsupported in SRM

§  Filtering fileStorageType is notsupported in SRM

§  Directory operation (directory SURL, browsing top directory, allLevelRecursiveor numOfLevels) is not supported in SRM

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. The information for the SURL is checked and returned successfully.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_REQUEST_QUEUED

§  file request is still on the queue.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file path

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to receive the information of the SURL or to access the directory or sub-directories

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

SRM_FILE_LIFETIME_EXPIRED

§  lifetime on SURL has expired. There is no guarantee of the file still in the cache.

SRM_FILE_IN_CACHE

§  lifetime on SURL has expired, but the file is still in the cache.

SRM_NOT_SUPPORTED

§  Operation on the path such as browsing the top directory is not supported. Explanation needs to be filled for details.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

 

 

 

4.6. srmMv

 

srmMv moves a file or a directory to destination.

 

4.6.1. Parameters

 

                  In:            string                                        authorizationID,

anyURI                                                       fromSURL,

                                    anyURI                                                       toSURL,

                                    TExtraInfo[]                         storageSystemInfo

                                   

Out:        TReturnStatus                    returnStatus                       

 

4.6.2. Notes on the Behavior

a)     Applies to both directories and files, and it works like unix mv.

b)    Authorization checks need to be performed on both fromSURL and toSURL.

c)     srmMv must fail on SURL that its status is SRM_FILE_BUSY, and SRM_FILE_BUSY must be returned.

d)    Moving an SURL to itself results in no operation and SRM_SUCCESS must be returned for no operation.

e)     When moving an SURL to already existing SURL, SRM_DUPLICATION_ERROR must be returned.

 

4.6.3. Return Status Code

SRM_SUCCESS

§  All requests are successfully completed. SURL is moved successfully from one local path to another local path.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to move fromSURL.

§  Client is not authorized to move a file into toSURL

SRM_INVALID_PATH

§  fromSURL does not refer to an existing known path

§  toSURL does not refer to a valid path

§  status of fromSURL is SRM_FILE_BUSY.

SRM_DUPLICATION_ERROR

§  toSURL exists already.

SRM_FILE_LOST

§  the requested file is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

§  The requested file is being used by other clients.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

SRM_NOT_SUPPORTED

§  function is not supported in the SRM

 


5. Data Transfer Functions

 

summary:

srmPrepareToGet

srmStatusOfGetRequest

srmPrepareToPut

srmStatusOfPutRequest

srmCopy

srmStatusOfCopyRequest

srmBringOnline

srmStatusOfBringOnlineRequest

 

srmReleaseFiles

srmPutDone

 

srmAbortRequest

srmAbortFiles

srmSuspendRequest

srmResumeRequest

 

srmGetRequestSummary

 

srmExtendFileLifeTime

srmGetRequestTokens

 

 

5.1. srmPrepareToGet

 

This function is used to bring files online upon the client’s request and assign TURLs so that client can access the files. Lifetime (pinning expiration time) is assigned on the TURL. When target space token is specified,it must be refer to an online space, and the files must be prepared using the space associated with the space token. It may be an asynchronous operation, and request token must be returned in such case if the client request is valid and accepted. The status may only be checked through srmStatusOfGetRequest with the returned request token.

 

5.1.1. Parameters

 

                  In:            string                                                          authorizationID,

TGetFileRequest[]                             arrayOfFileRequests,

                                    string                                                          userRequestDescription,             

TExtraInfo[]                                           storageSystemInfo,

                                    TFileStorageType                               desiredFileStorageType,

                                    int                                                                  desiredTotalRequestTime,

                                    int                                                                  desiredPinLifetime,

string                                                          targetSpaceToken,

TRetentionPolicyInfo                      targetFileRetentionPolicyInfo,

TTransferParameters                     transferParameters

 

                  Out:        TReturnStatus                                      returnStatus,

string                                                          requestToken,

TGetRequestFileStatus[]               arrayOfFileStatuses,

                                    int                                                                  remainingTotalRequestTime

 

5.1.2. Notes on the Behavior

a)     The default value of “lifetime” for Volatile or Durable files may be the lifetime left in the space of the corresponding file type. The default value of “fileStorageType” is Volatile.

b)    If optional input parameter targetSpaceToken is provided, then the target space token must refer to an online space. All requested files must be prepared into the target space, when supported.

c)     Input parameter targetFileRetentionPolicyInfo of TRetentionPolicyInfo specifies the desired retention policy information on the file when the file is prepared online.

d)    If both input parameters targetSpaceToken and TRetentionPolicyInfo are provided, then their types must match exactly. Otherwise, the request must be failed with SRM_INVALID_REQUEST.

e)     Access latency must be ONLINE always.

f)      If input parameter TAccessPattern is provided at the request-level, then all files must have the same access pattern.

g)     Optional input parameters in TTransferParameters may collide with the characteristics of the space specified. In this case, TTransferParameters as an input parameter must be ignored.

o)    The userRequestDescription is a user designated name for the request. It is case-sensitive. SRM is expected to keep it as client provides. It may be reused by the client. It may be used in the srmGetRequestTokens function to get back the system assigned request tokens. srmGetRequestTokensmust return all the request tokens that have the userRequestDescription.

h)    Only pull mode is supported for file transfers that client must pull the files from the TURL within the expiration time (remainingPinTime).

i)      Input parameter desiredPinLifetimespecifies a client-preferred lifetime (expiration time) on the prepared TURL.

j)      If the request is accepted and queued, SRM assigns the requestToken for asynchronous status checking. In such case, the returned status code must be SRM_REQUEST_QUEUED.

k)    totalRequestTime means: All the file transfer for this request must be completed within this totalRequestTime. Otherwise, SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation.

l)      If desiredTotalRequestTime is unspecified, the request may be retried for a duration, which is dependent on the SRM, in case transient error occurs.

m)   If input parameter desiredTotalRequestTime is 0 (zero), each file request must be tried at least once. Negative value must be invalid.

n)    Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

o)    The invocation of srmReleaseFile() is expected for finished files later on.

p)    The returned request token must be valid until all files in the request are released or removed.

q)    Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRMmust return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests are successful) or SRM_FAILURE at the request level.

r)     Zero length files must not fail on srmPrepareToGet.

 

5.1.3. Return Status Code

For request level return status,

SRM_REQUEST_QUEUED

§  successful request submission and acceptance. All file requests are on the queue. Request token must be returned.

SRM_REQUEST_INPROGRESS

§  some files are completed, and some files are still on the queue. Request token must be returned.

SRM_SUCCESS

§  all file requests are successfully completed. All SURLs are successfully pinned. For TURLs, file level status needs to be checked.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some file request is successfully pinned, and some file request is failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

SRM_INVALID_REQUEST

§  arrayOfFileRequest is empty

§  Input parameters targetSpaceToken and TRetentionPolicyInfodo not match.

§  Access latency is something other than ONLINE.

§  targetSpaceToken does not refer to an existing known space in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested SURLs.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested files.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested files for free.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requests bbftp for the only transfer protocol, but SRM does not support that. Client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  Directory operation is not supported in the SRM.

§  Recursive directory operation is not supported in the SRM.

§  None of the file transfer protocols are supported in the SRM.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_FILE_PINNED

§  successful request completion for the SURL. SURL is successfully pinned, and TURL is available for access.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_ABORTED

§  The requested file has been aborted.

SRM_RELEASED

§  The requested file has been released.

SRM_FILE_LOST

§  the requested file is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file in SRM

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to retrieve the file that is associated with the SURL

SRM_FILE_LIFETIME_EXPIRED

§  SURL is expired

§  TURL is expired

§  pin lifetime on TURL has expired, but the file is still in the cache.

SRM_NO_USER_SPACE

§  user space is not enough to hold requested file.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold requested file for free.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

§  The file request would not be able to be completed within the totalRequestTime.

§  The requested file has been suspended because the request has timed out.

 

 

5.2. srmStatusOfGetRequest

 

This function checks the status of the previously requested srmPrepareToGet. Request token from srmPrepareToGet must be provided.

 

5.2.1. Parameters

 

                  In:            string                                                          requestToken,

                                    string                                                          authorizationID,

                                    anyURI[]                                                   arrayOfSourceSURLs

 

                  Out:        TReturnStatus                                      returnStatus,

TGetRequestFileStatus[]               arrayOfFileStatuses,

                                    int                                                                  remainingTotalRequestTime

 

5.2.2. Notes on the Behavior

a)     The default value of “lifetime” for Volatile or Durable files may be the lifetime left in the space of the corresponding file type. The default value of “fileStorageType” is Volatile.

b)    If arrayOfSourceSURLs is not provided, SRM must return status for all file requests in the request that is associated with the request token.

c)     When the file is ready and TURL is prepared, the return status code must be SRM_FILE_PINNED.

d)    When the file is ready for the client, the file is implicitly pinned in the cache and lifetime must be enforced, subject to the policies associated with the underlying storage.

e)     If any of the request files is temporarily unavailable, SRM_FILE_UNAVAILABLE must be returned for the file.

f)      If any of the request files is permanently lost, SRM_FILE_LOST must be returned for the file.

g)     The file request must fail with an error SRM_FILE_BUSY if srmPrepareToGet requests for files which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

h)    SRM must fail (SRM_FAILURE) only if all files in the request failed.

i)      totalRequestTime means: All the file transfer for this request must be completed within this totalRequestTime. Otherwise, SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation.

j)      Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

k)    Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime from the request. remainingTotalRequestTimemay be returned. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRM must return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests are successful) or SRM_FAILURE at the request level. Clients may need to release files or clean up the target space when target space token is provided in the request.

l)      Output parameter returnStatus must always refer to the request status of the whole request, even if a subset of the whole request was specified in the input for specific file statuses.

 

5.2.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  all file requests are successfully completed. All SURLs are successfully pinned. For TURLs, file level status needs to be checked.

SRM_REQUEST_QUEUED

§  successful request submission and all files request is still on the queue

SRM_REQUEST_INPROGRESS

§  some files are completed, and some files are still on the queue

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some file request is successfully pinned, and some file request is failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

SRM_INVALID_REQUEST

§  requestToken does not refer to an existing known request in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested files.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested files.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested files for free.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requests bbftp for the only transfer protocol, but SRM does not support that. Client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  Directory operation is not supported in the SRM.

§  Recursive directory operation is not supported in the SRM.

§  None of the file transfer protocols are supported in the SRM.

SRM_ABORTED

§  The request has been aborted.

SRM_REQUEST_TIMED_OUT

§  Total request time is over and the rest of the request is failed.

SRM_REQUEST_SUSPENDED

§  request is suspended.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_FILE_PINNED

§  successful request completion for the SURL. SURL is successfully pinned, and TURL is available for access.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_ABORTED

§  The requested file has been aborted.

SRM_RELEASED

§  The requested file has been released.

SRM_REQUEST_SUSPENDED

§  File request is suspended.

SRM_FILE_LOST

§  the requested file is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file request that is associated with the request token

§  SURL does not refer to an existing file in SRM

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to retrieve the file that is associated with the SURL

SRM_FILE_LIFETIME_EXPIRED

§  SURL is expired

§  TURL is expired

§  pin lifetime on TURL has expired, but the file is still in the cache

SRM_NO_USER_SPACE

§  user space is not enough to hold requested file.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold requested file for free.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

§  The file request would not be able to be completed within the totalRequestTime.

§  The requested file has been suspended because the request has timed out.

 

 

5.3. srmBringOnline

 

This function brings files online upon the client request so that client can make certain data readily available for future access. In hierarchical storage systems, it is expected to “stage” files to the top hierarchy and make sure that the files stay online for a certain period of time. When client specifies target space token which must refer to an online space, the files must be brought online using the space associated with the space token. It may be an asynchronous operation, and request token must be returned if asynchronous operation is necessary in SRM. The status may only be checked through srmStatusOfBringOnlineRequest with the returned request token.

This function is similar to srmPrepareToGet, but it does not return Transfer URL (TURL).

 

5.3.1. Parameters

 

                  In:            string                                                                            authorizationID,

TGetFileRequest[]                                               arrayOfFileRequests,    

                                    string                                                                            userRequestDescription,             

TExtraInfo[]                                                             storageSystemInfo,

                                    TFileStorageType                                                 desiredFileStorageType,

                                    int                                                                                    desiredTotalRequestTime,

                                    int                                                                                    desiredLifetime, // lifetime on online

string                                                                            targetSpaceToken,

TRetentionPolicyInfo                                        targetFileRetentionPolicyInfo,

TTransferParameters                                       transferParameters,

                                    int                                                                                    deferredStartTime

 

                  Out:        TReturnStatus                                                        returnStatus,

string                                                                            requestToken,

TBringOnlineRequestFileStatus[]             arrayOfFileStatuses,

                                    int                                                                                    remainingTotalRequestTime,

                                    int                                                                                    remainingDeferredStartTime

                 

5.3.2. Notes on the Behavior

a)     Optional input parameter deferredStartTime is to support CE-SE resource co-allocation and tape mounting efficiency. It means that client does not intent to use the files before that time. If SRM decides not to bring any files until deferredStartTime is reached, SRM_REQUEST_QUEUED must be returned. By default,deferredStartTime is 0 (zero) and the request gets queued or processed upon submission. Negative value must be invalid.

b)    Output parameter remainingDeferredStartTime indicates how long the deferredStartTime is left, if supported. Negative value mustbe invalid.

c)     Input parameter targetFileRetentionPolicyInfo of TRetentionPolicyInfo specifies the desired retention policy information on the file when the file is brought online.

d)    If both input parameters targetSpaceToken and TRetentionPolicyInfo are provided, then their types must match exactly. Otherwise, the request must be failed, and SRM_INVALID_REQUEST must be returned.

e)     Optional input parameters in TTransferParameters may collide with the characteristics of the space specified. In this case, TTransferParameters as an input parameter must be ignored.

f)      If the transfer protocol hints are not specified, default is assumed to be processing mode and LAN access for the site, when supported.

g)     Access latency after the operation is successful must be ONLINE, and the file may also be on NEARLINE as well.

h)    It is up to the SRM to decide TConnectionType if not provided.

i)      The userRequestDescription is a user designated name for the request. It is case-sensitive. SRM must keep it as client provides. It may be reused by the client. It can be used in the srmGetRequestTokens function to get back the system assigned request tokens. srmGetRequestTokensmust return all the request tokens that have the userRequestDescription.

j)      Input parameter desiredLifetime is for a client-preferred lifetime (expiration time) on the file “copies (or “states”) of the SURLs that will be “brought online” into the target space that is associated with the targetSpaceToken.

k)    This call may be an asynchronous (non-blocking) call, and SRM assigns the requestToken when the request is valid, accepted and queued. The returned status code must be SRM_REQUEST_QUEUED. To get subsequent status and results, separate calls must be made through srmStatusOfBringOnline.

l)      The returned request token must be valid until all files in the request are released, removed or aborted.

m)   totalRequestTime means: All the file transfer for this request must be completed within this desiredTotalRequestTime. Otherwise, SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation.

n)    If input parameter desiredTotalRequestTime is unspecified, the request may be retried for a duration which is dependent on the SRM, in case transient error occurs.

o)    If input parameter desiredTotalRequestTime is 0 (zero), each file request must be tried at least once. Negative value must beinvalid.

p)    Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

q)    When srmAbortRequest is requested for srmBringOnline request, the request gets aborted, but those files that are brought online will remain in the space where they are brought in, and are not removed. Clients need to remove those files through srmPurgeFromSpace or srmRm.

r)     Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRM must return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests are successful) or SRM_FAILURE at the request level.

 

5.3.3. Return Status Code

For request level return status,

SRM_REQUEST_QUEUED

§  successful request submission and acceptance. All file requests are on the queue. Request token must be returned.

SRM_REQUEST_INPROGRESS

§  some files are completed, and some files are not completed yet. Request token must be returned.

SRM_SUCCESS

§  All requests are successfully completed. All SURLs are successfully brought online.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some files are successfully brought online, and some files are failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

SRM_INVALID_REQUEST

§  arrayOfFileRequest is empty

§  Access latency refers to something other than ONLINE.

§  Input parameters targetSpaceToken and TRetentionPolicyInfodo not match.

§  targetSpaceToken does not refer to an existing known space in the SRM.

§  deferredStartTime is negative.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested files.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested files.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested files for free.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requests bbftp for the only transfer protocol, but SRM cannot support that. Client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  GivendeferredStartTime is not supported in the SRM.

§  Directory operation is not supported in the SRM.

§  Recursive directory operation is not supported in the SRM.

§  None of the given file transfer protocols are supported in the SRM.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. SURL is successfully brought online.

SRM_FILE_IN_CACHE

§  successful request completion for the SURL. SURL is successfully brought online.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to retrieve the file that is associated with the SURL

SRM_ABORTED

§  The requested file has been aborted.

SRM_RELEASED

§  The requested file has been released.

SRM_FILE_LOST

§  the requested file is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file in SRM

SRM_FILE_LIFETIME_EXPIRED

§  SURL is expired

§  pin lifetime has expired, but the file is still in the cache

SRM_NO_USER_SPACE

§  user space is not enough to hold requested file.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold requested file for free.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

§  The file request would not be able to be completed within the totalRequestTime.

§  The requested file has been suspended because the request has timed out.

 

 

5.4. srmStatusOfBringOnlineRequest

 

This function checks the status of the previous request to srmBringOnline, when asynchronous operation is necessary in the SRM. Request token must have been provided previously in response to the srmBringOnline.

 

5.4.1. Parameters

 

                  In:            string                                                                            requestToken,

                                    string                                                                            authorizationID,

                                    anyURI[]                                                                     arrayOfSourceSURLs

 

                  Out:        TReturnStatus                                                        returnStatus,

TBringOnlineRequestFileStatus[]             arrayOfFileStatuses,

                                    int                                                                                    remainingTotalRequestTime,

                                    int                                                                                    remainingDeferredStartTime

 

5.4.2. Notes on the Behavior

a)     If arrayOfSourceSURLs is not provided, all files in the request must be returned.

b)    When the file is ready online, the return status code should be SRM_FILE_IN_CACHE.

c)     Output parameter remainingDeferredStartTime indicates how long the deferredStartTime is left, if supported. Negative value must beinvalid.

d)    When the file is ready for the client, the file is implicitly pinned in the cache and lifetime will be enforced, subject to the policies associated with the underlying storage.

e)     If any of the request files is temporarily unavailable, SRM_FILE_UNAVAILABLE must be returned for the file.

f)      If any of the request files is permanently lost, SRM_FILE_LOST must be returned for the file.

g)     The file request must fail with an error SRM_FILE_BUSY if srmBringOnline requests for files which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

h)    SRM must fail (SRM_FAILURE) only if all files in the request failed.

i)      totalRequestTime means: All the file transfer for this request must be completed within this totalRequestTime. Otherwise, SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation.

j)      Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

k)    If SRM decides not to bring any files until input parameter deferredStartTime is reached, SRM_REQUEST_QUEUED must be returned.

l)      Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime from the request. remainingTotalRequestTimemay be returned. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRM must return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests were successful) or SRM_FAILURE at the request level. Clients may need to release files or clean up the target space when target space token is provided.

m)   Output parameter returnStatus must always refer to the request status of the whole request, even if a subset of the whole request is specified in the input for specific file statuses.

 

5.4.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. All SURLs are successfully brought online.

SRM_REQUEST_QUEUED

§  successful request submission and all files request is on the queue

SRM_REQUEST_INPROGRESS

§  some files are completed, and some files are not completed yet.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some files are successfully brought online, and some files are failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM failed to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

SRM_INVALID_REQUEST

§  requestToken does not refer to an existing known request in the SRM.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requests bbftp for the only transfer protocol, but SRM cannot support that. Client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  deferredStartTime is not supported in the SRM.

§  Directory operation is not supported in the SRM.

§  Recursive directory operation is not supported in the SRM.

§  None of the file transfer protocols are supported in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested files.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested files.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested files for free.

SRM_ABORTED

§  The request has been aborted.

SRM_REQUEST_TIMED_OUT

§  Total request time is over and the rest of the request is failed.

SRM_REQUEST_SUSPENDED

§  request is suspended.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the SURL. SURL is successfully brought online.

SRM_FILE_IN_CACHE

§  successful request completion for the SURL. SURL is successfully brought online.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to retrieve the file that is associated with the SURL

SRM_ABORTED

§  The requested file has been aborted.

SRM_RELEASED

§  The requested file has been released.

SRM_REQUEST_SUSPENDED

§  File request is suspended.

SRM_FILE_LOST

§  the requested file is permanently lost.

SRM_FILE_BUSY

§  client requests for a file which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.

SRM_FILE_UNAVAILABLE

§  the requested file is temporarily unavailable.

SRM_INVALID_PATH

§  SURL does not refer to an existing known file request that is associated with the request token

SRM_FILE_LIFETIME_EXPIRED

§  SURL is expired

§  pin lifetime has expired, but the file is still in the cache

SRM_NO_USER_SPACE

§  user space is not enough to hold requested file.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold requested file for free.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

§  The file request would not be able to be completed within the totalRequestTime.

§  The requested file has been suspended because the request has timed out.

 

 

5.5. srmPrepareToPut

 

This function is used to write files into the storage. Upon the client request, SRM prepares a TURL so that client can write data into the TURL. Lifetime (pinning expiration time) is assigned on the TURL. When a specified target space token is provided, the files will be located finally in the targeted space associated with the target space token. It may be an asynchronous operation, and request token must be returned if the request is valid, accepted and queued to the SRM. The status may only be checked through srmStatusOfPutRequest with the returned request token.

 

5.5.1. Parameters

 

                  In:            string                                                          authorizationID,

TPutFileRequest[]                             arrayOfFileRequests,    

string                                                          userRequestDescription,

                                    TOverwriteMode                               overwriteOption,

                                    TExtraInfo[]                                           storageSystemInfo,

                                    int                                                                  desiredTotalRequestTime,

                                    int                                                                  desiredPinLifetime, // on TURL

                                    int                                                                  desiredFileLifetime, // on SURL

                                    TFileStorageType                               desiredFileStorageType,

string                                                          targetSpaceToken,

TRetentionPolicyInfo                      targetFileRetentionPolicyInfo,

TTransferParameters                     transferParameters

 

                  Out:        TReturnStatus                                      returnStatus,

string                                                          requestToken,

TPutRequestFileStatus[]               arrayOfFileStatuses,

                                    int                                                                  remainingTotalRequestTime

 

 

5.5.2. Notes on the Behavior

a)     The default value of “lifetime” for Volatile or Durable files may be the lifetime left in the space of the corresponding file type. The default value of “fileStorageType” is Volatile.

b)    TURL returned by the srmPrepareToPut may not be used for read access with any protocol. An explicit srmPrepareToGet or srmBringOnline is required.

c)     Optional input parameters in TTransferParameters may collide with the characteristics of the space specified. In this case, TTransferParameters as an input parameter must be ignored.

d)    Input parameter userRequestDescription may be null, and it is case-sensitive when provided. SRM must keep it as client provides. It may be reused by the client. It can be used in the srmGetRequestTokens function to get back the system assigned request tokens. srmGetRequestTokensmust return all the request tokens that have the userRequestDescription.

e)     When optional input parameter targetSpaceToken is provided at the request-level, all files in the request will end up in the space that is associated with the target space token if the space is enough for all files.

f)      Optional input parameter targetFileRetentionPolicyInfo of TRetentionPolicyInfo specifies the desired retention policy information on the file when the file is written into the target storage system.

g)     If both input parameters targetSpaceToken and TRetentionPolicyInfo are provided, then their types must match exactly. Otherwise, the request must be failed and SRM_INVALID_REQUEST must be returned.

h)    Only push mode is supported for file transfers that client must “push” the file to the prepared TURL.

i)      Input parameter targetSURL in the TPutFileRequestmust to be local to SRM. If targetSURL is not specified, SRM may generate a reference SURL for the file request automatically and put it in the specified user space if provided. Then, this reference SURL must be returned along with the “Transfer URL”. Some SRM implementation may require targetSURL.

j)      srmPutDone() is expected after each file is “put” into the prepared TURL.

k)    Optional input parameter desiredPinLifetime is the lifetime (expiration time) on the TURL when the Transfer URL is prepared. It does not refer to the lifetime of the SURL. TURLs must not be valid any more after the desiredPinLifetime is over if srmPutDone or srmAbortRequest is not submitted on the SURL before expiration. In such case, the SRM must return SRM_FAILURE at the file level.

l)      Optional input parameter desiredFileLifetime is the lifetime of the SURL when the file is put into the storage system. It does not refer to the lifetime (expiration time) of the TURL. Lifetime on SURL starts when successful srmPutDone is executed.

m)   The lifetime of the SURL starts as soon as SRM receives the srmPutDone(). If srmPutDone() is not provided, then the file in that space is subject to removal when the lifetime on the TURL expires or the lifetime on the space expires. The lifetime on the TURL can be found in the status of the file request as output parameter remainingPinTime in TPutRequestFileStatus.

n)    If request is accepted and queued, SRM assigns the requestToken for asynchronous status checking. In such case, the returned status code must be SRM_REQUEST_QUEUED.

o)    totalRequestTime means: All the file transfer for the request must be completed within thetotalRequestTime. Otherwise, SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation.

p)    If input parameter desiredTotalRequestTime is unspecified as NULL, the request must be retried for a duration which is dependent on the SRM.

q)    If input parameter desiredTotalRequestTime is 0 (zero), each file request must be tried at least once. Negative value must be invalid.

r)     Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

s)     Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime from the request. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRMmust return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests are successful) or SRM_FAILURE at the request level.

t)     Upon srmPrepareToPut, SURL entry is inserted to the name space, and any methods that access the SURL such as srmLs, srmBringOnline and srmPrepareToGet must return SRM_FILE_BUSY at the file level. If another srmPrepareToPut or srmCopy is requested on the same SURL, SRM_FILE_BUSY must be returned if the SURL can be overwritten, otherwise SRM_DUPLICATION_ERROR must be returned at the file level.

u)    Input parameter overwriteOption is assumed to be NEVER when not specified.

v)    When requested file storage type is VOLATILE, it cannot be promoted to PERMANENT to avoid complexities in space accounting and other cleanup tasks. SRM_NOT_SUPPORTED must be returned if the requested file storage type is not supported, otherwise the request must be processed.

w)   After TURL is returned, srmMv operation on the corresponding SURL may be requested. srmPutDone on the original SURL must be succesful, and SRM_SUCCESS must be returned at the file level upon successful srmPutDone.

x)     Zero length files must not fail on srmPrepareToPut.

y)    When a VOLATILE file is put into an unreserved replica quality space without any space token being used, and the VOLATILE file gets expired, SRM must remove its SURL from the file system. The file may or may not be removed physically right away.

 

5.5.3. Return Status Code

For request level return status,

SRM_REQUEST_QUEUED

§  successful request submission and acceptance. All file requests are on the queue. Request token must be returned.

SRM_REQUEST_INPROGRESS

§  some files are completed, and some files are still on the queue. Request token must be returned.

SRM_SUCCESS

§  All requests are successfully completed. For all SURLs, spaces are allocated, and TURLs are prepared.

SRM_PARTIAL_SUCCESS

§  All requests are completed. For some file requests, the spaces are allocated and TURLs are prepared, but for some file requests, it is failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM failS to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

SRM_INVALID_REQUEST

§  If both input parameters targetSpaceToken and TRetentionPolicyInfo are provided, then their types must match exactly.

§  targetSpaceToken does not refer to an existing known space in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested SURLs.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested files.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested files for free.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requests bbftp for the only transfer protocol, but SRM cannot support that. Client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  None of the file transfer protocols are supported in the SRM.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SPACE_AVAILABLE

§  successful request completion for the “put” request. The space is allocated, and TURL is prepared.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_FILE_IN_CACHE

§  lifetime on SURL has expired, but the file is still in the cache.

SRM_INVALID_PATH

§  targetSURL does not refer to a valid path.

SRM_DUPLICATION_ERROR

§  targetSURL refers to an existing SURL and overwriting is not permitted.

SRM_FILE_BUSY

§  client requests for files which there is an active srmPrepareToPut (no srmPutDone is yet called) or srmCopy request for.

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to write the file that is associated with the SURL

SRM_ABORTED

§  The requested file has been aborted.

SRM_NO_USER_SPACE

§  user space is not enough to hold the requested file.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold the requested file for free.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

§  The file request would not be able to be completed within the totalRequestTime.

§  The requested file has been suspended because the request has timed out.

§  The file request is not aborted or completed by srmPutDone, and the TURL (available space allocation for the file) is not valid any more.

 

 

5.6. srmStatusOfPutRequest

 

This function is used to check the status of the previously requested srmPrepareToPut. Request token from srmPrepareToPut must be provided.

 

5.6.1. Parameters

 

                  In:            string                                                          requestToken,

                                    string                                                          authorizationID,

                                    anyURI[]                                                   arrayOfTargetSURLs

 

                  Out:        TReturnStatus                                      returnStatus,

TPutRequestFileStatus[]               arrayOfFileStatuses,

                                    int                                                                  remainingTotalRequestTime

 

5.6.2. Notes on the Behavior

a)     The default value of “lifetime” for Volatile or Durable files may be the lifetime left in the space of the corresponding file type. The default value of “fileStorageType” is Volatile.

b)    If arrayOfTargetSURLs is not provided, all the file statuses in the request must be returned.

c)     When the space is ready for client to “put” data and TURL is prepared, the return status code must be SRM_SPACE_AVAILABLE.

d)    When the file space is ready for the client, the TURL is available in the cache and pin lifetime on the TURL must be enforced. TURLs must not be valid any more after the pin lifetime is over if srmPutDone or srmAbortRequest is not submitted on the SURL before the expiration. In such case, the SRM must return SRM_FAILURE at the file level.

e)     If a targetSURL is provided with some directory structure, the directory structure must exist, and SRM must not create the directory structure for the targetSURL. In such case, SRM_INVALID_PATH must be returned. srmMkdir may be used to create the directory structure by the client.

f)      Lifetime on SURL starts when successrul srmPutDone is executed.

g)     If the space for the requested files is full, and TURL cannot be returned, then SRM_EXCEED_ALLOCATION, SRM_NO_USER_SPACE, or SRM_NO_FREE_SPACE must be returned for the files.

h)    SRM must fail (SRM_FAILURE) only if all files in the request fail.

i)      totalRequestTime means: All the file transfer for this request must be completed within thetotalRequestTime. Otherwise, SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation.

j)      Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

k)    Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime from the request. remainingTotalRequestTimemay be returned. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRM must return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests are successful) or SRM_FAILURE at the request level. Clients may need to clean up the target space when target space token is provided.

l)      Upon srmPrepareToPut, SURL entry is added to the name space, and any methods that access the SURL such as srmLs, srmBringOnline and srmPrepareToGet must return SRM_FILE_BUSY at the file level. If another srmPrepareToPut or srmCopy is requested on the same SURL, SRM_FILE_BUSY must be returned if the SURL can be overwritten, otherwise SRM_DUPLICATION_ERROR must be returned at the file level.

m)   srmRm must remove SURLs even if the statuses of the SURLs are SRM_FILE_BUSY. In this case, the status for srmPrepareToPut request must return SRM_INVALID_PATH upon status request or srmPutDone.

n)    After TURL is returned, srmMv operation on the corresponding SURL may be requested. srmPutDone on the original SURL must be successful, and SRM_SUCCESS must be returned at the file level upon successful srmPutDone.

o)    Output parameter returnStatus must always refer to the request status of the whole request, even if a subset of the whole request is specified in the input for specific file statuses.

 

5.6.3. Return Status Code

For request level return status,

SRM_SUCCESS

§  All requests are successfully completed. For all SURLs, spaces are allocated, and TURLs are prepared.

SRM_REQUEST_QUEUED

§  successful request submission and all files request is still on the queue

SRM_REQUEST_INPROGRESS

§  some files are completed, and some files are still on the queue

SRM_PARTIAL_SUCCESS

§  All requests are completed. For some file requests, the spaces are allocated and TURLs are prepared, but for some file requests, it is failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

SRM_INVALID_REQUEST

§  requestToken does not refer to an existing known request in the SRM.

§  targetSpaceToken that client provided does not refer to an existing space in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested files.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested files.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested files for free.

SRM_REQUEST_TIMED_OUT

§  Total request time is over and the rest of the request is failed.

SRM_ABORTED

§  The request has been aborted.

SRM_REQUEST_SUSPENDED

§  The request is suspended.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requests bbftp for the only transfer protocol, but SRM cannot support that. Client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  None of the file transfer protocols are supported in the SRM.

SRM_FAILURE

§  All files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SPACE_AVAILABLE

§  successful request completion for the “put” request. The space is allocated, and TURL is prepared.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_SUCCESS

§  Client’s file transfer into TURL is completed, and srmPutDone on the targetSURL is completed. The file is now in the cache and lifetime on the targetSURL is started.

SRM_FILE_IN_CACHE

§  lifetime on SURL has expired, but the file is still in the cache.

SRM_INVALID_PATH

§  targetSURL does not refer to a valid path.

SRM_DUPLICATION_ERROR

§  targetSURL refers to an existing SURL and overwriting is not permitted.

SRM_FILE_BUSY

§  client requests for files which there is an active srmPrepareToPut (no srmPutDone is yet called) or srmCopy request for.

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to write the file that is associated with the SURL

SRM_ABORTED

§  The requested file has been aborted.

SRM_REQUEST_SUSPENDED

§  File request is suspended.

SRM_NO_USER_SPACE

§  user space is not enough to hold the requested file.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold the requested file for free.

SRM_FAILURE

§  any other request failure. Explanation needs to be filled for details.

§  The file request would not be able to be completed within the totalRequestTime.

§  The requested file has been suspended because the request has timed out.

§  The file request is not aborted or completed by srmPutDone, and the TURL (available space allocation for the file) is not valid any more.

 

 

5.7. srmCopy

 

This function is used to copy files from source storage sites into the target storage sites. The source storage site or the target storage site needs to be the SRM itself that the client makes the srmCopy request to. If both source and target are local to the SRM, it performed a local copy. There are two cases for remote copies: 1. Target SRM is where client makes a srmCopy request (PULL case) to, 2. Source SRM is where client makes a srmCopy request (PUSH case) to.

  1. PULL case: Upon the client’s srmCopy request, the target SRM makes a space at the target storage, and makes a request srmPrepareToGet to the source SRM. When TURL is ready at the source SRM, the target SRM transfers the file from the source TURL into the prepared target storage. After the file transfer completes, srmReleaseFiles is issued to the source SRM.
  2. PUSH case: Upon the client’s srmCopy request, the source SRM prepares a file to be transferred out to the target SRM, and makes a request srmPrepareToPut to the target SRM. When TURL is ready at the target SRM, the source SRM transfers the file from the prepared source into the prepared target TURL. After the file transfer completes, srmPutDone is issued to the target SRM.

When a specified target space token is provided, the files will be located finally in the targeted space associated with the space token. It may an asynchronous operation, and request token must be returned in such case. The status may only be checked through srmStatusOfCopyRequest with the returned request token.

 

5.7.1. Parameters

 

                  In:            string                                                          authorizationID,

TCopyFileRequest[]                         arrayOfFileRequests,                      

                                    string                                                          userRequestDescription,

                                    TOverwriteMode                               overwriteOption,

                                    int                                                                  desiredTotalRequestTime,

                                    int                                                                  desiredTargetSURLLifeTime,    

                                    TFileStorageType                               targetFileStorageType,

string                                                          targetSpaceToken,

TRetentionPolicyInfo                      targetFileRetentionPolicyInfo,

                                    TExtraInfo[]                                           sourceStorageSystemInfo,

                                    TExtraInfo[]                                           targetStorageSystemInfo

 

                  Out:        TReturnStatus                                      returnStatus,

string                                                          requestToken,

TCopyRequestFileStatus[]           arrayOfFileStatuses,

                                    int                                                                  remainingTotalRequestTime

 

 

5.7.2. Notes on the Behavior

a)     The default value of desiredTargetSURLLifeTime for Volatile or Durable files may be the lifetime left in the space of the corresponding file type. The default value of targetFileStorageType is Volatile.

b)    When aborted, target SURLs must be provided.

c)     Input parameter userRequestDescription may be null, and it is case-sensitive when provided. SRM is expected to keep it as client provides. It may be reused by the client. It can be used in the srmGetRequestTokens function to get back the system assigned request tokens. srmGetRequestTokensmust return all the request tokens that have the userRequestDescription.

d)    If optional input parameter targetSpaceToken is provided at the request-level, then all files in the request will end up in the space that is associated with the target space token.

e)     Input parameter targetFileRetentionPolicyInfo of TRetentionPolicyInfo specifies the desired retention policy information on the file when the file is written into the target storage system.

f)      If both input parameters targetSpaceToken and TRetentionPolicyInfo are provided, then their types must match exactly. Otherwise, the request must be failed, and SRM_INVALID_REQUEST must be returned.

g)     If request is accepted and queued, SRM must assign the requestToken for asynchronous status checking. In such case, the returned status code must be SRM_REQUEST_QUEUED.

h)    Pull mode: copy from remote storage location to the SRM. (e.g. from remote storage to underlying MSS.)

i)      Push mode: copy from the SRM to remote storage location.

j)      SRM must always release files through srmReleaseFiles from the source after copy is completed, if source is an SRM and PULL mode is performed.

k)    SRM must always issue srmPutDone to the target after copy is completed, if target is an SRM and PUSH mode is performed.

l)      Note there is no protocol negotiation with the client for the request.

m)   totalRequestTime means: All the file transfer for the request must be completed in this totalRequestTime. Otherwise, the request must be returned as failed at the end of the totalRequestTime, and SRM_REQUEST_TIMED_OUT must be returned as the request status code with individual file status of SRM_FAILURE with an appropriate explanation. All completed files must not be removed, but status of the files must be returned to the client.

n)    If input parameter desiredTotalRequestTime is unspecified as NULL, the request must be retried for a duration which is dependent on the SRM.

o)    If input parameter desiredTotalRequestTime is 0 (zero), each file request must be tried at least once. Negative value must be invalid.

p)    Output parameter remainingTotalRequestTime indicates how long the desiredTotalRequestTime is left. If remainingTotalRequestTime is 0 (zero), the request has been timed out. If remainingTotalRequestTime is a negative value (-1), it must mean that each file request will be tried at least once.

q)    When both sourceSURL and targetSURL are local, local copy must be performed.

r)     Empty directories are copied as well.

s)     If a targetSURL is provided with some directory structure, the directory structure must exist, and SRM must not create the directory structure for the targetSURL. In such case, SRM_INVALID_PATH must be returned. srmMkdir may be used to create the directory structure.

t)     If the sourceSURL and targetSURL are provided as directories (copying directories) when SRM supports, then all sub directories must be copied over from the source to the target, and complete sub-directory structure must be created only if TDirOption indicates them.

u)    Streaming mode is allowed. If streaming mode is supported and there is not enough space to hold the request or partially hold the request, the SRM must return SRM_REQUEST_QUEUED and keep trying the request for the duration of desiredTotalRequestTime from the request. In the output parameter of explanation in returnStatus, the SRM may make explicit that the retry is being done. If streaming mode is not supported, the SRM must return SRM_NO_USER_SPACE or SRM_NO_FREE_SPACE at the file level and SRM_PARTIAL_SUCCESS (if some file requests are successful) or SRM_FAILURE at the request level. Clients may need to clean up the target space when target space token is provided.

v)    Upon srmCopy request, SURL entry is inserted to the target name space, and any methods that access the target SURL such as srmLs, srmBringOnline and srmPrepareToGet must return SRM_FILE_BUSY at the file level. If another srmPrepareToPut or srmCopy are requested on the same target SURL, SRM_FILE_BUSY must be returned if the target SURL can be overwritten, otherwise SRM_DUPLICATION_ERROR must be returned at the file level.

w)   Input parameter overwriteOption is assumed to be NEVER when not specified.

 

                                                            

5.7.3. Return Status Code

For request level return status,

SRM_REQUEST_QUEUED

§  successful request submission and acceptance. All file requests are on the queue. Request token must be returned.

SRM_REQUEST_INPROGRESS

§  Some files are completed, and some files are still on the queue. Details are on the files status. Request token must be returned.

SRM_SUCCESS

§  All requests are successfully completed. All source SURLs are copied into the target destination successfully.

SRM_PARTIAL_SUCCESS

§  All requests are completed. Some file request is successfully copied into the target destination, and some file request is failed. Details are on the files status.

SRM_AUTHENTICATION_FAILURE

§  SRM fails to authenticate the client

SRM_AUTHORIZATION_FAILURE

§  client is not authorized to submit the request

§  Client is not authorized to copy files into the space that client provided with targetSpaceToken or targetFileRetentionPolicyInfo

SRM_INVALID_REQUEST

§  If both input parameters targetSpaceToken and TRetentionPolicyInfo are provided, then their types must match exactly.

§  targetSpaceToken does not refer to an existing known space in the SRM.

SRM_SPACE_LIFETIME_EXPIRED

§  space associated with the targetSpaceToken is expired.

SRM_EXCEED_ALLOCATION

§  space associated with the targetSpaceToken is not enough to hold all requested SURLs.

SRM_NO_USER_SPACE

§  user space is not enough to hold all requested SURLs.

SRM_NO_FREE_SPACE

§  SRM space is not enough to hold all requested SURLs for free.

SRM_INTERNAL_ERROR

§  SRM has an internal transient error, and client may try again.

SRM_NOT_SUPPORTED

§  SRM does not support the given input parameters. For example, client requestsdesiredFileStorageType that is not supported by the SRM.

§  targetFileRetentionPolicyInfo does not refer to a supported retention policy in the SRM.

§  Directory operation is not supported in the SRM.

§  Recursive directory operation is not supported in the SRM.

§  A specified input parameter is not supported in the SRM.

§  function is not supported in the SRM.

SRM_FAILURE

§  all files requests are failed.

§  any other request failure. Explanation needs to be filled for details.

 

For file level return status,

SRM_SUCCESS

§  successful request completion for the file. The sourceSURL is copied into the target destination targetSURL successfully, and lifetime on the targetSURL is started.

SRM_REQUEST_QUEUED

§  file request is on the queue.

SRM_REQUEST_INPROGRESS

§  file request is being served.

SRM_FILE_LOST

§  the request file (sourceSURL) is permanently lost.

SRM_FILE_BUSY

§  client requests for files at the source (sourceSURL) which there is an active srmPrepareToPut (no srmPutDone is yet called) request for.