**The Storage Resource Manager**

**Interface Specification**

**Version 2.2**

**26 September 2006**

+-------------------+--------------------------------------------------+
| > Collaboration   | http://sdm.lbl.gov/srm-wg                        |
| > Web:            |                                                  |
+-------------------+--------------------------------------------------+
| > Document        | http://sdm.lbl.gov/srm-wg/doc/SRM.v2.2.pdf       |
| > Location:       |                                                  |
+-------------------+--------------------------------------------------+
|                   |                                                  |
+-------------------+--------------------------------------------------+

+------------------+---------------------------------------------------+
| Editors:         |                                                   |
+------------------+---------------------------------------------------+
| > Alex Sim       | Lawrence Berkeley National Laboratory             |
+------------------+---------------------------------------------------+
| > Arie Shoshani  | Lawrence Berkeley National Laboratory             |
+------------------+---------------------------------------------------+
|                  |                                                   |
+------------------+---------------------------------------------------+

+-------------------+--------------------------------------------------+
| Contributors:     |                                                  |
+-------------------+--------------------------------------------------+
| > Timur           | Fermi National Accelerator Laboratory (FNAL),    |
| > Perelmutov      | USA                                              |
| >                 |                                                  |
| > Don Petravick   |                                                  |
+-------------------+--------------------------------------------------+
| > Junmin Gu       | Lawrence Berkeley National Laboratory (LBNL),    |
|                   | USA                                              |
+-------------------+--------------------------------------------------+
| > Olof Barring    | LHC Computing Project (LCG, CERN), Switzerland   |
| >                 |                                                  |
| > Jean-Philippe   |                                                  |
| > Baud\           |                                                  |
| > Shaun De Witt   |                                                  |
+-------------------+--------------------------------------------------+
| > Jens Jensen\    | Rutherford Appleton Laboratory (RAL), England    |
| > Owen Synge      |                                                  |
+-------------------+--------------------------------------------------+
| > Michael         | Thomas Jefferson National Accelerator Facility   |
| > Haddox-Schatz   | (TJNAF), USA                                     |
| >                 |                                                  |
| > Bryan Hess      |                                                  |
| >                 |                                                  |
| > Andy Kowalski\  |                                                  |
| > Chip Watson     |                                                  |
+-------------------+--------------------------------------------------+

**Copyright Notice**

© Copyright Lawrence Berkeley National Laboratory (LBNL), Fermi National
Accelerator Laboratory (FNAL), Jefferson National Accelerator Facility
(JLAB), Rutherford Appleton Laboratory (RAL) and European Organization
for Nuclear Research (CERN) 2000, 2001, 2002, 2003, 2004, 2005, 2006.
All Rights Reserved.

Permission to copy and display this "The Storage Resource Manager
Interface Specification" ("this paper\"), in any medium without fee or
royalty is hereby granted, provided that you include the following on
ALL copies of this paper, or portions thereof that

you make:

1\. A link or URL to this paper at this location.

2\. This Copyright Notice as shown in this paper.

THIS PAPER IS PROVIDED \"AS IS,\" AND Lawrence Berkeley National
Laboratory, Fermi National Accelerator Laboratory, Jefferson National
Accelerator Facility, Rutherford Appleton Laboratory and European
Organization for Nuclear Research (COLLECTIVELY, THE "COLLABORATION")
MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING,
BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, NON-INFRINGEMENT OR TITLE; THAT THE CONTENTS OF THIS
PAPER ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH
CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS,
TRADEMARKS OR OTHER RIGHTS.

THE COLLABORATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL,
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY
USE OR DISTRIBUTION OF THIS PAPER.

The names and trademarks of the Collaboration may NOT be used in any
manner, including advertising or publicity pertaining to this paper or
its contents, without specific, written prior permission. Title to
copyright in this paper will at all times remain with the Collaboration.

No other rights are granted by implication, estoppel or otherwise.

PORTIONS OF THIS PAPER WERE PREPARED AS AN ACCOUNT OF WORK FUNDED BY
U.S. Department of Energy AT UNIVERSITY OF CALIFORNIA\'S LAWRENCE
BERKELEY NATIONAL LABORATORY. NEITHER THE AUTHORS, NOR THE UNITED STATES
GOVERNMENT OR ANY AGENCY THEREOF, NOR THE UNIVERSITY OF CALIFORNIA, NOR
ANY OF THEIR EMPLOYEES OR OFFICERS, NOR ANY OTHER COPYRIGHT HOLDERS OR
CONTRIBUTORS, MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY
LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR
USEFULNESS OF ANY INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED,
OR REPRESENTS THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS.
REFERENCE HEREIN TO ANY SPECIFIC COMMERCIAL PRODUCT, PROCESS, OR SERVICE
BY TRADE NAME, TRADEMARK, MANUFACTURER, OR OTHERWISE, DOES NOT
NECESSARILY CONSTITUTE OR IMPLY ITS ENDORSEMENT, RECOMMENDATION, THE
UNITED STATES GOVERNMENT OR ANY AGENCY THEREOF OR ANY OTHER COPYRIGHT
HOLDERS OR CONTRIBUTORS. THE VIEW AND OPINIONS OF AUTHORS EXPRESSED
HEREIN DO NOT NECESSARILY STATE OR REFLECT THOSE OF THE UNITED STATES
GOVERNMENT OR ANY AGENCY THEREOF, OR THE ENTITY BY WHICH AN AUTHOR MAY
BE EMPLOYED.

This paper preparation has been partially supported by the Office of
Energy Research, Office of Computational and Technology Research,
Division of Mathematical, Information, and Computational Sciences, of
the U.S. Department of Energy under Contract No. DE-AC03-76SF00098.

The U.S. Government retains for itself, and others acting on its behalf,
a paid-up, nonexclusive, irrevocable worldwide license in said article
to reproduce, prepare derivative works, distribute copies to the public,
and perform publicly and display publicly, by or on behalf of the
Government.

**Table of Contents**

[Introduction 7](#introduction)

[Meaning of terms 7](#meaning-of-terms)

[1. Common Type Definitions 9](#__RefHeading___Toc139683240)

[**1.1. File Storage Type** 9](#__RefHeading___Toc139683241)

[**1.2. File Type** 9](#__RefHeading___Toc139683242)

[**1.3. Retention Policy** 9](#__RefHeading___Toc139683243)

[**1.4. Access Latency** 9](#__RefHeading___Toc139683244)

[**1.5. Permission Mode** 10](#__RefHeading___Toc139683245)

[**1.6. Permission Type** 10](#__RefHeading___Toc139683246)

[**1.7. Request Type** 10](#__RefHeading___Toc139683247)

[**1.8. Overwrite Mode** 10](#__RefHeading___Toc139683248)

[**1.9. File Locality** 10](#__RefHeading___Toc139683249)

[**1.10. Access Pattern** 11](#__RefHeading___Toc139683250)

[**1.11. Connection Type** 11](#__RefHeading___Toc139683251)

[**1.12. Status Codes** 11](#__RefHeading___Toc139683252)

[**1.13. Retention Policy Info** 12](#__RefHeading___Toc139683253)

[**1.14. Request Token** 12](#__RefHeading___Toc139683254)

[**1.15. User Permission** 13](#__RefHeading___Toc139683255)

[**1.16. Group Permission** 13](#__RefHeading___Toc139683256)

[**1.17. Size in Bytes** 13](#OLE_LINK22)

[**1.18. UTC Time** 13](#__RefHeading___Toc139683258)

[**1.19. Lifetime in Seconds** 13](#__RefHeading___Toc139683259)

[**1.20. SURL** 13](#__RefHeading___Toc139683260)

[**1.21. TURL** 14](#__RefHeading___Toc139683261)

[**1.22. Return Status** 14](#__RefHeading___Toc139683262)

[**1.23. Return Status for SURL** 14](#__RefHeading___Toc139683263)

[**1.24. File MetaData** 14](#__RefHeading___Toc139683264)

[**1.25. Space MetaData** 15](#__RefHeading___Toc139683265)

[**1.26. Directory Option** 15](#__RefHeading___Toc139683266)

[**1.27. Extra Info** 15](#__RefHeading___Toc139683267)

[**1.28. Transfer Parameters** 16](#__RefHeading___Toc139683268)

[**1.29. File Request for srmPrepareToGet**
16](#__RefHeading___Toc139683269)

[**1.30. File Request for srmPrepareToPut**
16](#__RefHeading___Toc139683270)

[**1.31. File Request for srmCopy** 16](#__RefHeading___Toc139683271)

[**1.32. Return File Status for srmPrepareToGet**
17](#__RefHeading___Toc139683272)

[**1.33. Return File Status for srmBringOnline**
17](#__RefHeading___Toc139683273)

[**1.34. Return File Status for srmPrepareToPut**
17](#__RefHeading___Toc139683274)

[**1.35. Return File Status for srmCopy**
17](#__RefHeading___Toc139683275)

[**1.36. Request Summary** 18](#__RefHeading___Toc139683276)

[**1.37. Return Status for SURL** 18](#__RefHeading___Toc139683277)

[**1.38. Return File Permissions** 18](#__RefHeading___Toc139683278)

[**1.39. Return Permissions on SURL** 18](#__RefHeading___Toc139683279)

[**1.40. Return Request Tokens** 19](#__RefHeading___Toc139683280)

[**1.41. Supported File Transfer Protocol**
19](#__RefHeading___Toc139683281)

[2. Space Management Functions 20](#__RefHeading___Toc139683282)

[**2.1. srmReserveSpace** 20](#__RefHeading___Toc139683283)

[**2.2. srmStatusOfReserveSpaceRequest**
22](#__RefHeading___Toc139683284)

[**2.3. srmReleaseSpace** 24](#__RefHeading___Toc139683285)

[**2.4. srmUpdateSpace** 25](#__RefHeading___Toc139683286)

[**2.5. srmStatusOfUpdateSpaceRequest**
26](#__RefHeading___Toc139683287)

[**2.6. srmGetSpaceMetaData** 28](#__RefHeading___Toc139683288)

[**2.7. srmChangeSpaceForFiles** 29](#__RefHeading___Toc139683289)

[**2.8. srmStatusOfChangeSpaceForFilesRequest**
32](#__RefHeading___Toc139683290)

[**2.9. srmExtendFileLifeTimeInSpace** 34](#__RefHeading___Toc139683291)

[**2.10. srmPurgeFromSpace** 36](#__RefHeading___Toc139683292)

[**2.11. srmGetSpaceTokens** 37](#__RefHeading___Toc139683293)

[3. Permission Functions 39](#__RefHeading___Toc139683294)

[**3.1. srmSetPermission** 39](#__RefHeading___Toc139683295)

[**3.2. srmCheckPermission** 40](#__RefHeading___Toc139683296)

[**3.3. srmGetPermission** 41](#__RefHeading___Toc139683297)

[4. Directory Functions 43](#__RefHeading___Toc139683298)

[**4.1. srmMkdir** 43](#__RefHeading___Toc139683299)

[**4.2. srmRmdir** 44](#__RefHeading___Toc139683300)

[**4.3. srmRm** 44](#__RefHeading___Toc139683301)

[**4.4. srmLs** 46](#__RefHeading___Toc139683302)

[**4.5. srmStatusOfLsRequest** 48](#__RefHeading___Toc139683303)

[**4.6. srmMv** 49](#__RefHeading___Toc139683304)

[5. Data Transfer Functions 51](#__RefHeading___Toc139683305)

[**5.1. srmPrepareToGet** 51](#__RefHeading___Toc139683306)

[**5.2. srmStatusOfGetRequest** 54](#__RefHeading___Toc139683307)

[**5.3. srmBringOnline** 57](#__RefHeading___Toc139683308)

[**5.4. srmStatusOfBringOnlineRequest**
61](#__RefHeading___Toc139683309)

[**5.5. srmPrepareToPut** 64](#__RefHeading___Toc139683310)

[**5.6. srmStatusOfPutRequest** 67](#__RefHeading___Toc139683311)

[**5.7. srmCopy** 70](#__RefHeading___Toc139683312)

[**5.8. srmStatusOfCopyRequest** 74](#__RefHeading___Toc139683313)

[**5.9. srmReleaseFiles** 77](#__RefHeading___Toc139683314)

[**5.10. srmPutDone** 78](#__RefHeading___Toc139683315)

[**5.11. srmAbortRequest** 80](#__RefHeading___Toc139683316)

[**5.12. srmAbortFiles** 81](#__RefHeading___Toc139683317)

[**5.13. srmSuspendRequest** 82](#__RefHeading___Toc139683318)

[**5.14. srmResumeRequest** 82](#__RefHeading___Toc139683319)

[**5.15. srmGetRequestSummary** 83](#__RefHeading___Toc139683320)

[**5.16. srmExtendFileLifeTime** 85](#__RefHeading___Toc139683321)

[**5.17. srmGetRequestTokens** 86](#__RefHeading___Toc139683322)

[6. Discovery Functions 88](#__RefHeading___Toc139683323)

[**6.1. srmGetTransferProtocols** 88](#__RefHeading___Toc139683324)

[**6.2. srmPing** 88](#OLE_LINK59)

[7. Appendix 90](#__RefHeading___Toc139683326)

[**7.1. Status Code Specification** 90](#__RefHeading___Toc139683327)

[**7.2. SRM WSDL discovery method** 91](#__RefHeading___Toc139683328)

# Introduction

This document contains the 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, as well as email correspondence and conference
calls. The purpose of this activity is to further define the
functionality and standardize the interface of Storage Resource Managers
(SRMs) -- a Grid middleware component.

The document is organized in four sections. The first, called "Defined
Structures" contain 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.

It is advisable to read the document SRM.v2.2.changes.doc posted at
http://sdm.lbl.gov/srm-wg before reading this specification.

# Meaning of terms

By "https" we mean [http]{.underline} protocol with [GSI]{.underline}
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.

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

    -   *[long]{.underline}* is 64bit: **(+/-)** 9223372036854775807

    -   *[int]{.underline}* is 32 bit**: (+/-)** 2147483647

    -   *[short]{.underline}* is 16 bit**: (+/-)** 32767

    -   *[unsignedLong]{.underline}* ranges (inclusive): 0
        to18446744073709551615

    -   *[unsignedInt]{.underline}* ranges (inclusive): 0 to 4294967295

    -   *[unsignedShort]{.underline}* ranges (inclusive): 0 to 65535

```{=html}
<!-- -->
```
-   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\]\".

-   In "localSURL", we mean local to the SRM that is processing the
    request.

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

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

-   The word "pinning" is limited to the "copies" or "states" of SURLs
    and the Transfer URLs (TURLs).

-   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.  []{#__RefHeading___Toc139683240 .anchor}**Common Type Definitions**

**Namespace** **[SRM]{.underline}**

**Notation: [underlined]{.underline}** attributes are ***REQUIRED*.**

1.  []{#__RefHeading___Toc139683241 .anchor}**File Storage Type**

enum **TFileStorageType** {VOLATILE, DURABLE, PERMANENT}

-   Volatile file has an expiration time and the storage may delete all
    traces of the file when it expires.

-   Permanent file has no expiration time.

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

2.  []{#__RefHeading___Toc139683242 .anchor}**File Type**

enum **TFileType** {FILE, DIRECTORY, LINK}

3.  []{#__RefHeading___Toc139683243 .anchor}**Retention Policy**

enum **TRetentionPolicy** { REPLICA , OUTPUT , CUSTODIAL }

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

```{=html}
<!-- -->
```
-   The type will be 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 will
    be 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 thought the TMetaDataPathDetail
    structure returned by the srmLs function.

4.  []{#__RefHeading___Toc139683244 .anchor}**Access Latency**

enum **TAccessLatency** { ONLINE, NEARLINE }

-   Files may be Online, Nearline or Offline. 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.

    -   For the SRM we only keep ONLINE and NEARLINE.

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

5.  []{#__RefHeading___Toc139683245 .anchor}**Permission Mode**

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

6.  []{#__RefHeading___Toc139683246 .anchor}**Permission Type**

enum **TPermissionType** {ADD, REMOVE, CHANGE}

7.  []{#__RefHeading___Toc139683247 .anchor}**Request Type**

enum **TRequestType** { PREPARE_TO_GET,

PREPARE_TO_PUT,

COPY,

BRING_ONLINE,

RESERVE_SPACE,

UPDATE_SPACE,

CHANGE_SPACE_FOR_FILES,

> LS
>
> }

8.  []{#__RefHeading___Toc139683248 .anchor}**Overwrite Mode**

enum **TOverwriteMode** {NEVER,

> ALWAYS,
>
> WHEN_FILES_ARE_DIFFERENT}

9.  []{#__RefHeading___Toc139683249 .anchor}**File Locality**

enum **TFileLocality** { ONLINE,

> NEARLINE,
>
> ONLINE_AND_NEARLINE,
>
> LOST,
>
> NONE.
>
> UNAVAILABLE }

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

-   The type will be used to describe a file property that indicates the
    current location or status in the storage system.

10. []{#__RefHeading___Toc139683250 .anchor}**Access Pattern**

enum **TAccessPattern** { TRANSFER_MODE, PROCESSING_MODE }

-   TAccessPattern will be passed as an input parameter to the
    srmPrepareToGet and srmBringOnline functions. It will make 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 will allow 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.

11. []{#__RefHeading___Toc139683251 .anchor}**Connection Type**

enum **TConnectionType** { WAN, LAN }

-   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 will be
    passed as an input to the srmPrepareToGet, srmPrepareToPut and
    srmBringOnline functions.

12. []{#__RefHeading___Toc139683252 .anchor}**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
>
> }

13. []{#__RefHeading___Toc139683253 .anchor}**Retention Policy Info**

typedef struct {

TRetentionPolicy [retentionPolicy]{.underline},

TAccessLatency accessLatency

} **TRetentionPolicyInfo**

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

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

14. []{#__RefHeading___Toc139683254 .anchor}**Request Token**

-   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 will be immutable.

15. []{#__RefHeading___Toc139683255 .anchor}**User Permission**

typedef struct { string [userID]{.underline},

TPermissionMode [mode]{.underline}

> } **TUserPermission**

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

16. []{#__RefHeading___Toc139683256 .anchor}**Group Permission**

typedef struct { string [groupID]{.underline},

TPermissionMode [mode]{.underline}

> []{#OLE_LINK22 .anchor}} **TGroupPermission**

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

17. **Size in Bytes**

-   Size in bytes is represented in unsigned long.

18. []{#__RefHeading___Toc139683258 .anchor}**UTC Time**

-   Time is represented in dateTime.

-   Formerly TGMTTime in SRM v2.1

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

-   Format is same as in XML dateTime type, 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.

19. []{#__RefHeading___Toc139683259 .anchor}**Lifetime in Seconds**

-   Lifetime in seconds is represented in integer.

-   "0" (zero) indicates the site defined default lifetime.

-   A negative value (-1) indicates "infinite" lifetime.

20. []{#__RefHeading___Toc139683260 .anchor}**SURL**

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

21. []{#__RefHeading___Toc139683261 .anchor}**TURL**

-   TURL is represented in anyURI.

22. []{#__RefHeading___Toc139683262 .anchor}**Return Status**

typedef struct {TStatusCode [statusCode]{.underline},

string explanation

> } **TReturnStatus**

23. []{#__RefHeading___Toc139683263 .anchor}**Return Status for SURL**

typedef struct {anyURI [surl]{.underline},

TReturnStatus [status]{.underline}

> } **TSURLReturnStatus**

24. []{#__RefHeading___Toc139683264 .anchor}**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**

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

-   *retentionPolicyInfo* indicates the assigned retention policy.

-   *fileLocality* indicates where the file is located currently in the
    system.

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

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

-   *ownerPermission* describes the owner ID and owner permission on the
    SURL.

-   *groupPermission* describes the group permission with group
    identifier on the SURL.

-   *otherPermission* describes the other permission on the SURL.

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

25. []{#__RefHeading___Toc139683265 .anchor}**Space MetaData**

typedef struct { string [spaceToken]{.underline},

TReturnStatus status,

TRetentionPolicyInfo retentionPolicyInfo,

> string owner,

unsigned long totalSize, // best effort

> unsigned long guaranteedSize, unsigned long unusedSize,

int lifetimeAssigned,

int lifetimeLeft

> } **TMetaDataSpace**

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

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

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

26. []{#__RefHeading___Toc139683266 .anchor}**Directory Option**

typedef struct {Boolean [isSourceADirectory]{.underline},

Boolean allLevelRecursive, // default = false

int numOfLevels // default = 1

> } **TDirOption**

27. []{#__RefHeading___Toc139683267 .anchor}**Extra Info**

typedef struct {string [key,]{.underline}

string value

> } **TExtraInfo**

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

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

28. []{#__RefHeading___Toc139683268 .anchor}**Transfer Parameters**

typedef struct {TAccessPattern accessPattern[,]{.underline}

TConnectionType connectionType,

string\[\] arrayOfClientNetworks

string\[\] arrayOfTransferProtocols

> } **TTransferParameters**

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

-   TGetFileRequest includes TAccessPattern which may conflict with the
    characteristics of the online disk of the target space associated
    with target space token if provided. In this case, TAccessPattern
    must be ignored

-   File transfer protocols are specified in a preferred order on all
    SRM transfer functions.

-   arrayOfClientNetworks is a hint of the client IPs that SRM/dCache
    can use for optimization of its internal storage systems based on
    the client's accessible IP addresses.

29. []{#__RefHeading___Toc139683269 .anchor}**File Request for
    srmPrepareToGet**

typedef struct {anyURI [sourceSURL,]{.underline}

> TDirOption dirOption,
>
> } **TGetFileRequest**

30. []{#__RefHeading___Toc139683270 .anchor}**File Request for
    srmPrepareToPut**

typedef struct {anyURI targetSURL , // local to SRM

unsigned long expectedFileSize

> } **TPutFileRequest**

-   If the optional targetSURL is provided, then the reference SURL is
    generated by the SRM. Specific SRM implementation may require
    targetSURL as an input parameter.

31. []{#__RefHeading___Toc139683271 .anchor}**File Request for srmCopy**

typedef struct {anyURI [sourceSURL,]{.underline}

anyURI [targetSURL,]{.underline}

> TDirOption dirOption
>
> } **TCopyFileRequest**

32. []{#__RefHeading___Toc139683272 .anchor}**Return File Status for
    srmPrepareToGet**

typedef struct {anyURI [sourceSURL]{.underline},

TReturnStatus [status]{.underline},

unsigned long fileSize,

int estimatedWaitTime,

> int remainingPinTime,
>
> anyURI transferURL,
>
> TExtraInfo\[\] transferProtocolInfo
>
> } **TGetRequestFileStatus**

-   *transferProtocolInfo* of type *TExtraInfo* is added to the
    *TGetRequestFileStatus*. This output parameter can be used to
    provide more information about the transfer protocol so that client
    can access the TURL efficiently.

33. []{#__RefHeading___Toc139683273 .anchor}**Return File Status for
    srmBringOnline**

typedef struct {anyURI [sourceSURL]{.underline},

TReturnStatus [status]{.underline},

unsigned long fileSize,

int estimatedWaitTime,

> int remainingPinTime,
>
> } **TBringOnlineRequestFileStatus**

34. []{#__RefHeading___Toc139683274 .anchor}**Return File Status for
    srmPrepareToPut**

typedef struct { anyURI [SURL]{.underline},

TReturnStatus [status]{.underline},

> unsigned long fileSize,

int estimatedWaitTime,

> int remainingPinLifetime // on TURL
>
> int remainingFileLifetime // on SURL
>
> anyURI transferURL,

TExtraInfo\[\] transferProtocolInfo

> } **TPutRequestFileStatus**

-   *transferProtocolInfo* of type *TExtraInfo* is added to the
    *TPutRequestFileStatus* to give clients 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.

35. []{#__RefHeading___Toc139683275 .anchor}**Return File Status for
    srmCopy**

typedef struct {anyURI [sourceSURL]{.underline},

anyURI [targetSURL]{.underline},

TReturnStatus [status]{.underline},

unsigned long fileSize,

int estimatedWaitTime,

> int remainingFileLifetime
>
> // on target SURL
>
> } **TCopyRequestFileStatus**

36. []{#__RefHeading___Toc139683276 .anchor}**Request Summary**

typedef struct {string [requestToken]{.underline},

TReturnStatus [status]{.underline},

TRequestType requestType,

int totalNumFilesInRequest,

int numOfCompletedFiles,

int numOfWaitingFiles,

int numOfFailedFiles

> } **TRequestSummary**

37. []{#__RefHeading___Toc139683277 .anchor}**Return Status for SURL**

typedef struct {anyURI [surl]{.underline},

TReturnStatus [status]{.underline}

int fileLifetime,

int pinLifetime,

> } **TSURLLifetimeReturnStatus**

-   *fileLifetime* describes the file lifetime on SURL.

-   *pinLifetime* describes the pin lifetime on TURL, if applicable.

38. []{#__RefHeading___Toc139683278 .anchor}**Return File Permissions**

typedef struct {anyURI [surl]{.underline},

TReturnStatus [status]{.underline},

TPermissionMode permission

> } **TSURLPermissionReturn**

39. []{#__RefHeading___Toc139683279 .anchor}**Return Permissions on
    SURL**

typedef struct {anyURI [surl]{.underline}, // both dir and file

TReturnStatus status,

string owner,

TPermissionMode ownerPermission,

> TUserPermission\[\] arrayOfUserPermissions,
>
> TGroupPermission\[\] arrayOfGroupPermissions,
>
> TPermissionMode otherPermission
>
> } **TPermissionReturn**

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

40. []{#__RefHeading___Toc139683280 .anchor}**Return Request Tokens**

typedef struct {string [requestToken]{.underline},

dateTime createdAtTime

> } **TRequestTokenReturn**

41. []{#__RefHeading___Toc139683281 .anchor}**Supported File Transfer
    Protocol**

typedef struct {string [transferProtocol]{.underline},

TExtraInfo\[\] attributes

> } **TSupportedTransferProtocol**

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

```{=html}
<!-- -->
```
-   *attributes*: Informational hints for the paired transfer protocol,
    such how many number of parallel streams can be used, desired buffer
    size, etc.

2.  []{#__RefHeading___Toc139683282 .anchor}**Space Management
    Functions**

***summary:***

[**srmReserveSpace**](#srmReserveSpace)

[**srmStatusOfReserveSpaceRequest**](#srmGetStatusOfReserveSpace)

[**srmReleaseSpace**](#srmReleaseSpace)

**[srmUpdateSpace](#srmUpdateSpace)**

[**srmGetSpaceMetaData**](#srmGetSpaceMetaData)

[**srmChangeSpaceForFiles**](#srmChangeSpaceForFiles)

[**srmStatusOfChangeSpaceForFilesRequest**](#srmGetStatusOfChangeSpaceForFiles)

[**srmExtendFileLifeTimeInSpace**](#srmExtendFileLifeTimeInSpace)

[**srmPurgeFromSpace**](#srmPurgeFromSpace)

[**srmGetSpaceTokens**](#srmGetSpaceToken)

1.  []{#__RefHeading___Toc139683283 .anchor}**srmReserveSpace**

[]{#srmReserveSpace .anchor}

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 to serve many
concurrent requests.

1.  **Parameters**

In: string authorizationID,

> String userSpaceTokenDescription,

TRetentionPolicyInfo [retentionPolicyInfo]{.underline},

> unsigned long desiredSizeOfTotalSpace[,]{.underline}
>
> unsigned long [desiredSizeOfGuaranteedSpace]{.underline},
>
> unsigned long desiredLifetimeOfReservedSpace,
>
> unsigned long \[\] arrayOfExpectedFileSizes,
>
> TExtraInfo\[\] storageSystemInfo,
>
> TTransferParameters transferParameters

Out: TReturnStatus [returnStatus,]{.underline}

> string requestToken,

int estimatedProcessingTime,

TRetentionPolicyInfo retentionPolicyInfo,

> unsigned long sizeOfTotalReservedSpace, // best effort
>
> unsigned long sizeOfGuaranteedReservedSpace,
>
> int lifetimeOfReservedSpace,
>
> string spaceToken

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If the input parameter *desiredLifetimeOfReservedSpace* is not
    provided, the lifetime of the reserved space is set to "infinite" by
    default.

b)  If the input parameter *retentionPolicyInfo* cannot be satisfied by
    the SRM server, SRM_INVALID_REQUEST must be returned.

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

d)  When asynchronous space reservation is necessary, the returned
    status code should be SRM_REQUEST_QUEUED.

e)  Input parameter *arrayOfExpectedFileSize* is a hint that SRM server
    can 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 will describe 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.

f)  Optional input parameter *storageSystemInfo* is needed in case the
    underlying storage system requires additional security information.

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

h)  If input parameter *desiredSizeOfTotalSpace* is not specified, the
    SRM will return its default space size.

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

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

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

l)  If an operation is successful (SRM_SUCCESS or
    SRM_LOWER_SPACE_GRANTED), *sizeOfGuaranteedReservedSpace*,
    *lifetimeOfReservedSpace* and *spaceToken* are required to return to
    the client.

    1.  **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_LOWER_SPACE_GRANTED

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

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to reserve space

> SRM_INVALID_REQUEST

-   the input parameter *retentionPolicyInfo* cannot be satisfied by the
    SRM server.

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

-   input parameters are invalid.

> SRM_NO_USER_SPACE

-   SRM server does not have enough user space for the client for client
    to request to reserve.

> SRM_NO_FREE_SPACE

-   SRM server does not have enough free space for client to request to
    reserve.

> SRM_EXCEED_ALLOCATION

-   SRM server does not have enough space for the client to fulfill the
    request because the client request needs 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 server

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

    1.  []{#__RefHeading___Toc139683284
        .anchor}**srmStatusOfReserveSpaceRequest**

[]{#srmGetStatusOfReserveSpace .anchor}

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

1.  **Parameters**

In: string authorizationID,

string [requestToken]{.underline}

Out: TReturnStatus [returnStatus,]{.underline}

> int estimatedProcessingTime,

TRetentionPolicyInfo retentionPolicyInfo,

> unsigned long sizeOfTotalReservedSpace,
>
> unsigned long sizeOfGuaranteedReservedSpace,
>
> int lifetimeOfReservedSpace,
>
> string spaceToken

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If the space reservation is not completed yet,
    *estimateProcessingTime* is 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 *spaceToken* are required to return to
    the client.

    1.  **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 server failed 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 server.

> SRM_EXCEED_ALLOCATION

-   SRM server does not have enough space for the client to fulfill the
    request because the client request needs more than the allocated
    space for the client.

> SRM_NO_USER_SPACE

-   SRM server does not have enough user space for the client for the
    client for client to request to reserve.

> SRM_NO_FREE_SPACE

-   SRM server does not have enough free space for the client for client
    to request to reserve.

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

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

    1.  []{#__RefHeading___Toc139683285 .anchor}**srmReleaseSpace**

[]{#srmReleaseSpace .anchor}

srmReleaseSpace() releases an occupied space.

1.  **Parameters**

In: string authorizationID,

> string [spaceToken]{.underline},
>
> TExtraInfo\[\] storageSystemInfo,

Boolean forceFileRelease

> Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  *forceFileRelease* is 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 are released, even in durable or permanent space.

c)  *srmReleaseSpace* may not complete right away because of the
    lifetime of 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, release those files at the end of their
    lifetime.

    1.  **Return Status Code**

> SRM_SUCCESS

-   successful request completion. Space is successfully released.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed 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
    server.

> 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 is already released.

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

    1.  []{#srmUpdateSpace .anchor} []{#__RefHeading___Toc139683286
        .anchor}**srmUpdateSpace**

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

1.  **Parameters**

In: string authorizationID,

> string [spaceToken]{.underline},
>
> unsigned long newSizeOfTotalSpaceDesired[,]{.underline}
>
> unsigned long newSizeOfGuaranteedSpaceDesired,
>
> int newLifeTime,
>
> TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus,]{.underline}

> string requestToken,
>
> unsigned long sizeOfTotalSpace, // best effort
>
> unsigned long sizeOfGuaranteedSpace,
>
> int lifetimeGranted

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If neither size nor lifetime is provided in the input parameters,
    then the request will be failed.

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

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

    1.  **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 server failed 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
    server.

-   input parameter size or time is not provided.

> SRM_EXCEED_ALLOCATION

-   SRM server does not have enough space for the client to fulfill the
    request because the client request has more than the allocated space
    for the client.

> SRM_NO_USER_SPACE

-   SRM server does not have enough space for the client to fulfill the
    request

> SRM_NO_FREE_SPACE

-   SRM server does not have enough free space to fulfill 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 used space.

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

> SRM_NOT_SUPPORTED

-   *function* is not supported

    1.  []{#__RefHeading___Toc139683287
        .anchor}**srmStatusOfUpdateSpaceRequest**

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

1.  **Parameters**

In: string authorizationID,

> string [requestToken]{.underline}

Out: TReturnStatus [returnStatus,]{.underline}

> unsigned long sizeOfTotalSpace, // best effort
>
> unsigned long sizeOfGuaranteedSpace,
>
> int lifetimeGranted

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Output parameters for sew sizes are the new actual sizes of the
    space.

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

    1.  **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 server failed 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
    server.

-   input parameter size or time is not provided.

> SRM_EXCEED_ALLOCATION

-   SRM server does not have enough space for the client to fulfill the
    request because the client request has more than the allocated space
    for the client.

> SRM_NO_USER_SPACE

-   SRM server does not have enough space for the client to fulfill the
    request

> SRM_NO_FREE_SPACE

-   SRM server does not have enough free space to fulfill 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 used space.

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

> SRM_NOT_SUPPORTED

-   *function* is not supported

    1.  []{#__RefHeading___Toc139683288 .anchor}**srmGetSpaceMetaData**

[]{#srmGetSpaceMetaData .anchor}

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 space
reservation through *srmReserveSpace* or
*srmStatusOfReserveSpaceRequest*.

1.  **Parameters**

In: string authorizationID,

> string\[\] [arrayOfSpaceTokens]{.underline}

Out: TReturnStatus [returnStatus,]{.underline}

> TMetaDataSpace\[\] arrayOfSpaceDetails

2.  **Return Status Code**

For request level return Status,

> SRM_SUCCESS

-   successful request completion. Information of all requested spaces
    are returned 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 server failed 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 server 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 server

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

> SRM_SPACE_LIFETIME_EXPIRED

-   The life time on the space that is associated with the *spaceToken*
    has expired

> SRM_FAILURE

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

    1.  []{#__RefHeading___Toc139683289
        .anchor}**srmChangeSpaceForFiles**

[]{#srmChangeSpaceForFiles .anchor}

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 is returned
for later status inquiry. There is no default behavior when target space
token is not provided. In such case, the request will be rejected, and
the return status must be SRM_INVALID_REQUEST.

1.  **Parameters**

In: string authorizationID,

anyURI \[\] [arrayOfSURLs,]{.underline}

string [targetSpaceToken,]{.underline}

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus,]{.underline}

> string requestToken,

int estimatedProcessingTime,

TSURLReturnStatus \[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  When space transition is completed successfully, SRM_SUCCESS must be
    returned for each SURL.

b)  For any forbidden transition by the SRM implementation,
    SRM_INVALID_REQUEST must be returned.

c)  Asynchronous operation may be necessary for some SRMs to serve many
    concurrent requests. 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
    should be SRM_REQUEST_QUEUED, and *arrayOfFileStatuses* may not be
    filled and returned.

e)  All files specified in *arrayOfSURLs* will be moved to the space
    associated with *targetSpaceToken.*

f)  When target space token is used, space allocation for a new 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. The
    status can be checked by srmStatusOfChangeSpaceForFilesRequest.

i)  When a space is successfully changed for a file from one space to
    another, it will either retain its remaining lifetime, or the
    lifetime will 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.

    1.  **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 server failed 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
    server.

-   *targetSpaceToken* refers to a forbidden transition by the SRM
    implementation.

> 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
    enough to hold all *SURLs*.

> 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

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

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

> 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 files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) 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

-   All file requests are failed.

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

    1.  []{#__RefHeading___Toc139683290
        .anchor}**srmStatusOfChangeSpaceForFilesRequest**

[]{#srmGetStatusOfChangeSpaceForFiles .anchor}

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

1.  **Parameters**

In: string authorizationID,

string [requestToken]{.underline}

Out: TReturnStatus [returnStatus]{.underline}

> int estimatedProcessingTime,
>
> TSURLReturnStatus \[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  When space transition is completed successfully, SRM_SUCCESS must be
    returned for each SURL.

b)  If changing space is not completed, *estimateProcessingTime* is
    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 should 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 should 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.

    1.  **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 was 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 server failed 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 server.

-   *targetSpaceToken* refers to a forbidden transition by the SRM
    implementation.

> 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
    enough to hold *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

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

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

> 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 files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) 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

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

    1.  []{#__RefHeading___Toc139683291
        .anchor}**srmExtendFileLifeTimeInSpace**

[]{#srmExtendFileLifeTimeInSpace .anchor}

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

1.  **Parameters**

In: string authorizationID,

> string [spaceToken,]{.underline}

anyURI \[\] arrayOfSURLs,

int newLifeTime

Out: TReturnStatus [returnStatus]{.underline},

TSURLLifetimeReturnStatus \[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  When *spaceToken* is provided, the lifetime of the files
    (*arrayOfSURLs*) in the space associated with the space token will
    be extended.

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, *newTimeExtended* must not exceed the
    remaining lifetime of the space.

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

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

f)  If *newLifeTime* is not specified, the SRM can use its default to
    assign the *newLifeTime*.

    1.  **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 server failed 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
    server.

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

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

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.

    1.  []{#__RefHeading___Toc139683292 .anchor}**srmPurgeFromSpace**

[]{#srmPurgeFromSpace .anchor}

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.

1.  **Parameters**

In: string authorizationID

anyURI \[\] [arrayOfSURLs]{.underline}

string [spaceToken,]{.underline}

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus,]{.underline}

> TSURLReturnStatus\[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
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*, *srmRm* may be used.

b)  If the client has an administers role that SRM server can accept in
    an understandable form, this request will 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 will be returned.

d)  SRM will remove only the "copies" (or "state") of the *SURLs*
    associated with the space token.

    1.  **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 server failed 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 files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) 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.

    1.  []{#__RefHeading___Toc139683293 .anchor}**srmGetSpaceTokens**

[]{#srmGetSpaceToken .anchor}

srmGetSpaceTokens() returns space tokens for currently allocated spaces.

1.  **Parameters**

In: string userSpaceTokenDescription,

string authorizationID

Out: TReturnStatus [returnStatus]{.underline}

> string\[\] arrayOfSpaceTokens

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If *userSpaceTokenDescription* is null, returns all space tokens
    this user owns.

b)  If the user assigned the same name to multiple space reservations,
    he may get back multiple space tokens.

    1.  **Return Status Code**

> SRM_SUCCESS

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

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to request *spaceTokens* associated with
    the *userSpaceDescription*

> SRM_INVALID_REQUEST

-   *userSpaceDescription* 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 server

3.  []{#__RefHeading___Toc139683294 .anchor}**Permission Functions**

***summary:***

> [**srmSetPermission**](#srmSetPermission)
>
> [**srmCheckPermission**](#srmCheckPermission)
>
> [**srmGetPermission**](#srmGetPermission)

1.  []{#__RefHeading___Toc139683295 .anchor}**srmSetPermission**

[]{#srmSetPermission .anchor}

srmSetPermission is to set permission on local SURL.

1.  **Parameters**

In: string authorizationID,

> anyURI [SURL]{.underline},
>
> TPermissionType [permissionType]{.underline},
>
> TPermissionMode ownerPermission[,]{.underline}
>
> TUserPermission\[\] arrayOfUserPermissions[,]{.underline}
>
> TGroupPermission\[\] arrayOfGroupPermissions[,]{.underline}
>
> TPermissionMode otherPermission,

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Applies to both dir and file.

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 is assumed that *TPermissionMode* is READ only.

h)  If *TPermissionType* is REMOVE, then the *TPermissionMode* is
    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 works 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 uid or gid, the specified permissions will replace the
    current permissions. If an entry does not exist for the specified
    uid or gid, an entry will be created.

    1.  **Return Status Code**

> SRM_SUCCESS

-   successful request completion. *SURL* has a new permission.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed 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 server

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

    1.  []{#__RefHeading___Toc139683296 .anchor}**srmCheckPermission**

[]{#srmCheckPermission .anchor}

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

1.  **Parameters**

In: anyURI \[\] [arrayOfSURLs,]{.underline}

string authorizationID,

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus,]{.underline}

> TSURLPermissionReturn\[\] arrayOfPermissions

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  SRM will check files in its local online and nearline storage.

    1.  **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 server failed 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.

    1.  []{#__RefHeading___Toc139683297 .anchor}**srmGetPermission**

[]{#srmGetPermission .anchor}

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

1.  **Parameters**

In: anyURI \[\] [arrayOfSURLs,]{.underline}

string authorizationID,

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus,]{.underline}

> TPermissionReturn\[\] arrayOfPermissionReturns

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
b)  SRM will check files in its local online and nearline storage.

    1.  **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 server failed 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.  []{#__RefHeading___Toc139683298 .anchor}**Directory Functions**

***summary:***

> [**srmMkdir**](#srmMkdir)
>
> [**srmRmdir**](#srmRmdir)
>
> [**srmRm**](#srmRm)
>
> [**srmLs**](#srmLs)
>
> [**srmStatusOfLsRequest**](#srmGetStatusOfLs)
>
> [**srmMv**](#srmMv)

1.  []{#__RefHeading___Toc139683299 .anchor}**srmMkdir**

[]{#srmMkdir .anchor}

srmMkdir create a directory in a local SRM space.

1.  **Parameters**

In: string authorizationID,

> anyURI [SURL,]{.underline}

TExtraInfo\[\] storageSystemInfo

> Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Consistent with unix, recursive creation of directories is not
    supported.

b)  *SURL* is a directory path and can include paths, as long as all
    directory hierarchy exists.

    1.  **Return Status Code**

> SRM_SUCCESS

-   All requests are successfully completed. *SURL* is created.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed 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

-   *SURL* does not refer to a valid path

-   component of *SURL* does not refer to an existing path

> SRM_DUPLICATION_ERROR

-   *SURL* exists 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 server

    1.  []{#__RefHeading___Toc139683300 .anchor}**srmRmdir**

[]{#srmRmdir .anchor}

srmRmdir removes an empty directory in a local SRM space.

1.  **Parameters**

In: string authorizationID,

> anyURI [SURL,]{.underline}

TExtraInfo\[\] storageSystemInfo,

boolean recursive // false by default

> Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  It applies to directory only.

b)  *recursive* is false by default.

c)  To distinguish from *srmRm*(), this function is for directories only

    1.  **Return Status Code**

> SRM_SUCCESS

-   All requests are successfully completed. *SURL* is removed.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed 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

-   *SURL* does not refer to a valid path

> SRM_NON_EMPTY_DIRECTORY

-   *SURL* is 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 server

-   input parameter *recursive* is not supported in the SRM server

    1.  []{#__RefHeading___Toc139683301 .anchor}**srmRm**

[]{#srmRm .anchor}

This function will remove 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 *srmPurgeFromSpace* shall not remove SURLs or the
name space entries.

1.  **Parameters**

In: string authorizationID,

> anyURI\[\] [arrayOfSURLs]{.underline},

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus,]{.underline}

> TSURLReturnStatus\[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  To distinguish from *srmRmdir*(), this function applies to files
    only

b)  *srmRm* removes all copies or states on the storage, and removes the
    entry from the name space.

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

d)  *srmLs,* *srmPrepareToGet* or *srmBringOnline* will 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.

    1.  **Return Status Code**

[]{#srmLs .anchor}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 server failed 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.

    1.  []{#__RefHeading___Toc139683302 .anchor}**srmLs**

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

1.  **Parameters**

In: string authorizationID,

> anyURI \[\] arrayOf[SURLs,]{.underline}
>
> TExtraInfo\[\] storageSystemInfo,

TFileStorageType fileStorageType,

boolean fullDetailedList,

> boolean allLevelRecursive,
>
> int numOfLevels,
>
> int offset,
>
> int count

Out: TReturnStatus [returnStatus]{.underline}

string requestToken

> TMetaDataPathDetail\[\] details

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Applies to both directory and file

b)  *fullDetailedList* is false by default.

    -   For directories, only path is required to be returned.

    -   For files, path and size are required to be returned.

```{=html}
<!-- -->
```
c)  If *fullDetailedList* is true, the full details are returned.

    -   For directories, *path* and *userPermission* are required to be
        returned.

    -   For *files, path, size, userPermission, lastModificationTime,*
        file *type,* and *lifetimeLeft* are required to be returned,
        similar to unix command *ls --l*.

d)  If *allLevelRecursive* is true then file lists of all level below
    current will be provided as well.

e)  If *allLevelRecursive* is \"true\" it dominates, i.e. ignore
    *numOfLevels*. If *allLevelRecursive* is \"false\" or missing, then
    do *numOfLevels*. If *numOfLevels* is \"0\" (zero) or missing,
    assume a single level. If both *allLevelRecursive* and *numOfLevels*
    are missing, assume a single level.

f)  If *numOfLevels* is 0, then information about directory itself is
    returned.

g)  If *numOfLevels* is 1, then information about files in the directory
    is returned.

h)  When listing for a particular type specified by "*fileStorageType*",
    only the files with that type will be in the output.

i)  Empty directories will be returned.

j)  For non-existing file or directory, SRM_INVALID_PATH must be
    returned.

    1.  **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_AUTHENTICATION_FAILURE

-   SRM server failed 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 values for *numOfLevels*, *offset* and *count* are
    provided.

> SRM_NOT_SUPPORTED

-   Requested *fileStorageType* is not supported in SRM

-   Filtering *fileStorageType* is not supported in SRM

-   Directory operation (directory SURL, allLevelRecursive and
    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_FILE_IN_CACHE

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

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

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

    1.  []{#__RefHeading___Toc139683303 .anchor}**srmStatusOfLsRequest**

[]{#srmGetStatusOfLs .anchor}

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

1.  **Parameters**

In: string authorizationID,

> string [requestToken]{.underline}
>
> int offset,
>
> int count

Out: TReturnStatus [returnStatus]{.underline}

> TMetaDataPathDetail\[\] details

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Empty directories will be returned.

b)  For non-existing file or directory, SRM_INVALID_PATH must be
    returned.

    1.  **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_AUTHENTICATION_FAILURE

-   SRM server failed 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 values for *offset* and *count* are provided.

> SRM_INTERNAL_ERROR

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

> SRM_NOT_SUPPORTED

-   Requested *fileStorageType* is not supported in SRM

-   Filtering *fileStorageType* is not supported in SRM

-   Directory operation (directory SURL, allLevelRecursive and
    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_FILE_IN_CACHE

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

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

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

    1.  []{#__RefHeading___Toc139683304 .anchor}**srmMv**

[]{#srmMv .anchor}

srmMv is to move a file from one local path to another local path.

1.  **Parameters**

In: string authorizationID,

> anyURI [fromSURL,]{.underline}

anyURI [toSURL,]{.underline}

TExtraInfo\[\] storageSystemInfo

Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Applies to both directory and file.

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

    1.  **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 server failed 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

> SRM_DUPLICATION_ERROR

-   *toSURL* exists already.

> SRM_FILE_LOST

-   the requested file is permanently lost.

> SRM_FILE_BUSY

-   client requests for files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) 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 server

5.  []{#__RefHeading___Toc139683305 .anchor}**Data Transfer Functions**

**summary:**

> [**srmPrepareToGet**](#srmPrepareToGet)
>
> [**srmStatusOfGetRequest**](#srmStatsuOfGetRequest)
>
> [**srmPrepareToPut**](#srmPrepareToPut)
>
> [**srmStatusOfPutRequest**](#srmStatusOfPutRequest)
>
> [**srmCopy**](#srmCopy)
>
> [**srmStatusOfCopyRequest**](#srmStatusOfCopyRequest)
>
> [**srmBringOnline**](#srmBringOnline)
>
> [**srmStatusOfBringOnlineRequest**](#srmStatusOfBringOnlineRequest)
>
> [**srmReleaseFiles**](#srmReleaseFiles)
>
> [**srmPutDone**](#srmPutDone)
>
> [**srmAbortRequest**](#srmAbortRequest)
>
> [**srmAbortFiles**](#srmAbortFiles)
>
> [**srmSuspendRequest**](#srmSuspendRequest)
>
> [**srmResumeRequest**](#srmResumeRequest)
>
> [**srmGetRequestSummary**](#srmGetRequestSummary)

[**srmExtendFileLifeTime**](#srmExtendFileLifeTime)

> [**srmGetRequestTokens**](#srmGetRequestTokens)

1.  []{#__RefHeading___Toc139683306 .anchor}**srmPrepareToGet**

[]{#srmPrepareToGet .anchor}

This function is used to bring files online upon the client's request
and assign TURL so that client can access the file. Lifetime (pinning
expiration time) is assigned on the TURL. When specified target space
token which must be referred to an online space, the files will be
prepared using the space associated with the space token. It is an
asynchronous operation, and request token must be returned if request is
valid and accepted. The status must be checked through
srmStatusOfGetRequest with the returned request token.

1.  **Parameters**

In: string authorizationID,

> TGetFileRequest\[\] [arrayOfFileRequests,]{.underline}

string userRequestDescription,

> TExtraInfo\[\] storageSystemInfo,

TFileStorageType desiredFileStorageType

int desiredTotalRequestTime

int desiredPinLifetime,

> string targetSpaceToken
>
> TRetentionPolicyInfo targetFileRetentionPolicyInfo
>
> TTransferParameters transferParameters

Out: TReturnStatus [returnStatus]{.underline}

> string requestToken,
>
> TGetRequestFileStatus\[\] arrayOfFileStatuses

int remainingTotalRequestTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  The default value of "lifetime" for Volatile or Durable files will
    be the lifetime left in the space of the corresponding file type.
    The default value of "fileStorageType" is Volatile.

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

c)  Input parameter *targetFileRetentionPolicyInfo* of
    *TRetentionPolicyInfo* is to specify 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 may be rejected with
    SRM_INVALID_REQUEST.

e)  Access latency must be ONLINE always.

f)  Input parameter *TAccessPattern* is provided at the request-level,
    and all files will have the same access pattern.

g)  *TAccessPattern* may conflict with the type of the target space
    associated with target space token, when both provided. In this
    case, *TAccessPattern* in the input parameter *TTransferParameters*
    must be ignored.

h)  The *userRequestDescription* is a user designated name for the
    request. It can be used in the *srmGetRequestID* function to get
    back the system assigned request tokens.

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

j)  Input parameter *desiredPinLifetime* is for a client preferred
    lifetime (expiration time) on the prepared TURL.

k)  If request is accepted, SRM assigns the *requestToken* for
    asynchronous status checking. In such case, the returned status code
    should be SRM_REQUEST_QUEUED.

l)  *totalRequestTime* means: All the file transfer for this request
    must be complete 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.

m)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

n)  If *totalRequestTime* is 0 (zero), 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 should be valid until all files in the
    request are released or removed.

    1.  **Return Status Code**

For request level return 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.
    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 server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to submit the request

> SRM_INVALID_REQUEST

-   *arrayOfFileRequest* is empty

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

-   Access latency is something other than ONLINE.

```{=html}
<!-- -->
```
-   *targetSpaceToken* does not refer to an existing known space in the
    SRM server.

> 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. When
    client does not specify the *targetSpaceToken*, SRM uses a default
    space. The default space is not sufficient to accommodate the
    request.

> SRM_NOT_SUPPORTED

-   SRM server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   Directory operation is not supported in the SRM server.

-   Recursive directory operation is not supported in the SRM server.

-   None of the file transfer protocols are supported in the SRM server.

> 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 still 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 files which there is an active *srmPrepareToPut*
    (no *srmPutDone* is not yet called) 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_AUTHORIZATION_FAILURE

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

> SRM_FILE_LIFETIME_EXPIRED

-   *SURL* is expired

-   *TUR*L is expired

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

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

    1.  []{#__RefHeading___Toc139683307
        .anchor}**srmStatusOfGetRequest**

[]{#srmStatsuOfGetRequest .anchor}

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

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID

anyURI \[\] arrayOfSourceSURLs,

Out: TReturnStatus [returnStatus,]{.underline}

> TGetRequestFileStatus\[\] arrayOfFileStatuses

int remainingTotalRequestTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  The default value of "lifetime" for Volatile or Durable files will
    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
    should be SRM_FILE_PINNED.

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
    srmPrepareToGet requests for files which there is an active
    srmPrepareToPut (no srmPutDone is not yet called) 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 complete 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)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

k)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

    1.  **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 server 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 server.

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

-   SRM server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   Directory operation is not supported in the SRM server.

-   Recursive directory operation is not supported in the SRM server.

-   None of the file transfer protocols are supported in the SRM server.

> 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_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 still 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 files which there is an active *srmPrepareToPut*
    (no *srmPutDone* is not yet called) 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_AUTHORIZATION_FAILURE

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

> SRM_FILE_LIFETIME_EXPIRED

-   *SURL* is expired

-   *TUR*L is expired

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

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

    1.  []{#__RefHeading___Toc139683308 .anchor}**srmBringOnline**

        []{#srmBringOnline .anchor}

This function is used to bring files online upon the client's 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 be
referred to an online space, the files will be brought online using the
space associated with the space token. It is an asynchronous operation,
and request token must be returned if asynchronous operation is
necessary in SRM. The status may be checked through
*srmStatusOfBringOnlineRequest* with the returned request token.

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

1.  **Parameters**

In: string authorizationID,

> TGetFileRequest\[\] [arrayOfFileRequests,]{.underline}

string userRequestDescription,

> TExtraInfo\[\] storageSystemInfo,

TFileStorageType desiredFileStorageType

int desiredTotalRequestTime

int desiredLifetime, // life time on online

> string targetSpaceToken,
>
> TRetentionPolicyInfo targetFileRetentionPolicyInfo,
>
> TTransferParameters transferParameters,

int deferredStartTime

Out: TReturnStatus [returnStatus]{.underline}

> string requestToken
>
> TBringOnlineRequestFileStatus\[\] arrayOfFileStatuses

int remainingTotalRequestTime

int remainingDeferredStartTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  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.

b)  Output parameter *remainingDeferredStartTime* indicates how long the
    deferredStartTime is left, if supported.

c)  Input parameter *targetFileRetentionPolicyInfo* of
    *TRetentionPolicyInfo* is to specify 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 may be rejected, and
    SRM_INVALID_REQUEST will be returned.

e)  *TAccessPattern* may conflict with the type of the target space
    associated with target space token, when both provided. In this
    case, *TAccessPattern* in the input parameter *TTransferParameters*
    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.

g)  Access latency must be ONLINE always.

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

i)  The *userRequestDescription* is a user designated name for the
    request. It can be used in the *srmGetRequestID* method to get back
    the system assigned request ID.

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 and accepted.
    The returned status code should be SRM_REQUEST_QUEUED. To get
    subsequent status and results, separate calls should be made through
    srmStatusOfBringOnline.

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

m)  Input parameter *totalRequestTime* means: All the file transfer for
    this request must be complete 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.

n)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

o)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

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

    1.  **Return Status Code**

For request level return 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 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 server failed 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.

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

```{=html}
<!-- -->
```
-   *targetSpaceToken* does not refer to an existing known space in the
    SRM server.

> 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 server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   *deferredStartTime* is not supported in the SRM server.

-   Directory operation is not supported in the SRM server.

-   Recursive directory operation is not supported in the SRM server.

-   None of the file transfer protocols are supported in the SRM server.

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

-   file request is still 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 files which there is an active *srmPrepareToPut*
    (no *srmPutDone* is not yet called) 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_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.

    1.  []{#__RefHeading___Toc139683309
        .anchor}**srmStatusOfBringOnlineRequest**

[]{#srmStatusOfBringOnlineRequest .anchor}

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

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID

anyURI \[\] arrayOfSourceSURLs,

Out: TReturnStatus [returnStatus,]{.underline}

> TBringOnlineRequestFileStatus\[\] arrayOfFileStatuses

int remainingTotalRequestTime

int remainingDeferredStartTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If *arrayOfSourceSURLs* is not provided, returns status for all
    files in this request.

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.

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 not yet called) for.

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

i)  Input parameter *totalRequestTime* means: All the file transfer for
    this request must be complete 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)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

k)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

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

    1.  **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 still 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 server 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 server.

> SRM_NOT_SUPPORTED

-   SRM server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   *deferredStartTime* is not supported in the SRM server.

-   Directory operation is not supported in the SRM server.

-   Recursive directory operation is not supported in the SRM server.

-   None of the file transfer protocols are supported in the SRM server.

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

-   The request has been aborted.

> SRM_REQUEST_TIMED_OUT

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

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

-   file request is still 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 files which there is an active *srmPrepareToPut*
    (no *srmPutDone* is not yet called) 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_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.

    1.  []{#__RefHeading___Toc139683310 .anchor}**srmPrepareToPut**

[]{#srmPrepareToPut .anchor}

This function is used to write files into the storage. Upon the client's
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
is an asynchronous operation, and request token must be returned if the
request is valid and accepted to the SRM. The status may be checked
through srmStatusOfPutRequest with the returned request token.

1.  **Parameters**

In: string authorizationID,

> TPutFileRequest\[\] arrayOfFileRequests[,]{.underline}
>
> 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]{.underline}

> string requestToken[,]{.underline}
>
> TPutRequestFileStatus\[\] arrayOfFileStatuses

int remainingTotalRequestTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  The default value of "lifetime" for Volatile or Durable files will
    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)  *TAccessPattern* may conflict with the type of the target space
    associated with target space token, when both provided. In this
    case, *TAccessPattern* in the input parameter *TTransferParameters*
    must be ignored.

d)  Input parameter *targetSpaceToken* is provided at the request-level,
    and 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.

e)  Input parameter *targetFileRetentionPolicyInfo* of
    *TRetentionPolicyInfo* is to specify 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 may be rejected and
    SRM_INVALID_REQUEST must be returned.

g)  Only push mode is supported for file transfers that client must
    "push" the file to the prepared TURL.

h)  Input parameter *targetSURL* in the *TPutFileRequest* has to be
    local to SRM. If *targetSURL* is not specified, SRM will make a
    reference for the file request automatically and put it in the
    specified user space if provided. This reference SURL will be
    returned along with the "Transfer URL". Some SRM implementation may
    require *targetSURL*.

i)  *srmPutDone*() is expected after each file is "put" into the
    prepared TURL.

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

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

l)  The lifetime of the SURL starts as soon as SRM receives the
    *srmPutDone*(). If *srmPutDone*() is not provided, then the files in
    that space are 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*.

m)  If request is accepted, SRM assigns the *requestToken* for
    asynchronous status checking. In such case, the returned status code
    should be SRM_REQUEST_QUEUED.

n)  Input parameter *totalRequestTime* means: All the file transfer for
    this request must be complete 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.

o)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

p)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

    1.  **Return Status Code**

For request level return 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.
    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 server failed 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.

```{=html}
<!-- -->
```
-   *targetSpaceToken* does not refer to an existing known space in the
    SRM server.

> 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 server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   None of the file transfer protocols are supported in the SRM server.

> 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 still 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 without no overwriting
    option.

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

    1.  []{#__RefHeading___Toc139683311
        .anchor}**srmStatusOfPutRequest**

[]{#srmStatusOfPutRequest .anchor}

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

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID

anyURI \[\] arrayOfTargetSURLs,

Out: TReturnStatus [returnStatus,]{.underline}

> TPutRequestFileStatus\[\] arrayOfFileStatuses

int remainingTotalRequestTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  The default value of "lifetime" for Volatile or Durable files will
    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, returns status for all the
    file requests in this request.

c)  When the space is ready for client to "put" data and TURL is
    prepared, the return status code should 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 will be enforced.

e)  If a targetSURL is provided with some directory structure, the
    directory structure must exist, and SRM will 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.

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

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

h)  Input parameter *totalRequestTime* means: All the file transfer for
    this request must be complete 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.

i)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

j)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

    1.  **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 server 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 server.

```{=html}
<!-- -->
```
-   *targetSpaceToken* that client provided does not refer to an
    existing space in the SRM server.

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

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

> SRM_INTERNAL_ERROR

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

> SRM_NOT_SUPPORTED

-   SRM server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   None of the file transfer protocols are supported in the SRM server.

> 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 still 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 without no overwriting
    option.

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

    1.  []{#__RefHeading___Toc139683312 .anchor}**srmCopy**

[]{#srmCopy .anchor}

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.
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), 2. Source SRM is where
client makes a srmCopy request (PUSH case).

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
    SR M 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 specified target space token is provided, the files will be located
finally in the targeted space associated with the space token. It is an
asynchronous operation, and request token must be returned. The status
may be checked through srmStatusOfCopyRequest with the returned request
token.

1.  **Parameters**

In: string authorizationID,

> TCopyFileRequest\[\] [arrayOfFileRequests]{.underline},

string userRequestDescription,

TOverwriteMode overwriteOption,

int desiredTotalRequestTime,

int desiredTargetSURLLifetime,

TFileStorageType targetFileStorageType,

> string targetSpaceToken,
>
> TRetentionPolicyInfo targetFileRetentionPolicyInfo,

TExtraInfo\[\] sourceStorageSystemInfo,

TExtraInfo\[\] targetStorageSystemInfo

Out: TReturnStatus [returnStatus]{.underline},

> string requestToken[,]{.underline}
>
> TCopyRequestFileStatus\[\] arrayOfFileStatuses,

int remainingTotalRequestTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  The default value of "lifetime" for Volatile or Durable files will
    be the lifetime left in the space of the corresponding file type.
    The default value of "fileType" is Volatile.

b)  When aborted, target SURLs need to be provided.

c)  Input parameter *targetSpaceToken* is provided at the request-level,
    and all files in the request will end up in the space that is
    associated with the target space token.

d)  Input parameter *targetFileRetentionPolicyInfo* of
    *TRetentionPolicyInfo* is to specify the desired retention policy
    information on the file when the file is written into the target
    storage system.

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

f)  If request is accepted, SRM assigns the *requestToken* for
    asynchronous status checking. In such case, the returned status code
    should be SRM_REQUEST_QUEUED.

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

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

i)  Always release files through *srmReleaseFiles* from the source after
    copy is done, if source is an SRM and PULL mode was performed.

j)  Always issue *srmPutDone* to the target after copy is done, if
    target is an SRM and PUSH mode was performed.

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

l)  Input parameter *desiredTotalRequestTime* means: if all the file
    transfer for this request must be complete in this
    *desiredTotalRequestTime*. Otherwise, the request is returned as
    failed at the end of the *desiredTotalRequestTime*, 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.

m)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

n)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

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

p)  Empty directories are copied as well.

q)  If a targetSURL is provided with some directory structure, the
    directory structure must exist, and SRM will 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.

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

    1.  **Return Status Code**

For request level return 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. 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 server failed 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.

```{=html}
<!-- -->
```
-   *targetSpaceToken* does not refer to an existing known space in the
    SRM server.

> 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 server does not support the given input parameters. For example,
    client requested *desiredFileStorageType* that is not supported by
    the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   Directory operation is not supported in the SRM server.

-   Recursive directory operation is not supported in the SRM server.

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

-   *function* is not supported in the SRM server

> 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 source *SURL* is
    copied into the target destination *targetSURL* successfully, and
    lifetime on the *targetSURL* is started.

> SRM_REQUEST_QUEUED

-   file request is still 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 not yet called) for.

> SRM_FILE_UNAVAILABLE

-   the request file (*sourceSURL*) is temporarily unavailable.

> SRM_FILE_LIFETIME_EXPIRED

-   lifetime on *targetSURL* has expired, but the file is still in the
    cache.

> SRM_INVALID_PATH

-   *sourceSUR* does not exist

-   *targetSURL* does not refer to a valid path.

> SRM_DUPLICATION_ERROR

-   *targetSURL* refers to an existing SURL without no overwriting
    option.

> SRM_AUTHORIZATION_FAILURE

-   Client is not authorized to copy files from *sourceSURL*

-   Client is not authorized to copy files into *targetSURL*

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

> SRM_ABORTED

-   The requested file has been aborted.

> SRM_RELEASED

-   The requested file has been released.

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

    1.  []{#__RefHeading___Toc139683313
        .anchor}**srmStatusOfCopyRequest**

[]{#srmStatusOfCopyRequest .anchor}

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

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID,

anyURI \[\] arrayOfSourceSURLs,

anyURI \[\] arrayOfTargetSURLs,

Out: TReturnStatus [returnStatus,]{.underline}

> TCopyRequestFileStatus\[\] arrayOfFileStatuses,

int remainingTotalRequestTime

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If *arrayOfSourceSURLs* and/or *arrayOfTargetSURLs* are not
    provided, return status for all file requests in the request.

b)  If the target space for the requested files is full, then
    SRM_EXCEED_ALLOCATION, SRM_NO_USER_SPACE, or SRM_NO_FREE_SPACE must
    be returned.

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

d)  *totalRequestTime* means: All the file transfer for this request
    must be complete 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.

e)  If *totalRequestTime* is unspecified as NULL, the request will be
    retried for a duration which is dependent on the SRM implementation.

f)  If *totalRequestTime* is 0 (zero), each file request will be tried
    at least once.

    1.  **Return Status Code**

For request level return status,

> SRM_SUCCESS

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

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

```{=html}
<!-- -->
```
-   *targetSpaceToken* does not refer to an existing known space in the
    SRM server.

> SRM_TOO_MANY_RESULTS

-   Request produced too many results that SRM server cannot handle, and
    *arrayOfSourceURLs and arrayOfTargetURLs* cannot fit the results to
    return.

> SRM_REQUEST_TIMED_OUT

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

> 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

-   Insufficient space left in the space that is associated with
    spaceToken.

> SRM_NO_FREE_SPACE

-   When client does not specify the spaceToken, SRM uses a default
    space. The default space is insufficient to accommodate the request.

> SRM_ABORTED

-   The request has been aborted.

> SRM_INTERNAL_ERROR

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

> SRM_NOT_SUPPORTED

-   SRM server does not support the given input parameters. For example,
    client requested bbftp for the only transfer protocol, but SRM
    cannot support that. Client requested *desiredFileStorageType* that
    is not supported by the SRM server.

-   *targetFileRetentionPolicyInfo* does not refer to a supported
    retention policy in the SRM server.

-   Overwrite option is not supported in the SRM server.

-   Directory operation is not supported in the SRM server.

-   Recursive directory operation is not supported in the SRM server.

-   any input parameter is not supported in the SRM server

-   a particular type of an input parameter is not supported in the SRM
    server

-   *function* is not supported in the SRM server

> 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 source *SURL* is
    copied into the target destination *targetSURL* successfully, and
    lifetime on the *targetSURL* is started.

> SRM_REQUEST_QUEUED

-   file request is still 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 not yet called) for.

> SRM_FILE_UNAVAILABLE

-   the request file (*sourceSURL*) is temporarily unavailable.

> SRM_FILE_LIFETIME_EXPIRED

-   lifetime on *targetSURL* has expired, but the file is still in the
    cache.

> SRM_INVALID_PATH

-   *sourceSUR* does not exist

-   *targetSURL* does not refer to a valid path.

> SRM_DUPLICATION_ERROR

-   *targetSURL* refers to an existing SURL without no overwriting
    option.

> SRM_AUTHORIZATION_FAILURE

-   Client is not authorized to copy files from *sourceSURL*

-   Client is not authorized to copy files into *targetSURL*

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

> SRM_ABORTED

-   The requested file has been aborted.

> SRM_RELEASED

-   The requested file has been released.

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

    1.  []{#__RefHeading___Toc139683314 .anchor}**srmReleaseFiles**

[]{#srmReleaseFiles .anchor}

This function is used to release pins on the previously requested
"copies" (or "state") of the SURL. This function normally follows
srmPrepareToGet or srmBringOnline functions.

1.  **Parameters**

In: string requestToken,

string authorizationID,

anyURI \[\] arrayOfSURLs[,]{.underline}

Boolean doRemove

Out: TReturnStatus [returnStatus,]{.underline}

> TSURLReturnStatus\[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  *doRemove* by default is false. If remove is true, the pin on the
    file is released, the "copy" or "state" is removed and SRM may
    release the resource.

b)  Directory is okay for SURL. In such case, it will release all files
    recursively in the directory.

c)  If requestToken is not provided, then the SRM will release all the
    files specified by the SURLs owned by this user, regardless of the
    requestToken.

d)  If requestToken is not provided, then authorizationID is needed. It
    may be inferred or provide in the call.

    1.  **Return Status Code**

For request level return status,

> SRM_SUCCESS

-   All requests are successfully completed. All *SURLs* are released
    successfully.

> SRM_PARTIAL_SUCCESS

-   All requests are completed. Some *SURLs* are successfully released,
    and some *SURLs* are failed. Details are on the files status.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to release files

> SRM_INVALID_REQUEST

-   *arrayOfSURLs* is empty.

```{=html}
<!-- -->
```
-   *requestToken* does not refer to an existing known request of
    *srmPrepareToGet* or *srmBringOnline* in the SRM server.

> 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

-   input parameter *doRemove* is not supported in the SRM. *srmRm* must
    be used.

For file level return status,

> SRM_SUCCESS

-   successful request completion for the *SURL. SURL* is released
    successfully.

> SRM_INVALID_PATH

-   *SURL* does not refer to an existing file

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to release *SURL*

> SRM_LAST_COPY

-   *SURL* is the last copy when *remove* flag is on

> SRM_FILE_LIFETIME_EXPIRED

-   *SURL* is expired already.

> SRM_ABORTED

-   The requested file has been aborted.

> SRM_FAILURE

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

    1.  []{#__RefHeading___Toc139683315 .anchor}**srmPutDone**

[]{#srmPutDone .anchor}

srmPutDone() is used to notify the SRM that the client completed a file
transfer to the TransferURL in the allocated space. This call should
normally follow srmPrepareToPut.

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID,

anyURI \[\] [arrayOfSURLs]{.underline}

Out: TReturnStatus [returnStatus,]{.underline}

> TSURLReturnStatus\[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Called by client after srmPrepareToPut() prepares the TURL and the
    client completes the file transfer into the prepared TURL.

    1.  **Return Status Code**

For request level return status,

> SRM_SUCCESS

-   All requests are successfully completed. *TURLs* contain data, and
    file lifetimes on the *SURLs* start.

> SRM_PARTIAL_SUCCESS

-   All requests are completed. Some file requests are successfully
    completed, and some file requests are failed. Details are on the
    files status.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to call the request specified by the
    *requestToken*

> SRM_INVALID_REQUEST

-   *arrayOfSURLs* is empty.

-   *requestToken* is empty.

-   *requestToken* does not refer to an existing known request in the
    SRM server.

> SRM_REQUEST_TIMED_OUT

-   Total request time is over and the request is failed.

> SRM_ABORTED

-   The request has been aborted.

> 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

For file level return status,

> SRM_SUCCESS

-   successful request completion of the "put done" for the *targetSURL*

> SRM_INVALID_PATH

-   *SURL* does not refer to an existing file request

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to call the request *srmPutDone*() on the
    *SURL*

> SRM_FILE_LIFETIME_EXPIRED

-   *targetSURL* has an expired *TURL*.

> SRM_SPACE_LIFETIME_EXPIRED

-   *targetSURL* has an expired space allocation.

> SRM_ABORTED

-   The requested SURL file has been aborted.

> SRM_FAILURE

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

    1.  []{#__RefHeading___Toc139683316 .anchor}**srmAbortRequest**

[]{#srmAbortRequest .anchor}

*srmAbortRequest*() allows clients to prematurely terminate asynchronous
requests of any types. It may involve data transfer requests initiated
by a call to *srmPrepareToGet*(), *srmBringOnline*(),
*srmPrepareToPut*() or *srmCopy*(). The effect of *srmAbortRequest*()
depends on the type of request. For data transfer request, the SRM will
attempt a complete cleanup of running transfers and files in
intermediate state.

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID

Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Terminate all files in the request regardless of the file state.
    Remove files from the queue, and release cached files if a limited
    lifetime is associated with the file. Expired files are released.

b)  Those files that are brought online with unlimited lifetime will
    remain in the space where they are brought in. and are not removed.
    Clients need to remove explicitly through *srmRm* or
    *srmPurgeFromSpace*.

c)  Abort must be allowed to all requests with *requestToken.*

    1.  **Return Status Code**

> SRM_SUCCESS

-   successful request completion. Request is aborted successfully.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to abort files in the request specified by
    the *requestToken*

> SRM_INVALID_REQUEST

-   *requestToken* does not refer to an existing known request in the
    SRM server.

> 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

    1.  []{#__RefHeading___Toc139683317 .anchor}**srmAbortFiles**

[]{#srmAbortFiles .anchor}

srmAbortFiles() allows clients to abort selective file requests from the
asynchronous requests of any type. It may include data transfer requests
initiated by a call to srmPrepareToGet(), srmBringOnline(),
srmPrepareToPut(), or srmCopy(). The effect of a srmAbortFiles() depends
on the type of the request.

1.  **Parameters**

In: string [requestToken,]{.underline}

anyURI \[\] [arrayOfSURLs,]{.underline}

string authorizationID

Out: TReturnStatus [returnStatus,]{.underline}

> TSURLReturnStatus\[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Abort all files in this call regardless of the state.

    1.  **Return Status Code**

For request level return status,

> SRM_SUCCESS

-   successful request completion. All *SURLs* are aborted successfully.

> SRM_PARTIAL_SUCCESS

-   All requests are completed. Some *SURLs* ares successfully aborted,
    and some *SURLs* are failed. Details are on the files status.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to abort files in the request specified by
    the *requestToken*

> SRM_INVALID_REQUEST

-   *arrayOfSURLs* is empty.

-   *requestToken* is empty.

-   *requestToken* does not refer to an existing known request in the
    SRM server.

> 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

For file level return status,

> SRM_SUCCESS

-   successful request completion for the *SURL. SURL* is aborted
    successfully.

> SRM_INVALID_PATH

-   *SURL* does not refer to an existing file request that is associated
    with the request token

> SRM_FAILURE

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

    1.  []{#__RefHeading___Toc139683318 .anchor}**srmSuspendRequest**

[]{#srmSuspendRequest .anchor}

srmSuspendedRequest is to suspend a previously submitted active request.

1.  **Parameters**

In: string [requestToken]{.underline}

string authorizationID

Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Suspend all files in this request until srmResumeRequest is issued.

    1.  **Return Status Code**

> SRM_SUCCESS

-   successful request completion. Request is suspended successfully.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to suspend the request specified by the
    *requestToken*

> SRM_INVALID_REQUEST

-   *requestToken* is empty.

```{=html}
<!-- -->
```
-   *requestToken* does not refer to an existing known request in the
    SRM server.

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

    1.  []{#__RefHeading___Toc139683319 .anchor}**srmResumeRequest**

[]{#srmResumeRequest .anchor}

srmResumeRequest is to resume previously suspended requestst**.**

1.  **Parameters**

In: string [requestToken,]{.underline}

string authorizationID

> Out: TReturnStatus [returnStatus]{.underline}

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Resume the previously suspended request.

    1.  **Return Status Code**

> SRM_SUCCESS

-   successful request completion. Request is resumed successfully.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to resume the request specified by the
    *requestToken*

> SRM_INVALID_REQUEST

-   *requestToken* is empty.

```{=html}
<!-- -->
```
-   *requestToken* does not refer to an existing known request in the
    SRM server.

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

    1.  []{#__RefHeading___Toc139683320 .anchor}**srmGetRequestSummary**

[]{#srmGetRequestSummary .anchor}

srmGetRequestSummary is to retrieve a summary of the previously
submitted request**.**

1.  **Parameters**

In: string \[\] [arrayOfRequestTokens,]{.underline}

string authorizationID

Out: TReturnStatus [returnStatus]{.underline}

> TRequestSummary\[\] arrayOfRequestSummaries

2.  **Return Status Code**

For request interface level return status,

> SRM_SUCCESS

-   All requests are successfully completed. All requests summaries are
    checked and returned successfully. Details are on the request
    status.

> SRM_PARTIAL_SUCCESS

-   All requests are completed. Summaries of some requests are
    successfully checked and returned, but some requests summaries are
    failed. Details are on the request status.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to get summary of the request specified by
    the *requestToken*

> SRM_INVALID_REQUEST

-   *arrayOfRequestTokens* 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

-   SRM failed to get summaries of all requests that are associated with
    request tokens.

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

For request level return status,

SRM_INVALID_REQUEST

-   *requestToken* does not refer to an existing known request in the
    SRM server.

> SRM_SUCCESS

-   The request has been completed successfully.

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

-   Total request time is over and the request is failed.

> SRM_REQUEST_SUSPENDED

-   The request has been suspended.

> SRM_ABORTED

-   The request has been aborted.

> SRM_PARTIAL_SUCCESS

-   All requests are completed. Some request is successfully completed,
    and some request is failed.

> SRM_FAILURE

-   The request is failed. *Explanation* needs to be filled for details.

    1.  []{#__RefHeading___Toc139683321
        .anchor}**srmExtendFileLifeTime**

srmExtendFileLifetime() allows clients to extend lifetime of existing
*SURL*s of volatile and durable file storage types or pinning lifetime
of *TURLs*. Those *TURLs* are of the results of *srmPrepareToGet* and
*srmPrepareToPut*.

1.  **Parameters**

In: string authorizationID,

> string requestToken[,]{.underline}

anyURI \[\] [arrayOfSURLs]{.underline}

int newFileLifetime

int newPinLifetime

Out: TReturnStatus [returnStatus]{.underline},

TSURLLifetimeReturnStatus \[\] arrayOfFileStatuses

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  *newPinLifetime* and *newFileLifetime* are relative to the calling
    time. Lifetime will be set from the calling time for the specified
    period.

b)  When extending pinning lifetime of *TURLs* with *newPinLifetime,
    requestToken* and *arrayOfSURLs* must be provided.

c)  When extending lifetime of *SURLs* with *newFileLifetime*,
    *requestToken* is optional.

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

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

f)  If *newPinLifetime* or *newFileLifetime* is not specified, the SRM
    can use its default to assign the *newPinLifetime* or
    *newFileLifetime*.

g)  Lifetime cannot be extended on the released files, aborted files,
    expired files, and suspended files.

h)  Extending file lifetime on SURL is similar to
    srmExtendFileLifetimeInSpace

    1.  **Return Status Code**

For request level return status,

> SRM_SUCCESS

-   All requests are successfully completed. All *SURLs* or *TURLs*
    associated with *SURLs* in the specified request have an extended
    lifetime. Details are on the files status.

> SRM_PARTIAL_SUCCESS

-   All requests are completed. Lifetimes on some *SURLs* or *TURLs* are
    successfully extended, and lifetimes on some *SURLs* or *TURLs* are
    failed to be extended. Details are on the files status.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to extend file lifetime

> SRM_INVALID_REQUEST

-   *requestToken* does not refer to an existing known request in the
    SRM server.

-   *requestToken* is not provided, and extending pinning lifetime of
    *TURLs* associated with *SURLs* require *requestToken*.

> 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

For file level return status,

> SRM_SUCCESS

-   successful request completion for the *SURL. SURL* or *TURL*
    associated with the *SURL* in the request has an extended lifetime.

> SRM_INVALID_PATH

-   *SURL* does not refer to an existing file

-   *SURL* does not refer to an existing file request that is associated
    with the request token

> SRM_FILE_LIFETIME_EXPIRED

-   Lifetime on *SURL* is expired already.

> SRM_ABORTED

-   The requested file has been aborted.

> SRM_RELEASED

-   The requested file has been released.

> SRM_FAILURE

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

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

    1.  []{#__RefHeading___Toc139683322 .anchor}**srmGetRequestTokens**

[]{#srmGetRequestTokens .anchor}

srmGetRequestTokens retrieves request tokens for the client's requests,
given client provided request description. This is to accommodate lost
request tokens. This can also be used for getting all request tokens.

1.  **Parameters**

In: string userRequestDescription,

string authorizationID

> Out: TReturnStatus [returnStatus]{.underline}
>
> TRequestTokenReturn\[\] arrayOfRequestTokens

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  If userRequestDescription is null, returns all requests this user
    has.

b)  If the user assigned the same name to multiple requests, he may get
    back multiple request IDs each with the time the request was made.

    1.  **Return Status Code**

> SRM_SUCCESS

-   successful request completion. Request tokens are returned
    successfully.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is notauthorized to get request tokens specified by the
    userRequestDescription

> SRM_INVALID_REQUEST

-   *userRequestDescription* does not refer to any existing known
    requests

> 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

6.  []{#__RefHeading___Toc139683323 .anchor}**Discovery Functions**

***summary:***

> [**srmGetTransferProtocols**](#srmGetTransferProtocols)
>
> [**srmPing**](#srmPing)

1.  []{#__RefHeading___Toc139683324 .anchor}**srmGetTransferProtocols**

    []{#srmGetTransferProtocols .anchor}

This function is to discover what transfer protocols are supported by
the SRM.

1.  **Parameters**

In: string authorizationID,

Out: TReturnStatus [returnStatus]{.underline},

TSupportedTransferProtocol \[\] protocolInfo

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  *srmGetTransferProtocols*() returns the supported file transfer
    protocols in the SRM with any additional information about the
    transfer protocol.

    1.  **Return Status Code**

> []{#OLE_LINK59 .anchor}SRM_SUCCESS

-   successful request completion. List of supported transfer protocols
    are returned successfully.

> SRM_AUTHENTICATION_FAILURE

-   SRM server failed to authenticate the client

> SRM_AUTHORIZATION_FAILURE

-   client is not authorized to request storage information

> 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

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

1.  **srmPing**

[]{#srmPing .anchor}

This function is used to check the state of the SRM. It works as an "are
you alive" type of call.

1.  **Parameters**

In: string authorizationID,

Out: string [versionInfo]{.underline}

TExtraInfo\[\] otherInfo

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  *srmPing*() returns a string containing SRM v2.2 version number as a
    minimal "up and running" information. For this particular SRM v2.2
    version, it must be "**v2.2**". Other versions may have "**v1.1**",
    "**v3.0**", and so on.

b)  Any additional information about the SRM can be provided in the
    output parameter *otherInfo*.

```{=html}
<!-- -->
```
7.  []{#__RefHeading___Toc139683326 .anchor}**Appendix**

    1.  []{#__RefHeading___Toc139683327 .anchor}**Status Code
        Specification**

**Note:**

-   Status codes represent errors, warnings and status.

-   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.  []{#__RefHeading___Toc139683328 .anchor}**SRM WSDL discovery
        method**

May 1, 2003

A\) SURL format:

**srm://**host\[:port\]**/**\[soap_end_point_path**?SFN=**\]site_file_name

where \[...\] means optional, and letters in bold are fixed.

We note if the SURL contains the soap_end_point_path, then it is not
possible to change the soap endpoint without changing all the previously
published SURLs.

Example SURLs:

Without soap_end_point_path:

srm://dm.lbl.gov:4001/ABC/file_x

with soap_end_point_path:

srm://dm.lbl.gov:4001/srm_servlet?SFN=ABC/file_x

B\) Given that soap-end-point-path clause is provided, then the soap
endpoint is:

https://host\[:port\]/soap_end_point_path

C\) If port is missing, the default port assumed is 8443, which is the
port for https with GSI.

The discussion below assumes no endpoint in the SURL, and shows how the
soap endpoints and wsdl can be found given an SURL

Issues:

1.  We wish to have a way of finding the SRM WSDL for multiple versions
    from the SURL.

2.  We wish to support clients that know what SRM version they want to
    use. For example, a client that uses version 1.1, should be able to
    got the WSDL and/or the SOAP endpoint for it directly.

3.  We wish to have a default where an SRM version number is not
    mentioned. The version returned in this case is whatever the SRM
    currently supports, or if multiple versions are supported, the SRM
    chooses what to return.

4.  We wish to allow a file accessed by a previous SRM version to be
    accessed by a future SRM version without having to change the SURL.
    Furthermore, if the file can be accessed by either version
    simultaneously (that depend on the SRM implementation) that should
    be possible too.

5.  We wish to have a way for a client to find out which version the SRM
    supports and the endpoint without having to read the WSDL. This is
    necessary in a changing world, where new version can be introduced.

6.  We wish to have a client that can use multiple SRM versions to find
    out which SRM version is supported by the SRM. This is probably the
    most realistic scenario, since we cannot expect all SRMs to support
    the same version at any one time.

7.  We wish to have a client find out which SRM versions are supported
    for accessing a particular file, in case that files can be accessed
    by multiple SRM versions simultaneously. This is related to point 3
    above.

This is a long wish list, but the proposed solution is simple. We assume
that the WSDL will contain the version number. First, we propose that
every SRM WSDL starts with:

SRM version number\--\> (e.g. \<!\--SRM version 2.1.3\--\>)

Now, the solution is as follows:

Give an SURL: srm://host\[:port\]/path/file (e.g.
srm://dm.lbl.gov:4001/ABC/file_x)

The following can be derived:

Case 1)

> For clients that know what SRM versions they want to use:
>
> https://host:port/srm/srm.version.wsdl
>
> https://host:port/srm/srm.version.endpoint
>
> For example, given the SURL above, and the client uses version 1.1,
> you derive:
>
> https://dm.lbl.gov:4001/srm/srm.1.1.wsdl
>
> https://dm.lbl.gov:4001/srm/srm.1.1.endpoint
>
> Note: the endpoint returned can be any URI, e.g.:
> https://gizmo.lbl.gov:10001/srm/v1.0
>
> or: https://dm.lbl.gov:12345/servlet/srm.1.1)

Case 2)

> For clients that don't know the version, and want to use the default:
>
> https://host:port/srm/srm.wsdl
>
> https://host:port/srm/srm.endpoint
>
> For the example above:
>
> https://dm.lbl.gov:4001/srm/srm.wsdl
>
> https://dm.lbl.gov:4001/srm/srm.endpoint

Case 3)

> For clients that want to find out the SRM version and endpoint without
> getting the entire WSDL:
>
> https://host:port/srm/srm.info
>
> The srm.info file will contain:
>
> \<!\--SRM version number\-- \--srmEndpoint\--\>
>
> For example:
>
> \<!\--SRM version 2.1.3\-- \-- https://gizmo.lbl.gov:10001/srm\--\>

Case 4)

> For servers that support multiple srm version accessing the SAME file:
>
> The same format as above repeating for each srm version.
>
> For example:
>
> \<!\--SRM version 1.1\-- \-- https://sdm.lbl.gov:5005/srm\--\>
>
> \<!\--SRM version 2.1.3\-- \-- https://gizmo.lbl.gov:10001/srm\--\>

To summarize, the following is what should be supported for WSDL and
endpoint discovery:

Given an SURL:

**srm://**host\[:port\]**/**site_file_name

The following can be derived:

a\) https://host\[:port\]/srm/srm\[.version\].wsdl

b\) https://host\[:port\]/srm/srm\[.version\].endpoint

c\) https://host\[:port\]/srm/srm.info

Where the content have the format repeated as many time as there are
supported versions:

\<!\--SRM version number\-- \--srmEndpoint\--\>

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--