**The Storage Resource Manager**

**Interface Specification**

**Version 2.2**

**2 April 2007**

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

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

+--------------------------+------------------------------------------+
| **Contributors:**        |                                          |
+==========================+==========================================+
| > **Timur Perelmutov**   | **Fermi National Accelerator Laboratory  |
| >                        | (FNAL), USA**                            |
| > **Don Petravick**      |                                          |
+--------------------------+------------------------------------------+
| > **Ezio Corso**         | **International Centre for Theoretical   |
| >                        | Physics (ICTO), Italy**                  |
| > **Luca Magnoni**       |                                          |
|                          | **Istituto Nazionale di Fisica Nucleare  |
|                          | (INFN), Italy**                          |
+--------------------------+------------------------------------------+
| > **Junmin Gu**          | **Lawrence Berkeley National Laboratory  |
|                          | (LBNL), USA**                            |
+--------------------------+------------------------------------------+
| > **Paolo Badino**       | **LHC Computing Project (LCG, CERN),     |
| >                        | Switzerland**                            |
| > **Olof Barring**       |                                          |
| >                        |                                          |
| > **Jean-Philippe Baud** |                                          |
| >                        |                                          |
| > **Flavia Donno**       |                                          |
| >                        |                                          |
| > **Maarten Litmaath**   |                                          |
+--------------------------+------------------------------------------+
| > **Shaun De Witt**      | **Rutherford Appleton Laboratory (RAL),  |
| >                        | England**                                |
| > **Jens Jensen**        |                                          |
+--------------------------+------------------------------------------+
| > Michael Haddox-Schatz  | **Thomas Jefferson National Accelerator  |
| >                        | Facility (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), **Istituto Nazionale di
Fisica Nucleare (INFN), International Centre for Theoretical Physics
(ICTO),** and European Organization for Nuclear Research (CERN) 2000,
2001, 2002, 2003, 2004, 2005, 2006, 2007. 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 5](#introduction)

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

[1. Common Type Definitions 7](#_Toc130102073)

[**1.1. File Storage Type** 7](#_Toc163229690)

[**1.2. File Type** 7](#_Toc163229691)

[**1.3. Retention Policy** 7](#_Toc163229692)

[**1.4. Access Latency** 7](#_Toc163229693)

[**1.5. Permission Mode** 8](#_Toc163229694)

[**1.6. Permission Type** 8](#_Toc163229695)

[**1.7. Request Type** 8](#_Toc163229696)

[**1.8. Overwrite Mode** 8](#_Toc163229697)

[**1.9. File Locality** 8](#_Toc163229698)

[**1.10. Access Pattern** 9](#_Toc163229699)

[**1.11. Connection Type** 9](#_Toc163229700)

[**1.12. Status Codes** 9](#_Toc163229701)

[**1.13. Retention Policy Info** 10](#_Toc163229702)

[**1.14. Request Token** 10](#_Toc163229703)

[**1.15. User Permission** 10](#_Toc163229704)

[**1.16. Group Permission** 11](#_Toc163229705)

[**1.17. Size in Bytes** 11](#_Toc163229706)

[**1.18. UTC Time** 11](#_Toc163229707)

[**1.19. Time in Seconds (Lifetime and RequestTime)**
11](#_Toc163229708)

[**1.20. SURL** 11](#_Toc163229709)

[**1.21. TURL** 12](#_Toc163229710)

[**1.22. Return Status** 12](#_Toc163229711)

[**1.23. Return Status for SURL** 12](#_Toc163229712)

[**1.24. File MetaData** 12](#_Toc163229713)

[**1.25. Space MetaData** 13](#_Toc163229714)

[**1.26. Directory Option** 13](#_Toc163229715)

[**1.27. Extra Info** 13](#_Toc163229716)

[**1.28. Transfer Parameters** 14](#_Toc163229717)

[**1.29. File Request for srmPrepareToGet** 14](#_Toc163229718)

[**1.30. File Request for srmPrepareToPut** 14](#_Toc163229719)

[**1.31. File Request for srmCopy** 14](#_Toc163229720)

[**1.32. Return File Status for srmPrepareToGet** 14](#_Toc163229721)

[**1.33. Return File Status for srmBringOnline** 15](#_Toc163229722)

[**1.34. Return File Status for srmPrepareToPut** 15](#_Toc163229723)

[**1.35. Return File Status for srmCopy** 15](#_Toc163229724)

[**1.36. Request Summary** 16](#_Toc163229725)

[**1.37. Return Status for SURL** 16](#_Toc163229726)

[**1.38. Return File Permissions** 16](#_Toc163229727)

[**1.39. Return Permissions on SURL** 16](#_Toc163229728)

[**1.40. Return Request Tokens** 17](#_Toc163229729)

[**1.41. Supported File Transfer Protocol** 17](#_Toc163229730)

[2. Space Management Functions 18](#_Toc163229731)

[**2.1. srmReserveSpace** 18](#_Toc163229732)

[**2.2. srmStatusOfReserveSpaceRequest** 20](#_Toc163229733)

[**2.3. srmReleaseSpace** 21](#_Toc163229734)

[**2.4. srmUpdateSpace** 23](#_Toc163229735)

[**2.5. srmStatusOfUpdateSpaceRequest** 24](#_Toc58129358)

[**2.6. srmGetSpaceMetaData** 25](#_Toc163229737)

[**2.7. srmChangeSpaceForFiles** 27](#_Toc163229738)

[**2.8. srmStatusOfChangeSpaceForFilesRequest** 29](#_Toc163229739)

[**2.9. srmExtendFileLifeTimeInSpace** 31](#_Toc163229740)

[**2.10. srmPurgeFromSpace** 33](#_Toc163229741)

[**2.11. srmGetSpaceTokens** 34](#_Toc163229742)

[3. Permission Functions 36](#_Toc163229743)

[**3.1. srmSetPermission** 36](#_Toc163229744)

[**3.2. srmCheckPermission** 37](#_Toc163229745)

[**3.3. srmGetPermission** 38](#_Toc163229746)

[4. Directory Functions 40](#_Toc163229747)

[**4.1. srmMkdir** 40](#_Toc163229748)

[**4.2. srmRmdir** 41](#_Toc163229749)

[**4.3. srmRm** 41](#_Toc163229750)

[**4.4. srmLs** 43](#_Toc163229751)

[**4.5. srmStatusOfLsRequest** 45](#_Toc163229752)

[**4.6. srmMv** 47](#_Toc136425010)

[5. Data Transfer Functions 49](#_Toc163229754)

[**5.1. srmPrepareToGet** 49](#_Toc163229755)

[**5.2. srmStatusOfGetRequest** 52](#_Toc163229756)

[**5.3. srmBringOnline** 55](#_Toc163229757)

[**5.4. srmStatusOfBringOnlineRequest** 59](#_Toc163229758)

[**5.5. srmPrepareToPut** 62](#_Toc163229759)

[**5.6. srmStatusOfPutRequest** 66](#_Toc163229760)

[**5.7. srmCopy** 69](#_Toc163229761)

[**5.8. srmStatusOfCopyRequest** 73](#_Toc163229762)

[**5.9. srmReleaseFiles** 76](#_Toc163229763)

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

[**5.11. srmAbortRequest** 79](#_Toc163229765)

[**5.12. srmAbortFiles** 80](#_Toc163229766)

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

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

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

[**5.16. srmExtendFileLifeTime** 84](#_Toc163229770)

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

[6. Discovery Functions 88](#_Toc163229772)

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

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

[7. Appendix 90](#_Toc163229775)

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

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

[**7.3. Changes log** 94](#_Toc163229778)

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

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

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

1.  []{#_Toc163229690 .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.  []{#_Toc163229691 .anchor}**File Type**

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

3.  []{#_Toc163229692 .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.  []{#_Toc163229693 .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.  []{#_Toc163229694 .anchor}**Permission Mode**

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

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

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

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

enum **TRequestType** { PREPARE\_TO\_GET,

PREPARE\_TO\_PUT,

COPY,

BRING\_ONLINE,

RESERVE\_SPACE,

UPDATE\_SPACE,

CHANGE\_SPACE\_FOR\_FILES,

> LS }

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

enum **TOverwriteMode** {NEVER,

> ALWAYS,
>
> WHEN\_FILES\_ARE\_DIFFERENT}

-   Use case for WHEN\_FILES\_ARE\_DIFFERENT can be that files are
    different when the declared size for an SURL is different from the
    actual one, or that the checksum of an SURL is different from the
    actual one.

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

9.  []{#_Toc163229698 .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. []{#_Toc163229699 .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. []{#_Toc163229700 .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. []{#_Toc163229701 .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
>
> }

-   SRM\_NOT\_SUPPORTED is used, in general

    -   If a server does not support a method

    -   If a server does not support particular optional input
        parameters

13. []{#_Toc163229702 .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. []{#_Toc163229703 .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.

-   Request tokens are case-sensitive.

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

15. []{#_Toc163229704 .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. []{#_Toc163229705 .anchor}**Group Permission**

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

TPermissionMode [mode]{.underline}

> } **TGroupPermission**

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

17. []{#_Toc163229706 .anchor}**Size in Bytes**

-   Size in bytes is represented in unsigned long.

18. []{#_Toc163229707 .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. []{#_Toc163229708 .anchor}**Time in Seconds (Lifetime and
    RequestTime)**

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

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

-   A negative value (-1) indicates "infinite (indefinite)" time.

-   Exceptions:

    -   Any "remaining" times may have zero (0) second when no time is
        left.

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

20. []{#_Toc163229709 .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. []{#_Toc163229710 .anchor}**TURL**

-   **TURL is represented in anyURI.**

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

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

string explanation

> } **TReturnStatus**

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

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

TReturnStatus [status]{.underline}

> } **TSURLReturnStatus**

24. []{#_Toc163229713 .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.

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

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

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

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

25. []{#_Toc163229714 .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.

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

-   *lifetimeLeft* is the remaining lifetime that is left on the space.

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

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

Boolean allLevelRecursive, // default = false

int numOfLevels // default = 1

> } **TDirOption**

27. []{#_Toc163229716 .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. []{#_Toc163229717 .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.

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

-   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. []{#_Toc163229718 .anchor}**File Request for srmPrepareToGet**

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

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

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

typedef struct { anyURI targetSURL , // local to SRM

unsigned long expectedFileSize

> } **TPutFileRequest**

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

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

anyURI [targetSURL,]{.underline}

> TDirOption dirOption
>
> } **TCopyFileRequest**

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

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

TReturnStatus [status]{.underline},

unsigned long [fileSize]{.underline},

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.

-   *estimatedWaitTime to be negative value, -1, for unknown.*

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

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

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

TReturnStatus [status]{.underline},

unsigned long [fileSize]{.underline},

int estimatedWaitTime,

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

-   *estimatedWaitTime to be negative value, -1, for unknown.*

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

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

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

TReturnStatus [status]{.underline},

> unsigned long [fileSize]{.underline},

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.

-   *estimatedWaitTime to be negative value, -1, for unknown.*

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

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

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

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

anyURI [targetSURL]{.underline},

TReturnStatus [status]{.underline},

unsigned long [fileSize]{.underline},

int estimatedWaitTime,

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

-   *estimatedWaitTime to be negative value, -1, for unknown.*

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

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

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

TReturnStatus [status]{.underline},

TRequestType requestType,

int totalNumFilesInRequest,

int numOfCompletedFiles,

int numOfWaitingFiles,

int numOfFailedFiles

> } **TRequestSummary**

-   *numOfWaitingFiles* describes the number of files on the queue.

-   *numOfFailedFiles* describes the number of failed files and aborted
    files.

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

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

37. []{#_Toc163229726 .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. []{#_Toc163229727 .anchor}**Return File Permissions**

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

TReturnStatus [status]{.underline},

TPermissionMode permission

> } **TSURLPermissionReturn**

39. []{#_Toc163229728 .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. []{#_Toc163229729 .anchor}**Return Request Tokens**

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

dateTime createdAtTime

> } **TRequestTokenReturn**

41. []{#_Toc163229730 .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.  **\
    **[]{#_Toc163229731 .anchor}**Space Management *Functions***

***summary:***

[**srmReserveSpace**](#_Toc163229732)

[**srmStatusOfReserveSpaceRequest**](#_Toc163229733)

[**srmReleaseSpace**](#_Toc163229734)

**[srmUpdateSpace](#srmUpdateSpace)**

[**srmGetSpaceMetaData**](#_Toc163229737)

[**srmChangeSpaceForFiles**](\l)

[**srmStatusOfChangeSpaceForFilesRequest**](\l)

[**srmExtendFileLifeTimeInSpace**](\l)

[**srmPurgeFromSpace**](\l)

[**srmGetSpaceTokens**](\l)

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

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

1.  **Parameters**

In: string authorizationID,

> String userSpaceTokenDescription,

TRetentionPolicyInfo [retentionPolicyInfo]{.underline},

> **unsigned long** desiredSizeOfTotalSpace[,]{.underline}
>
> **unsigned long** [desiredSizeOfGuaranteedSpace]{.underline},
>
> int 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)  *Input parameter userSpaceTokenDescription* is case-sensitive. SRM
    server is expected to keep it as client provides. It can be reused
    by the client. *srmGetSpaceTokens* will return all the space tokens
    that have the *userSpaceTokenDescription.*

b)  If the input parameter *desiredLifetimeOfReservedSpace* is not
    provided, the lifetime of the reserved space may be set to "infinite
    (indefinite)" by default.

c)  If particular values of the input parameter *retentionPolicyInfo*
    cannot be satisfied by the SRM server, SRM\_NOT\_SUPPORTED or
    SRM\_NO\_FREE\_SPACE must be returned.

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

e)  When asynchronous space reservation is necessary, the returned
    status code should be SRM\_REQUEST\_QUEUED.

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

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

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

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

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

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

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

m)  If an operation is successful (SRM\_SUCCESS or
    SRM\_LOWER\_SPACE\_GRANTED), *sizeOfGuaranteedReservedSpace*,
    *lifetimeOfReservedSpace* and *spaceToken* are required to return to
    the client.

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

    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\_**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\_AUTHENTICATION\_FAILURE**

-   **SRM server failed to authenticate the client**

> **SRM\_AUTHORIZATION\_FAILURE**

-   **client is not authorized to reserve space**

> **SRM\_INVALID\_REQUEST**

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

-   **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 server does not have enough free space for a particular
    > retentionPolicyInfo**

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

```{=html}
<!-- -->
```
-   specific values of the input parameter *retentionPolicyInfo* is not
    supported by the SRM

```{=html}
<!-- -->
```
-   **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.  []{#_Toc163229733 .anchor}**srmStatusOfReserveSpaceRequest**

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 server does not have enough free space for a particular
    > retentionPolicyInfo**

> **SRM\_**REQUEST\_SUSPENDED

-   **request is suspended.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

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

> **SRM\_NOT\_SUPPORTED**

-   ***function* is not supported in the SRM 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.  []{#_Toc163229734 .anchor}**srmReleaseSpace**

**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 OUTPUT or CUSTODIAL
    retention quality space.

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

d)  *If space is being released with forceFileRelease option while SURLs
    are being created with srmPrepareToPut or srmCopy, the file is
    removed and SRM\_INVALID\_PATH must be returned by the srmPutDone,
    srmStatusOfPutRequest, or srmStatusOfCopyRequest when the file is
    volatile. If the file is permanent type, the file is moved to the
    default space, and the space would be successfully released. The
    subsequent srmPutDone, srmStatusOfPutRequest, or
    srmStatusOfCopyRequest would be successful.*

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

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

    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} []{#_Toc163229735
        .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, and SRM\_INVALID\_REQUEST must be
    returned. The existing values must not be changed.

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

c)  *newLifetime* is the new lifetime requested regardless of the
    previous lifetime. It 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.

d)  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\_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**

[]{#_Toc58129358 .anchor}

1.  **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\_**REQUEST\_SUSPENDED

-   **request is suspended.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

-   **New requested size is less than currently used space.**

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

> **SRM\_NOT\_SUPPORTED**

-   ***function* is not supported**

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

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

1.  **Parameters**

In: string authorizationID,

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

Out: TReturnStatus [returnStatus,]{.underline}

> TMetaDataSpace\[\] arrayOfSpaceDetails

2.  **Notes on the Behavior**

```{=html}
<!-- -->
```
a)  Output parameters *unusedSize* in *TMetaDataSpace* returns 0 if
    there is no space left in the allocated space.

b)  When clients use more space than allocated, clients get warned to
    accommodate their files in the spaces or update the space before
    running out. SRM

    1.  **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\_EXCEED\_ALLOCATION**

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

> **SRM\_FAILURE**

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

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

This function is used to change the space property of files to another
space property by specifying target space tokens. All files specified by
SURLs will have a new space token. SURLs must not be changed. New space
token may be acquired from *srmReserveSpace*. Asynchronous operation may
be necessary for some SRMs, and in such case, request token 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. It includes changing spaces
    on SURLs that statuses are SRM\_FILE\_BUSY.

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

-   **The status of SURL is SRM\_FILE\_BUSY.**

> **SRM\_EXCEED\_ALLOCATION**

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

> SRM\_FILE\_LOST

-   the requested file with the SURL is permanently lost**.**

> SRM\_FILE\_BUSY

-   client requests for 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.  []{#_Toc163229739
        .anchor}**srmStatusOfChangeSpaceForFilesRequest**

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

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\_**REQUEST\_SUSPENDED

-   **request is suspended.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

-   **All file requests are failed.**

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

> **SRM\_NOT\_SUPPORTED**

-   ***function* is not supported in the SRM**

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

-   **The status of SURL is SRM\_FILE\_BUSY.**

> **SRM\_EXCEED\_ALLOCATION**

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

> **SRM\_**REQUEST\_SUSPENDED

-   **file request is suspended.**

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

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)  *arrayOfSURLs* are optional. When SURLs are not provided, all files
    in the space must have the new extended lifetimes.

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

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

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

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

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

g)  If input parameters *newLifeTime* request exceed the remaining
    lifetime of the space, then SRM\_SUCCESS is returned at the request
    and file level, and *TSURLLifetimeReturnStatus* contains the
    remaining lifetime.

h)  Lifetime extension must fail on SURLs when their status is
    SRM\_FILE\_BUSY.

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

    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\_SPACE\_LIFETIME\_EXPIRED**

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

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

-   **All file requests updating lifetimes in a space are failed.**

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

> **SRM\_NOT\_SUPPORTED**

-   ***function* is not supported in the SRM 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.  []{#_Toc163229741 .anchor}**srmPurgeFromSpace**

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

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

**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)  *Input parameter userSpaceTokenDescription* is case-sensitive. SRM
    server is expected to keep it as client provides. It can be reused
    by the client. *srmGetSpaceTokens* will return all the space tokens
    that have the *userSpaceTokenDescription.*

c)  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** *userSpaceTokenDescription*

> **SRM\_INVALID\_REQUEST**

-   *userSpaceTokenDescription* **does not refer to an existing space
    > description.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

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

> **SRM\_NOT\_SUPPORTED**

-   ***function* is not supported in the SRM server**

3.  **\
    **[]{#_Toc163229743 .anchor}**Permission *Functions***

***summary:***

> [**srmSetPermission**](#_Toc163229744)
>
> [**srmCheckPermission**](#_Toc163229745)
>
> [**srmGetPermission**](#_Toc163229746)

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

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.

j)  *srmSetPermission will modify permissions on SURLs even if the
    statuses of the SURLs are SRM\_FILE\_BUSY.*

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

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

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

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

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.  **\
    **[]{#_Toc163229747 .anchor}**Directory *Functions***

***summary:***

> [**srmMkdir**](#_Toc163229748)
>
> [**srmRmdir**](#_Toc163229749)
>
> [**srmRm**](#_Toc163229750)
>
> [**srmLs**](#srmLs)
>
> [**srmStatusOfLsRequest**](#_Toc163229752)

[**srmMv**](\l)

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

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

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

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

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

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.

f)  *srmRm will remove SURLs even if the statuses of the SURLs are
    SRM\_FILE\_BUSY. In this case, operations such as srmPrepareToPut or
    srmCopy that holds the SURL status as SRM\_FILE\_BUSY must return
    SRM\_INVALID\_PATH upon status request or srmPutDone.*

    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.  []{#_Toc163229751 .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 (numOfLevels=0) or a single file *, path, size,
        userPermission, lastModificationTime, type, fileLocality,* and
        *lifetimeLeft* are required to be returned, similar to unix
        command *ls --l*.

    -   For directories (numOfLevels=1) *, path, size, userPermission,
        lastModificationTime, and type* are required to be returned.

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)  **Default value of *numOfLevels* is 1 when not provided.**

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

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

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

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

k)  Empty directories will be returned.

l)  **For non-existing or system-prohibited file or directory browsing,
    SRM\_INVALID\_PATH must be returned. For non-supported file or
    directory browsing, SRM\_NOT\_SUPPORTED must be returned.
    *Explanation* needs to be filled for details.**

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

    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\_**REQUEST\_INPROGRESS

-   **Some files are completed, and some files are still on the queue.
    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 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.**

-   **Operation on the path such as browsing the top directory may be
    prohibited. *Explanation* needs to be filled for details.**

> **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\_**REQUEST\_INPROGRESS

-   **file request is being served.**

> **SRM\_**REQUEST\_QUEUED

-   **file request is still on the queue.**

> **SRM\_INVALID\_PATH**

-   ***SURL* does not refer to an existing known file path.**

> **SRM\_AUTHORIZATION\_FAILURE**

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

> SRM\_FILE\_BUSY

-   client requests for files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) for**.**

> **SRM\_FILE\_LIFETIME\_EXPIRED**

-   **lifetime on *SURL* is expired. There is no guarantee of the file
    still in the cache.**

> **SRM\_FILE\_IN\_CACHE**

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

> **SRM\_NOT\_SUPPORTED**

-   **Operation on the path such as browsing the top directory may be
    not supported. *Explanation* needs to be filled for details.**

> **SRM\_FAILURE**

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

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

**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\_**REQUEST\_INPROGRESS

-   **Some files are completed, and some files are still on the queue.
    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 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\_**REQUEST\_INPROGRESS

-   **file request is being served.**

> **SRM\_**REQUEST\_QUEUED

-   **file request is still on the queue.**

> **SRM\_INVALID\_PATH**

-   ***SURL* does not refer to an existing known file path**

> **SRM\_AUTHORIZATION\_FAILURE**

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

> SRM\_FILE\_BUSY

-   client requests for files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) for**.**

> **SRM\_FILE\_LIFETIME\_EXPIRED**

-   **lifetime on *SURL* is expired. There is no guarantee of the file
    still in the cache.**

> **SRM\_FILE\_IN\_CACHE**

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

> **SRM\_NOT\_SUPPORTED**

-   **Operation on the path such as browsing the top directory may be
    not supported. *Explanation* needs to be filled for details.**

> **SRM\_FAILURE**

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

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

srmMv is to move a file or a directory to destination.

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, and works like unix *mv***.

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

c)  *srmMv* must fail on SURL that its status is SRM\_FILE\_BUSY, and
    SRM\_INVALID\_REQUEST must be returned.

d)  Moving an SURL to itself results in no operation and SRM\_SUCCESS
    will be returned for no operation.

e)  When moving an SURL to already existing SURL,
    SRM\_DUPLICATION\_ERROR must be returned.

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

-   **status of *fromSURL* is SRM\_FILE\_BUSY.**

> **SRM\_DUPLICATION\_ERROR**

-   ***toSURL* exists already.**

> SRM\_FILE\_LOST

-   the requested file is permanently lost**.**

> SRM\_FILE\_BUSY

-   client requests for 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.  **\
    **[]{#_Toc163229754 .anchor}**Data Transfer *Functions***

**summary:**

> [**srmPrepareToGet**](#_Toc163229755)
>
> **[srmStatusOfGetRequest](\l)[srmPrepareToPut](#_Toc163229759)**
>
> **[srmStatusOfPutRequest](\l)[srmCopy](#_Toc163229761)**
>
> [**srmStatusOfCopyRequest**](\l)
>
> [**srmBringOnline**](\l)
>
> [**srmStatusOfBringOnlineRequest**](\l)
>
> [**srmReleaseFiles**](#_Toc163229763)
>
> [**srmPutDone**](#_Toc163229764)
>
> [**srmAbortRequest**](#_Toc163229765)
>
> [**srmAbortFiles**](#_Toc163229766)
>
> [**srmSuspendRequest**](#_Toc163229767)
>
> [**srmResumeRequest**](#_Toc163229768)
>
> [**srmGetRequestSummary**](#_Toc163229769)

[**srmExtendFileLifeTime**](#srmExtendFileLifeTime)

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

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

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)  Optional input parameters in *TTransferParameters* may collide with
    the characteristics of the space specified. In this case,
    *TTransferParameters* as an input parameter must be ignored.

```{=html}
<!-- -->
```
o)  The *userRequestDescription* is a user designated name for the
    request. *It* is case-sensitive. SRM server is expected to keep it
    as client provides. It can be reused by the client. It can be used
    in the *srmGetRequestTokens* function to get back the system
    assigned request tokens. *srmGetRequestTokens* will return all the
    request tokens that have the *userRequestDescription.*

```{=html}
<!-- -->
```
h)  Only pull mode is supported for file transfers that client must pull
    the files from the TURL within the expiration time
    (*remainingPinTime*).

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

j)  If request is accepted, SRM assigns the *requestToken* for
    asynchronous status checking. In such case, the returned status code
    should be SRM\_REQUEST\_QUEUED.

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

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

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

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

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

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

q)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*. In
    the output parameter of explanation in *returnStatus*, the server
    may make explicit that the retry is being done. If streaming mode is
    not supported, the server returns SRM\_NO\_USER\_SPACE or
    SRM\_NO\_FREE\_SPACE at the file level and SRM\_PARTIAL\_SUCCESS (if
    some file requests were successful) or SRM\_FAILURE at the request
    level.

r)  Zero length files must not fail on srmPrepareToGet.

    1.  **Return Status Code**

**For request level return status,**

> **SRM\_**REQUEST\_QUEUED

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

> **SRM\_**REQUEST\_INPROGRESS

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

> **SRM\_SUCCESS**

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

> **SRM\_PARTIAL\_SUCCESS**

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

> **SRM\_AUTHENTICATION\_FAILURE**

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

-   ***TURL is expired***

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

> **SRM\_NO\_USER\_SPACE**

-   **user space *is not enough to hold requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold requested SURL 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\_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.  []{#_Toc163229756 .anchor}**srmStatusOfGetRequest**

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)  Output parameter *remainingTotalRequestTime* indicates how long the
    *desiredTotalRequestTime* is left. If *remainingTotalRequestTime is
    0 (zero), the request has been timed out. If
    remainingTotalRequestTime is a negative value (-1), it would mean
    that each file request will be tried at least once.*

k)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. *remainingTotalRequestTime* is being returned. In
    the output parameter of explanation in *returnStatus*, the server
    may make explicit that the retry is being done. If streaming mode is
    not supported, the server returns SRM\_NO\_USER\_SPACE or
    SRM\_NO\_FREE\_SPACE at the file level and SRM\_PARTIAL\_SUCCESS (if
    some file requests were successful) or SRM\_FAILURE at the request
    level. Clients may need to release files or clean up the target
    space when target space token was provided.

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

    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\_**REQUEST\_SUSPENDED

-   **request is suspended.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

-   **All files requests are failed.**

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

**For file level return status,**

> SRM\_FILE\_PINNED

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

> **SRM\_**REQUEST\_QUEUED

-   **file request is on the queue.**

> **SRM\_**REQUEST\_INPROGRESS

-   **file request is being served.**

> **SRM\_ABORTED**

-   **The requested file has been aborted.**

> **SRM\_RELEASED**

-   **The requested file has been released.**

> **SRM\_**REQUEST\_SUSPENDED

-   **File request is suspended.**

> SRM\_FILE\_LOST

-   the requested file is permanently lost**.**

> SRM\_FILE\_BUSY

-   client requests for 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**

-   ***TURL is expired***

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

> **SRM\_NO\_USER\_SPACE**

-   **user space *is not enough to hold requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold requested SURL 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\_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.  []{#_Toc163229757 .anchor}**srmBringOnline**

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. By default
    *deferredStartTime* is 0 (zero) and the request gets queued or
    processed upon submission. Negative value is invalid.

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

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)  Optional input parameters in *TTransferParameters* may collide with
    the characteristics of the space specified. In this case,
    *TTransferParameters* as an input parameter must be ignored.

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

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* is case-sensitive. SRM server is expected to keep it
    as client provides. It can be reused by the client. It can be used
    in the *srmGetRequestTokens* function to get back the system
    assigned request tokens. *srmGetRequestTokens* will return all the
    request tokens that have the *userRequestDescription.*

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

k)  This call may be an asynchronous (non-blocking) call, and SRM
    assigns the *requestToken* when the request is valid 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)  *totalRequestTime* means: All the file transfer for this request
    must be complete within this *desiredTotalRequestTime*. Otherwise,
    SRM\_REQUEST\_TIMED\_OUT must be returned as the request status code
    with individual file status of SRM\_FAILURE with an appropriate
    explanation.

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

o)  If input parameter *desiredTotalRequestTime* is 0 (zero), each file
    request will be tried at least once. Negative value is not valid.

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

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

r)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. In the output parameter of explanation in
    *returnStatus*, the server may make explicit that the retry is being
    done. If streaming mode is not supported, the server returns
    SRM\_NO\_USER\_SPACE or SRM\_NO\_FREE\_SPACE at the file level and
    SRM\_PARTIAL\_SUCCESS (if some file requests were successful) or
    SRM\_FAILURE at the request level.

    1.  **Return Status Code**

**For request level return status,**

> **SRM\_**REQUEST\_QUEUED

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

> **SRM\_**REQUEST\_INPROGRESS

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

> **SRM\_SUCCESS**

-   **All requests are successfully completed. All *SURLs* are
    successfully brought online.**

> **SRM\_PARTIAL\_SUCCESS**

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

> **SRM\_AUTHENTICATION\_FAILURE**

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

-   ***deferredStartTime* is negative.**

> **SRM\_SPACE\_LIFETIME\_EXPIRED**

-   **space associated with the *targetSpaceToken is expired*.**

> **SRM\_EXCEED\_ALLOCATION**

-   **space associated with the *targetSpaceToken is not enough to hold
    all requested 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 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\_NO\_USER\_SPACE**

-   **user space *is not enough to hold requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold requested SURL 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\_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.  []{#_Toc163229758 .anchor}**srmStatusOfBringOnlineRequest**

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. Negative value is not
    valid.

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)  *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)  Output parameter *remainingTotalRequestTime* indicates how long the
    *desiredTotalRequestTime* is left. If *remainingTotalRequestTime is
    0 (zero), the request has been timed out. If
    remainingTotalRequestTime is a negative value (-1), it would mean
    that each file request will be tried at least once.*

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

l)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. *remainingTotalRequestTime* is being returned. In
    the output parameter of explanation in *returnStatus*, the server
    may make explicit that the retry is being done. If streaming mode is
    not supported, the server returns SRM\_NO\_USER\_SPACE or
    SRM\_NO\_FREE\_SPACE at the file level and SRM\_PARTIAL\_SUCCESS (if
    some file requests were successful) or SRM\_FAILURE at the request
    level. Clients may need to release files or clean up the target
    space when target space token was provided.

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

    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 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\_**REQUEST\_SUSPENDED

-   **request is suspended.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_FAILURE**

-   **All files requests are failed.**

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

**For file level return status,**

> SRM\_SUCCESS

-   **successful request completion for the *SURL. SURL* is successfully
    brought online.**

> **SRM\_**REQUEST\_QUEUED

-   **file request is on the queue.**

> **SRM\_**REQUEST\_INPROGRESS

-   **file request is being served.**

> **SRM\_AUTHORIZATION\_FAILURE**

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

> **SRM\_ABORTED**

-   **The requested file has been aborted.**

> **SRM\_RELEASED**

-   **The requested file has been released.**

> **SRM\_**REQUEST\_SUSPENDED

-   **File request is suspended.**

> SRM\_FILE\_LOST

-   the requested file is permanently lost**.**

> SRM\_FILE\_BUSY

-   client requests for 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\_NO\_USER\_SPACE**

-   **user space *is not enough to hold requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold requested SURL 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\_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.  []{#_Toc163229759 .anchor}**srmPrepareToPut**

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)  Optional input parameters in *TTransferParameters* may collide with
    the characteristics of the space specified. In this case,
    *TTransferParameters* as an input parameter must be ignored.

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

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

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

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

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

i)  Input parameter *targetSURL* in the *TPutFileRequest* has to be
    local to SRM. If *targetSURL* is not specified, SRM will generate a
    reference SURL 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*.

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

k)  Input parameter *desiredPinLifetime* is the lifetime (expiration
    time) on the TURL when the Transfer URL is prepared. It does not
    refer to the lifetime of the SURL. TURLs will not be valid any more
    after the *desiredPinLifetime is over if srmPutDone or
    srmAbortRequest is not submitted on the SURL before expiration. In
    such case, the server returns SRM\_FAILURE at the file level.*

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

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

n)  If request is accepted, SRM assigns the *requestToken* for
    asynchronous status checking. In such case, the returned status code
    should be SRM\_REQUEST\_QUEUED.

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

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

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

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

s)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. In the output parameter of explanation in
    *returnStatus*, the server may make explicit that the retry is being
    done. If streaming mode is not supported, the server returns
    SRM\_NO\_USER\_SPACE or SRM\_NO\_FREE\_SPACE at the file level and
    SRM\_PARTIAL\_SUCCESS (if some file requests were successful) or
    SRM\_FAILURE at the request level.

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

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

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

w)  After TURL is returned, *srmMv* operation on the corresponding SURL
    may be requested. *srmPutDone* on the original SURL will succeed,
    and SRM\_SUCCESS must be returned at the file level upon successful
    srmPutDone.

x)  Zero length files must not fail on srmPrepareToPut.

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

    1.  **Return Status Code**

**For request level return status,**

> **SRM\_**REQUEST\_QUEUED

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

> **SRM\_**REQUEST\_INPROGRESS

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

> **SRM\_SUCCESS**

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

> **SRM\_PARTIAL\_SUCCESS**

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

> **SRM\_AUTHENTICATION\_FAILURE**

-   **SRM 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 on the queue.**

> **SRM\_**REQUEST\_INPROGRESS

-   **file request is being served.**

> **SRM\_FILE\_IN\_CACHE**

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

> **SRM\_INVALID\_PATH**

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

> SRM\_DUPLICATION\_ERROR

-   ***targetSURL refers to an existing SURL and overwriting is not
    allowed.***

> SRM\_FILE\_BUSY

-   client requests for files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) or srmCopy for**.**

> **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\_NO\_USER\_SPACE**

-   **user space *is not enough to hold the requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold the requested SURL for free*.**

> **SRM\_FAILURE**

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

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

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

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

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

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. TURLs
    will not be valid any more after the *pin lifetime is over if
    srmPutDone or srmAbortRequest is not submitted on the SURL before
    expiration. In such case, the server returns SRM\_FAILURE at the
    file level.*

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)  Lifetime on SURL starts when successrul srmPutDone is executed.

g)  If the space for the requested files is full, and TURL cannot be
    returned, then SRM\_EXCEED\_ALLOCATION, SRM\_NO\_USER\_SPACE, or
    SRM\_NO\_FREE\_SPACE must be returned for the files.

h)  SRM must fail (SRM\_FAILURE) only if all files in the request
    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)  Output parameter *remainingTotalRequestTime* indicates how long the
    *desiredTotalRequestTime* is left. If *remainingTotalRequestTime is
    0 (zero), the request has been timed out. If
    remainingTotalRequestTime is a negative value (-1), it would mean
    that each file request will be tried at least once.*

k)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. *remainingTotalRequestTime* is being returned. In
    the output parameter of explanation in *returnStatus*, the server
    may make explicit that the retry is being done. If streaming mode is
    not supported, the server returns SRM\_NO\_USER\_SPACE or
    SRM\_NO\_FREE\_SPACE at the file level and SRM\_PARTIAL\_SUCCESS (if
    some file requests were successful) or SRM\_FAILURE at the request
    level. Clients may need to clean up the target space when target
    space token was provided.

l)  Upon srmPrepareToPut, SURL entry is inserted to the name space, and
    any methods that access the SURL such as srmLs, srmBringOnline and
    srmPrepareToGet must return SRM\_FILE\_BUSY at the file level. If
    another srmPrepareToPut or srmCopy were requested on the same SURL,
    SRM\_FILE\_BUSY must be returned if the SURL can be overwritten,
    otherwise SRM\_DUPLICATION\_ERROR must be returned at the file
    level.

m)  *srmRm may remove SURLs even if the statuses of the SURLs are
    SRM\_FILE\_BUSY. In this case, the status for srmPrepareToPut
    request must return SRM\_INVALID\_PATH upon status request or
    srmPutDone.*

n)  After TURL is returned, *srmMv* operation on the corresponding SURL
    may be requested. *srmPutDone* on the original SURL will succeed,
    and SRM\_SUCCESS must be returned at the file level upon successful
    srmPutDone.

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

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

-   **The request has been aborted.**

> **SRM\_**REQUEST\_SUSPENDED

-   **The request is suspended.**

> **SRM\_**INTERNAL\_ERROR

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

> **SRM\_NOT\_SUPPORTED**

-   **SRM 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 on the queue.**

> **SRM\_**REQUEST\_INPROGRESS

-   **file request is being served.**

> SRM\_SUCCESS

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

> **SRM\_FILE\_IN\_CACHE**

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

> **SRM\_INVALID\_PATH**

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

> SRM\_DUPLICATION\_ERROR

-   ***targetSURL refers to an existing SURL and overwriting is not
    allowed.***

> SRM\_FILE\_BUSY

-   client requests for files which there is an active srmPrepareToPut
    (no srmPutDone is not yet called) or srmCopy for**.**

> **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\_**REQUEST\_SUSPENDED

-   **File request is suspended.**

> **SRM\_NO\_USER\_SPACE**

-   **user space *is not enough to hold the requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold the requested SURL for free*.**

> **SRM\_FAILURE**

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

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

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

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

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

This function is used to copy files from source storage sites into the
target storage sites. The source storage site or the target storage site
needs to be the SRM itself that the client makes the *srmCopy* request.
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 userRequestDescription may be null, and it* is
    case-sensitive when provided. SRM server is expected to keep it as
    client provides. It can be reused by the client. It can be used in
    the *srmGetRequestTokens* function to get back the system assigned
    request tokens. *srmGetRequestTokens* will return all the request
    tokens that have the *userRequestDescription.*

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.

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)  If request is accepted, SRM assigns the *requestToken* for
    asynchronous status checking. In such case, the returned status code
    should be SRM\_REQUEST\_QUEUED.

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

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

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

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

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

m)  *totalRequestTime* means: if all the file transfer for this request
    must be complete in this *totalRequestTime*. Otherwise, the request
    is returned as failed at the end of the *totalRequestTime*, and
    SRM\_REQUEST\_TIMED\_OUT must be returned as the request status code
    with individual file status of SRM\_FAILURE with an appropriate
    explanation. All completed files must not be removed, but status of
    the files must be returned to the client.

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

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

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

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

r)  Empty directories are copied as well.

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

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

u)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. In the output parameter of explanation in
    *returnStatus*, the server may make explicit that the retry is being
    done. If streaming mode is not supported, the server returns
    SRM\_NO\_USER\_SPACE or SRM\_NO\_FREE\_SPACE at the file level and
    SRM\_PARTIAL\_SUCCESS (if some file requests were successful) or
    SRM\_FAILURE at the request level. Clients may need to clean up the
    target space when target space token was provided.

v)  Upon srmCopy, SURL entry is inserted to the target name space, and
    any methods that access the target SURL such as srmLs,
    srmBringOnline and srmPrepareToGet must return SRM\_FILE\_BUSY at
    the file level. If another srmPrepareToPut or srmCopy were requested
    on the same target SURL, SRM\_FILE\_BUSY must be returned if the
    target SURL can be overwritten, otherwise SRM\_DUPLICATION\_ERROR
    must be returned at the file level.

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

    1.  **Return Status Code**

**For request level return status,**

> **SRM\_**REQUEST\_QUEUED

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

> **SRM\_**REQUEST\_INPROGRESS

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

> **SRM\_SUCCESS**

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

> **SRM\_PARTIAL\_SUCCESS**

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

> **SRM\_AUTHENTICATION\_FAILURE**

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

-   client requests for files at the target (*targetSURL*) which there
    is an active srmPrepareToPut (no srmPutDone is not yet called) or
    srmCopy 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 and overwriting is not
    allowed.***

> **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\_NO\_USER\_SPACE**

-   **user space *is not enough to hold the requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold the requested SURL for free*.**

> **SRM\_FAILURE**

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

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

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

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

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)  Output parameter *remainingTotalRequestTime* indicates how long the
    *desiredTotalRequestTime* is left. If *remainingTotalRequestTime is
    0 (zero), the request has been timed out. If
    remainingTotalRequestTime is a negative value (-1), it would mean
    that each file request will be tried at least once.*

f)  Streaming mode is allowed. If streaming mode is supported and there
    is not enough space to hold the request or partially hold the
    request, the SRM server returns SRM\_REQUEST\_QUEUED and keeps
    trying the request for the duration of *desiredTotalRequestTime*
    from the request. *remainingTotalRequestTime* is being returned. In
    the output parameter of explanation in *returnStatus*, the server
    may make explicit that the retry is being done. If streaming mode is
    not supported, the server returns SRM\_NO\_USER\_SPACE or
    SRM\_NO\_FREE\_SPACE at the file level and SRM\_PARTIAL\_SUCCESS (if
    some file requests were successful) or SRM\_FAILURE at the request
    level. Clients may need to clean up the target space when target
    space token was provided.

g)  Upon srmCopy, SURL entry is inserted to the target name space, and
    any methods that access the target SURL such as srmLs,
    srmBringOnline and srmPrepareToGet must return SRM\_FILE\_BUSY at
    the file level. If another srmPrepareToPut or srmCopy were requested
    on the same target SURL, SRM\_FILE\_BUSY must be returned if the
    target SURL can be overwritten, otherwise SRM\_DUPLICATION\_ERROR
    must be returned at the file level.

h)  *srmRm may remove SURLs even if the statuses of the SURLs are
    SRM\_FILE\_BUSY. In this case, the status for srmCopy request must
    return SRM\_INVALID\_PATH upon status request.*

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

    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\_**REQUEST\_SUSPENDED

-   **The request is suspended.**

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

-   client requests for files at the target (*targetSURL*) which there
    is an active srmPrepareToPut (no srmPutDone is not yet called) or
    srmCopy 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 and overwriting is not
    allowed.***

> **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\_**REQUEST\_SUSPENDED

-   **File request is suspended.**

> **SRM\_NO\_USER\_SPACE**

-   **user space *is not enough to hold the requested SURL*.**

> **SRM\_NO\_FREE\_SPACE**

-   **SRM space *is not enough to hold the requested SURL for free*.**

> **SRM\_FAILURE**

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

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

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

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

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 and SURLs are provided, then the
    SRM will release all the files specified by the SURLs owned by the
    caller, regardless of the requestToken.*

d)  *If requestToken is provided and SURLs are not provided, then the
    SRM will release all the files in the request that is associated
    with the requestToken.*

e)  *At least one of requestToken and SURLs must be provided.*

f)  *If requestToken is not provided, then authorizationID may be needed
    as an additional verification method for the client authorization to
    release files. It may be inferred or provide in the call.*

g)  *srmReleaseFiles is only valid after srmPrepareToGet or
    srmBringOnline operations. To release TURLs after a srmPrepareToPut,
    srmAbortRequest or srmAbortFiles must be used. If a client submits
    srmReleaseFiles after srmPrepareToPut or srmPutDone, then the SRM
    server returns SRM\_INVALID\_REQUEST.*

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

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

b)  *srmRm may remove SURLs even if the statuses of the SURLs are
    SRM\_FILE\_BUSY. In this case, SRM\_INVALID\_PATH must be returned
    upon srmPutDone request.*

c)  If any additional *srmPutDone* is requested on the same SURL,
    SRM\_DUPLICATION\_ERROR must be returned at the file level.

d)  When srmPutDone is called on a subset of srmPrepareToPut request,
    the request level status for the srmPutDone must refer to the subset
    of the request that srmPutDone was called on.

e)  When srmPutDone is called without any file transfers into the TURL,
    SRM\_INVALID\_PATH must be returned at the file level status.

f)  Before srmPutDone is called, if one of the parent directories is
    "moved", srmPutDone on the old SURL must fail. The SURL must reflect
    the changes from the directory move.

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

-   **no file transfer was performed on the SURL**

> **SRM\_AUTHORIZATION\_FAILURE**

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

> **SRM\_DUPLICATION\_ERROR**

-   ***targetSURL* exists already.**

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

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

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

d)  When aborting srmCopy request, the request may contain one source
    SURL and multiple target SURLs. If the request is aborted by the
    source SURL, all file request of the same source SURL must be
    aborted. If the request is aborted by the target SURL, a specific
    target file request must be aborted, and other file requests from
    the same source SURL must not be aborted.

e)  When aborting srmPrepareToGet request, all uncompleted files must be
    aborted, and all successfully completed files must be released.

f)  When aborting srmPrepareToPut request before srmPutDone and before
    the file transfer, the SURL must not exist as the result of the
    successful abort on the SURL. *Any srmRm request on the SURL must
    fail.*

g)  When aborting srmPrepareToPut request before srmPutDone and after
    the file transfer, the SURL may exist, and a srmRm request on the
    SURL may remove the requested SURL.

h)  When aborting after srmPutDone, it must be failed for those files.
    An explicit srmRm is required to remove those successfully completed
    files for srmPrepareToPut.

i)  When duplicate abort request is issued on the same request,
    SRM\_SUCCESS may be returned to all duplicate abort requests and no
    operations on duplicate abort requests are performed.

    1.  **Return Status Code**

> **SRM\_SUCCESS**

-   **successful request completion. Request is aborted successfully.**

> **SRM\_PARTIAL\_SUCCESS**

-   **All requests are completed. Some *SURLs* are successfully aborted,
    and some *SURLs* are failed. Some abort may be failed because files
    were successfully completed already.**

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

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

b)  When aborting srmCopy request, the request may contain one source
    SURL and multiple target SURLs. If the request is aborted by the
    source SURL, all file request of the same source SURL must be
    aborted. If the request is aborted by the target SURL, a specific
    target file request must be aborted, and other file requests from
    the same source SURL must not be aborted.

c)  When aborting srmPrepareToGet file requests, all uncompleted files
    must be aborted, and all successfully completed files must be
    released.

d)  When aborting srmPrepareToPut file requests before srmPutDone and
    before the file transfers, the SURL must not exist as the result of
    the successful abort on the SURL. *Any srmRm request on the SURL
    must fail.*

e)  When aborting srmPrepareToPut file requests before srmPutDone and
    after the file transfer, the SURL may exist, and a srmRm request on
    the SURL may remove the requested SURL.

f)  When aborting after srmPutDone, it must be failed for those files.
    An explicit srmRm is required to remove those successfully completed
    files for srmPrepareToPut.

g)  This method must not change the request level status of the
    completed requests. Once a request is completed, the status of the
    request remains the same.

h)  When duplicate abort file request is issued on the same files,
    SRM\_SUCCESS may be returned to all duplicate abort file requests
    and no operations on duplicate abort file requests are performed.

    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* are 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 abort 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.  []{#_Toc163229767 .anchor}**srmSuspendRequest**

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

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

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

**srmExtendFileLifetime() allows clients to extend lifetime of existing
*SURL*s of volatile and durable file storage types or lifetime of
*pinned files (TURLs and t*hose *TURLs* are of the results of
*srmPrepareToGet,* *srmPrepareToPut or srmBringOnline*).**

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)  This method allows to change only one lifetime at a time (either
    SURL lifetime by the *newFileLifetime* or pin lifetime by the
    *newPinLifetime*), depending on the presence or absence of the
    request token. When both *newFileLifetime* and *newPinLifetime* are
    provided in the same request, the request is invalid, and
    SRM\_INVALID\_REQUST must be returned. SURL lifetimes are on SURLs
    that resulted from the successful srmCopy or srmPrepareToPut
    followed by srmPutDone, and pin lifetimes are on TURLs or file
    copies that resulted from srmPrepareToGet, srmPrepareToPut or
    srmBringOnline.

b)  *newPinLifetime* and *newFileLifetime* are relative to the calling
    time. Lifetime will be set from the calling time for the specified
    period.

c)  When the *requestToken* is provided, only pin lifetime is extended
    **with *newPinLifetime*.**

d)  When SURL lifetime is extended with ***newFileLifetime***, the
    request token must not be specified.

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

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

g)  When none of lifetime input parameters (*newPinLifetime* and
    *newFileLifetime*) is not specified, the SRM server does not change
    the lifetimes.

h)  Lifetime cannot be extended on the released files, aborted files,
    expired files, and suspended files. For example, pin lifetime cannot
    be extended after srmPutDone is requested on SURLs after
    srmPrepareToPut. In such case, SRM\_INVALID\_REQUEST at the file
    level must be returned, and SRM\_PARTIAL\_SUCCESS or SRM\_FAILURE
    must be returned at the request level.

i)  Extending file lifetime on SURL is similar to
    srmExtendFileLifetimeInSpace.

j)  If input parameters *newFileLifetime* or *newPinLifetime* request
    exceeds the remaining lifetime of the space, then SRM\_SUCCESS is
    returned at the request and file level, and
    *TSURLLifetimeReturnStatus* contains the remaining lifetime.

k)  Lifetime extension must fail on SURLs when their status is
    SRM\_FILE\_BUSY.

l)  This method intends to negotiate a request of extension of file or
    pin lifetime. When new lifetime request exceeds the remaining
    lifetime of the space where SURLs are, SRM\_SUCCESS is returned at
    the request level and at the file level, and
    TSURLLifetimeReturnStatus includes the remaining lifetime.

    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\_INVALID\_REQUEST**

-   **Attempt to extend pin lifetimes on TURLs that have been already
    expired.**

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

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 the client
    has.

b)  If the user assigned the same description to multiple requests, the
    client may get back multiple request tokens 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.  []{#_Toc163229772 .anchor}**Discovery *Functions***

***summary:***

> [**srmGetTransferProtocols**](\l)

[**srmPing**](\l)

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

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

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

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

    1.  []{#_Toc163229776 .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.  []{#_Toc163229777 .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\--\>

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

1.  []{#_Toc163229778 .anchor}**Changes log**

In regards to the discussion with WLCG Data Management Coordination
Group for the requirements of the LHC experiments of the Grid Storage
Interfaces, changes were made to the SRM v2.1.2 specification. The
changes are based on the 2-day meeting in May, 2006. The SRM version 2.2
changes extend and update the SRM v2.1.2 specification.

WSDL and Specification finalized: June 20, 2006

Revision history to the specification: July 3, 2006

July 6, 2006,

September 27, 2006 (includes WSDL changes),

December 15, 2006

January 22, 2007

April 2, 2007

All changes after the above date are grouped separately by dates.

1.  

2.  

3.  

4.  

5.  

6.  

7.  1.  

    2.  

    3.  1.  **June 20, 2006 from v2.1.1 to v2.2**

            1.  **In general**

-   If there is any discrepancy between SRM.v2.2.doc and
    SRM.v2.2.ws.op.doc, then lines in the SRM.v2.2.doc will take the
    precedence.

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

-   Some attribute names were changed to be consistent throughout the
    paper. Attributes have an indication of multiple values by having a
    plural form.

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

    1.  **In the Defined Structure:**

```{=html}
<!-- -->
```
-   Space types (TSpaceType) are removed.

-   TAccessLatency is added.

-   TRetentionPolicy is added.

-   Together with TAccessLatency and TRetentionPolicy,
    TRetentionPolicyInfo is added, and TRetentionPolicy is required when
    TRetentionPolicyInfo is provided.

-   TRequestType is expanded.

-   TGMTTime becomes TUTCTime.

-   TFileLocality is added.

-   TMetaDataPathDetail is changed slightly

-   TMetaDataSpace is changed slightly

-   TExtraInfo is added for key/value pairs of additional information.

-   TStorageSystemInfo is removed, and is used as TExtraInfo\[\].

-   TAccessPattern is added.

-   TConnectionType is added.

-   TTransferParameters is added to replace the string array of
    arrayOfTransferProtocols parameter.

-   "None" from TPermissionMode became "NONE"

-   TRequestType has capitals: PREPARE\_TO\_GET, PREPARE\_TO\_PUT and
    COPY.

-   TRequestType has additional BRING\_ONLINE, RESERVE\_SPACE,
    UPDATE\_SPACE, CHANGE\_SPACE\_FOR\_FILES, and LS.

-   TLifeTimeInSeconds and TSizeInBytes had "unsigned long" in the spec,
    but "long" in the WSDL file. They are corrected to have "unsigned
    long" in WSDL.

-   TGetFileRequest, TPutFileRequest, and TCopyFileRequest are
    simplified.

-   SRM\_UNAUTHORIZED\_ACCESS is changed to SRM\_AUTHORIZATION\_FAILURE
    to cover any unauthorized failures.

-   TStatusCode has a few more status codes: SRM\_PARTIAL\_SUCCESS,
    SRM\_REQUEST\_TIMED\_OUT, SRM\_LAST\_COPY, SRM\_FILE\_BUSY,
    SRM\_FILE\_LOST, and SRM\_FILE\_UNAVAILABLE.

-   TUserPermission, TGroupPermission, TSURLPermissionReturn, and
    TRequestTokenReturn have the required parameters. Those parameters
    are required when the type information is being provided.

-   isExpired parameter is removed from TMetaDataSpace.
    SRM\_SPACE\_LIFETIME\_EXPIRED may be used instead.

-   {Volatile, Durable, Permanent} becomes {VOLATILE, DURABLE,
    PERMANENT}

-   {File, Directory, Link} becomes {FILEPATH, DIRECTORY, LINK}

-   { Never, Always, WhenFilesAreDifferent} becomes { NEVER, ALWAYS,
    WHEN\_FILE\_ARE\_DIFFERENT}

-   {TransferMode, ProcessingMode} becomes { TRANSFER\_MODE,
    PROCESSING\_MODE}

-   TRequestSummary has \"isSuspended\" removed

-   TRequestToken is removed to be string (xsd:string)

-   TSpaceToken is removed to be string (xsd:string)

-   TUserID is removed to be string (xsd:string)

-   TGroupID is removed to be string (xsd:string)

-   TOwnerPermission is removed and TPermissionMode is used.

-   TOtherPermission is removed and TPermissionMode is used.

-   Checksum types (TCheckSumType, TCheckSumValue) are removed and
    string (xsd:string) is used.

-   TSizeInBytes is removed and unsigned long (xsd:unsignedLong) is used

-   TUTCTime is removed and dateTime (xsd:dateTime) is used

-   TLifeTimeInSeconds is removed and int (xsd:int) is used

-   "infinite" lifetime is agreed.

-   TSURL is removed and anyURI (xsd:anyURI) is used

-   TTURL is removed and anyURI (xsd:anyURI) is used

-   SURLInfo is removed. anyURI is used instead for SURLs and storage
    system info is moved at the request level.

-   TSURLLifetimeReturnStatus is added for srmExtendFileLifeTime

    1.  **In the Space Reservation Functions:**

```{=html}
<!-- -->
```
-   Retention policy is introduced as a way of indicating quality of the
    space where files are located.

-   Access latency is also introduced to describe how latency of files
    is improvable.

-   srmReserveSpace has new input parameters.

-   srmReserveSpace is now asynchronous, and
    srmStatusOfReserveSpaceRequest is added for checking status of the
    asynchronous srmReserveSpace.

-   TMetaDataSpace includes retention policy information instead of
    previous space types.

-   srmChangeSpaceForFiles is added to change the storage token of
    files. Since it may take a long time to complete the request, it may
    be an asynchronous operation, and
    srmStatusOfChangeSpaceForFilesRequest is added.

-   srmExtendFileLifetimeInSpace is added to extend lifefime for all
    files in a space that is associated with a space token.

-   srmCompactSpace is removed

-   srmPurgeFromSpace is added.

-   srmStatusOfUpdateSpaceRequest is added for an asynchronous operation
    for srmUpdateSpace.

-   In srmExtendFileLifetimeInSpace, new file lifetime must not exceed
    the remaining lifetime of the space.

-   srmChangeSpaceForFiles (2.7.2, 2.7.3) has a note for target space
    when it cannot hold all files

    1.  **In the Permission Functions:**

```{=html}
<!-- -->
```
-   srmReassignToUser is removed.

-   srmSetPermission (3.1.2) has a note about CHANGE permission type for
    non-existing user/group.

-   srmCheckPermission (3.2.2 ) has \"localCheckOnly\" removed.

-   srmGetPermission is added.

    1.  **In the Directory Functions:**

```{=html}
<!-- -->
```
-   TMetaDataPathDetail includes the assigned retention policy and file
    locality.

-   srmLs has TSURL and TStorageSystemInfo separately from the
    previously combined TSURLInfo as input parameters.

-   srmLs may be an asynchronous operation, and srmStatusOfLsRequest is
    added.

-   srmLs has limited permission returns.

    1.  **In the Data Transfer Functions:**

-   srmReleaseFiles has an optional remove flag to remove the "copy" or
    "state" from the space.

-   srmRemoveFiles has been removed.

-   Client access pattern is added to indicate the possible usage
    pattern of the TURL.

-   Client connection type is added to indicate the possible connection
    to the TURL.

-   TTransferParameters is added to combine the client input parameters
    for array of client supported transfer protocol list, client access
    pattern, client connection type and array of client networks.

-   Array of client network indicates IP addresses that client has a
    possible access to.

-   TExtraInfo is added for additional information as a key/value pair.
    It may be used for the returned transfer protocol of TURL. It may
    indicate the properties of the transfer protocol so that the client
    can optimize the date transfer.

-   srmPrepareToGet and srmStatusOfGetRequest have updated input
    parameters.

-   srmPrepareToPut and srmStatusOfPutRequest have updated input
    parameters.

-   srmCopy and srmStatusOfCopyRequest have updated input parameters.

-   srmBringOnline and srmStatusOfBringOnlineRequest are added.

-   srmGetRequestTokens is changed from srmGetRequestID.

-   srmExtendFileLifeTime has two newLifetime input parameters, one for
    pin lifetime for TURL, and another for file lifetime for SURL.

-   srmExtendFileLifeTime has arrayOfSURLs as required.

-   srmPrepareToGet/BringOnline/Put/Copy has notes changed on
    totalRequestTime to indicate default time and trying at least once.

-   Total request time "0" (zero) indicates that SRM will try at least
    once for each file in the request.

-   srmPrepareToGet/BringOnline/Put/Copy has notes on timed-out
    requests.

-   srmPrepareToPut (5.5.2-h) adds \"Some SRM implementation may require
    targetSURL.\"

-   srmExtendFileLifeTime has a lifetime paired with the SURLs in
    return.

    1.  **In the Information Discovery Functions:**

-   srmGetTransferProtocols is added for clients to discover the
    supported transfer protocols by SRM.

-   srmPing is added for clients to check the status of the SRM.

    1.  **July 3, 2006**

-   TMetaDataPathDetails as an output of srmLs includes unix-like
    permission returns: ownerPermission, groupPermission, and
    otherPermission. {owner,group}Permission must show {owner,group} id
    and the {owner,group} permission.

    1.  **July 6, 2006**

-   Behavior on srmPurgeFromSpace is changed for clarity. (more to come
    later)

-   SRM\_FILE\_BUSY status is removed from srmRm for it is a hard
    remove.

    1.  **September 27, 2006**

-   srmLs: TMetaDataPathDetail has path as string, instead of SURL as
    anyURI. Path reflects an absolute path of a file or a directory.

-   srmMkdir, srmRmdir: input parameter directoryPath becomes SURL.

-   srmReleaseFiles: input parameter arrayOfSURLs becomes not required.
    When request token is provided and SURLs are not provided, all files
    in the request will be released.

-   WSDL : extra output parameter in srmExtendFileLifeTimeInSpace is
    removed. The extra output parameter is not in the spec.

    1.  **December 15, 2006**

-   Typos fixed

    -   From srmGetRequestID to srmGetRequestTokens

-   srmLs and srmStatusOfLsRequest

    -   SRM\_FILE\_BUSY is added

    -   SRM\_FILE\_LIFETIME\_EXPIRED is added

    -   SRM\_REQUEST\_INPROGRESS is returned at the request level and
        file level.

    -   A comment of "**Operation on the path such as browsing the top
        directory may be prohibited" is added to the
        SRM\_INVALID\_PATH.**

-   srmStatusOfLsRequest

    -   SRM\_REQUEST\_INPROGRESS is returned at the request level and
        file level.

-   srmReleaseSpace

    -   b\) will be changed to OUTPUT or CUSTODIAL retention quality
        space, from durable or permanent space which no longer exists as
        definitions.

    -   *If space is being released with forceFileRelease option while
        SURLs are being created with srmPrepareToPut or srmCopy, the
        file is removed and SRM\_INVALID\_PATH must be returned by the
        srmPutDone, srmStatusOfPutRequest, or srmStatusOfCopyRequest
        when the file is volatile. If the file is permanent type, the
        file is moved to the default space, and the space would be
        successfully released. The subsequent srmPutDone,
        srmStatusOfPutRequest, or srmStatusOfCopyRequest would be
        successful.*

    -   *If space is being released without forceFileRelease option
        while SURLs are being created with srmPrepareToPut or srmCopy,
        SRM\_FAILURE must be returned in srmReleaseSpace.*

-   srmReleaseFiles: clarified the comments;

    -   *If requestToken is not provided and SURLs are provided, then
        the SRM will release all the files specified by the SURLs owned
        by the caller, regardless of the requestToken.*

    -   *If requestToken is provided and SURLs are not provided, then
        the SRM will release all the files in the request that is
        associated with the requestToken.*

    -   *At least one of requestToken and SURLs must be provided.*

    -   *If requestToken is not provided, then authorizationID may be
        needed as an additional verification method for the client
        authorization to release files. It may be inferred or provide in
        the call.*

    -   *srmReleaseFiles is only valid after srmPrepareToGet or
        srmBringOnline operations. To release TURLs after a
        srmPrepareToPut, srmAbortRequest or srmAbortFiles must be used.
        If a client submits srmReleaseFiles after srmPrepareToPut or
        srmPutDone, then the SRM server returns SRM\_INVALID\_REQUEST.*

-   srmExtendFileLifeTime: behavior gets clarified:

    -   This method allows to change only one lifetime at a time (either
        SURL lifetime by the *newFileLifetime* or pin lifetime by the
        *newPinLifetime*), depending on the presence or absence of the
        request token. SURL lifetimes are on SURLs that resulted from
        the successful srmCopy or srmPrepareToPut followed by
        srmPutDone, and pin lifetimes are on TURLs or file copies that
        resulted from srmPrepareToGet, srmPrepareToPut or srmBringOnline

    -   When the *requestToken* is provided, only pin lifetime is
        extended **with *newPinLifetime.***

    -   When SURL lifetime is extended with ***newFileLifetime***, the
        request token must not be specified.

    -   When lifetime input parameters (*newPinLifetime* or
        *newFileLifetime*) are not specified, the SRM server uses its
        default value.

    -   Lifetime cannot be extended on the released files, aborted
        files, expired files, and suspended files. For example, pin
        lifetime cannot be extended after srmPutDone is requested on
        SURLs after srmPrepareToPut. In such case, SRM\_INVALID\_REQUEST
        at the file level must be returned, and SRM\_PARTIAL\_SUCCESS or
        SRM\_FAILURE must be returned at the request level.

    -   If input parameters *newFileLifetime* or *newPinLifetime*
        request exceeds the remaining lifetime of the space, then
        SRM\_SUCCESS is returned at the request and file level, and
        *TSURLLifetimeReturnStatus* contains the remaining lifetime.

    -   Lifetime extension must fail on SURLs when their status is
        SRM\_FILE\_BUSY.

    -   **SRM\_INVALID\_REQUEST is added at the file level.**

-   srmExtendFileLifeTimeInSpace: added comments

    -   If input parameters *newLifetime* request exceed the remaining
        lifetime of the space, then SRM\_SUCCESS is returned at the
        request and file level, and *TSURLLifetimeReturnStatus* contains
        the remaining lifetime.

    -   Lifetime extension must fail on SURLs when their status is
        SRM\_FILE\_BUSY.

    -   *arrayOfSURLs* are optional. When SURLs are not provided, all
        files in the space must have the new extended lifetimes.

    -   This method applied only to SURLs, and output parameter
        *pinLifetime* in *TSURLLifetimeReturnStatus* must be null

-   srmUpdateSpace

    -   Output parameter, *lifetimeGranted* is clarified as it is
        relative to the calling time.

-   srmReserveSpace

    -   includes SRM\_REQUEST\_INPROGRESS as a valid return status.

    -   Data type of input parameter desiredLifetimeOfReservedSpace is
        corrected to be int.

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

-   srmGetSpaceMetaData

    -   description about the unusedSize is added.

    -   **SRM\_EXCEED\_ALLOCATION is added at the space level.**

-   srmRm

    -   *srmRm will remove SURLs even if the statuses of the SURLs are
        SRM\_FILE\_BUSY. In this case, operations such as
        srmPrepareToPut or srmCopy that holds the SURL status as
        SRM\_FILE\_BUSY must return SRM\_INVALID\_PATH upon status
        request or srmPutDone.*

-   *srmSetPermission*

    -   *srmSetPermission will modify permissions on SURLs even if the
        statuses of the SURLs are SRM\_FILE\_BUSY.*

-   *srmMv*

    -   *srmMv* must fail on SURL that its status is SRM\_FILE\_BUSY,
        and SRM\_INVALID\_REQUEST must be returned.

-   srmPrepareToGet

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

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

-   srmBringOnline

    -   If input parameter *desiredTotalRequestTime* is 0 (zero), each
        file request will be tried at least once. Negative value is not
        valid

    -   Output parameter *remainingDeferredStartTime* indicates how long
        the deferredStartTime is left, if supported. Negative value is
        not valid.

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

-   srmPrepareToPut

    -   comments added: TURLs will not be valid any more after the
        *desiredPinLifetime is over if srmPutDone or srmAbortRequest is
        not submitted on the SURL before expiration.*

    -   Upon srmPrepareToPut, SURL entry is inserted to the name space,
        and any methods that access the SURL such as srmLs,
        srmBringOnline and srmPrepareToGet must return SRM\_FILE\_BUSY
        at the file level. If another srmPrepareToPut or srmCopy were
        requested on the same SURL, SRM\_FILE\_BUSY must be returned if
        the SURL can be overwritten, otherwise SRM\_DUPLICATION\_ERROR
        must be returned at the file level.

    -   Input parameter *desiredFileLifetime* is the lifetime of the
        SURL when the file is put into the storage system. It does not
        refer to the lifetime (expiration time) of the TURL. Lifetime on
        SURL starts when successrul srmPutDone is executed.

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

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

-   srmStatusOfPutRequest

    -   comments added: TURLs will not be valid any more after the *pin
        lifetime is over if srmPutDone or srmAbortRequest is not
        submitted on the SURL before expiration.*

    -   Lifetime on SURL starts when successrul srmPutDone is executed

    -   SRM\_ABORTED is returned at the request level at the successful
        abort of the request.

    -   SRM\_NO\_USER\_SPACE, SRM\_NO\_FREE\_SPACE and SRM\_FILE\_BUSY
        are added at the file level status.

    -   *srmRm may remove SURLs even if the statuses of the SURLs are
        SRM\_FILE\_BUSY. In this case, the status for srmPrepareToPut
        request must return SRM\_INVALID\_PATH upon status request or
        srmPutDone.*

-   *srmPutDone*

    -   *srmRm may remove SURLs even if the statuses of the SURLs are
        SRM\_FILE\_BUSY. In this case, SRM\_INVALID\_PATH must be
        returned upon srmPutDone request.*

    -   If any additional *srmPutDone* is requested on the same SURL,
        SRM\_DUPLICATION\_ERROR must be returned at the file level.

-   srmCopy

    -   Upon srmCopy, SURL entry is inserted to the target name space,
        and any methods that access the target SURL such as srmLs,
        srmBringOnline and srmPrepareToGet must return SRM\_FILE\_BUSY
        at the file level. If another srmPrepareToPut or srmCopy were
        requested on the same target SURL, SRM\_FILE\_BUSY must be
        returned if the target SURL can be overwritten, otherwise
        SRM\_DUPLICATION\_ERROR must be returned at the file level.

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

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

-   srmStatusOfCopyRequest

    -   *srmRm may remove SURLs even if the statuses of the SURLs are
        SRM\_FILE\_BUSY. In this case, the status for srmCopy request
        must return SRM\_INVALID\_PATH upon status request.*

-   Request Token

    -   Includes a statement about the lifetime of the request token.

-   User request/space descriptions

    -   *Statement that userRequest\[Space\]Description may be null, and
        it* is case-sensitive when provided. SRM server is expected to
        keep it as client provides. It can be reused by the client. It
        can be used in the *srmGetRequest\[Space\]Tokens* function to
        get back the system assigned request or space tokens.

-   **Streaming mode**

    -   **srmPrepareToGet, srmStatusOfGetRequest, srmBringOnline,
        srmStatusOfBringOnlineRequest, srmPrepareToPut,
        srmStatusOfPutRequest, srmCopy, srmStatusOfCopyRequest**

    -   **added comments**

    -   SRM\_NO\_USER\_SPACE and SRM\_NO\_FREE\_SPACE are added at the
        file level status.

-   estimatedWaitTime

    -   TGetRequestFileStatus, TBringOnlineRequestFileStatus,
        TPutRequestFileStatus, TCopyRequestFileStatus

    -   Negative value, -1, for unknown.

-   Transfer parameters

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

-   TMetaDataPathDetail: added comments

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

    -   *lifetimeLeft* is the remaining lifetime that is left on the
        SURL.

-   TMetaDataSpace: added comments

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

    -   *lifetimeLeft* is the remaining lifetime that is left on the
        space.

        1.  **January 22, 2007**

-   Typo

    -   srmCopy has input parameter desiredTargetSURLLifeTime for
        corresponding WSDL parameter.

-   srmUpdateSpace

    -   neither size not time is provided, SRM\_INVALID\_REQUEST is
        returned

-   srmLs

    -   default numOfLevels is 1.

    -   Added note (l) for browsing **non-existing, non-supported, or
        system-prohibited file or directory**

-   **srmPrepareToPut**

    -   **removed file level status SRM\_SUCCESS that never happens**

-   **TPutFileRequest**

    -   **Removed a duplicate note**

-   **Time in seconds**

    -   **Behavior contains for both life time and request time, and
        exceptions are specified.**

-   **TRequestSummary**

    -   *numOfWaitingFiles* describes the number of files on the queue.

    -   *numOfFailedFiles* describes the number of failed files and
        aborted files.

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

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

-   *TOverwriteMode*

    -   For srmPrepareToPut and srmCopy, input parameter
        *overwriteOption* is assumed to be NEVER when not specified.

-   SRM\_REQUEST\_SUSPENDED

    -   Added for a possible return status for
        srmStatusOfReserveSpaceRequest, srmStatusOfUpdateSpaceRequest,
        srmStatusOfChangeSpaceForFilesRequest, srmStatusOfGetRequest,
        srmStatusOfBringOnlineRequest, srmStatusOfPutRequest and
        srmStatusOfCopyRequest

-   srmExtendFileLifetimeInSpace

    -   underline of input parameter arrayOfSURLs is corrected to be
        optional.

-   srmExtendFileLifetime -- behavior gets explicit

    -   added that when both *newFileLifetime* and *newPinLifetime* are
        provided in the same request, the request is invalid, and
        SRM\_INVALID\_REQUST must be returned.

-   *srmAbortRequest*

    -   SRM\_PARTIAL\_SUCCESS added as a return status to cover a case
        when some files in a request were aborted, and failed because
        they were completed successfully already.

-   srmAbortFiles

    -   added: (b) When aborting srmCopy request, the request may
        contain one source SURL and multiple target SURLs. If the
        request is aborted by the source SURL, all file request of the
        same source SURL must be aborted. If the request is aborted by
        the target SURL, a specific target file request must be aborted,
        and other file requests from the same source SURL must not be
        aborted.

-   srmReserveSpace

    -   when input parameter retentionPolicyInfo is not supported by
        SRM, SRM\_NOT\_SUPPORTED must be returned.

        1.  **April 6, 2007**

-   srmLs and srmStatusOfLsRequest

    -   SRM\_REQUEST\_QUEUED is added

    -   SRM\_NOT\_SUPPORTED is added at the file level for non-supported
        top directory browsing

    -   Updated: (c) If fullDetailedList is true, the full details are
        returned.

        -   For directories (numOfLevels=0) or a single file , path,
            size, userPermission, lastModificationTime, type,
            fileLocality, and lifetimeLeft are required to be returned,
            similar to unix command ls --l.

        -   For directories (numOfLevels=1) , path, size,
            userPermission, lastModificationTime, and type are required
            to be returned.

-   srmMv

    -   Added: (d) Moving an SURL to itself results in no operation and
        SRM\_SUCCESS will be returned for no operation.

    -   Added: (e) When moving an SURL to already existing SURL,
        SRM\_DUPLICATION\_ERROR must be returned.

-   srmRmdir

    -   Added: (d) When only expired volatile files are in the requested
        directory, srmRmdir must allow the removal of the requested
        directory regardless of the expired files. The SURL of the
        expired volatile files must no longer exist in the file system,
        and may or may not be removed right away physically depending on
        the internal server policy.

-   srmExtendFileLifeTime

    -   Added: (l) This method intends to negotiate a request of
        extension of file or pin lifetime. When new lifetime request
        exceeds the remaining lifetime of the space where SURLs are,
        SRM\_SUCCESS is returned at the request level and at the file
        level, and TSURLLifetimeReturnStatus includes the remaining
        lifetime.

    -   Updated: (g) When none of lifetime input parameters
        (*newPinLifetime* and *newFileLifetime*) is not specified, the
        SRM server does not change the lifetimes,

-   srmExtendFileLifeTimeInSpace

    -   Udated: (f) If *newLifeTime* is not specified, the SRM does not
        change the lifetime.

    -   Added SRM\_SPACE\_LIFETIME\_EXPIRED at the request level status

-   srmAbortRequest

    -   Added: (d) When aborting srmCopy request, the request may
        contain one source SURL and multiple target SURLs. If the
        request is aborted by the source SURL, all file request of the
        same source SURL must be aborted. If the request is aborted by
        the target SURL, a specific target file request must be aborted,
        and other file requests from the same source SURL must not be
        aborted.

    -   Added: (e) When aborting srmPrepareToGet request, all
        uncompleted files must be aborted, and all successfully
        completed files must be released.

    -   Added: (f) When aborting srmPrepareToPut request before
        srmPutDone and before the file transfer, the SURL must not exist
        as the result of the successful abort on the SURL. Any srmRm
        request on the SURL must fail.

    -   Added: (g) When aborting srmPrepareToPut request before
        srmPutDone and after the file transfer, the SURL may exist, and
        an srmRm request on the SURL may remove the requested SURL.

    -   Added: (h) When aborting after srmPutDone, it must be failed for
        those files. An explicit srmRm is required to remove those
        successfully completed files for srmPrepareToPut.

    -   Added: (i) When duplicate abort request is issued on the same
        request, SRM\_SUCCESS may be returned to all duplicate abort
        requests and no operations on duplicate abort requests are
        performed.

    -   Updated: (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.*

-   *srmAbortFiles*

    -   Added: (c) When aborting srmPrepareToGet file requests, all
        uncompleted files must be aborted, and all successfully
        completed files must be released.

    -   Added: (d) When aborting srmPrepareToPut file requests before
        srmPutDone and before the file transfers, the SURL must not
        exist as the result of the successful abort on the SURL. Any
        srmRm request on the SURL must fail.

    -   Added: (e) When aborting srmPrepareToPut file requests before
        srmPutDone and after the file transfer, the SURL may exist, and
        a srmRm request on the SURL may remove the requested SURL.

    -   Added: (f) When aborting after srmPutDone, it must be failed for
        those files. An explicit srmRm is required to remove those
        successfully completed files for srmPrepareToPut.

    -   Added: (g) This method must not change the request level status
        of the completed requests. Once a request is completed, the
        status of the request remains the same.

    -   Added: (h) When duplicate abort file request is issued on the
        same files, SRM\_SUCCESS may be returned to all duplicate abort
        file requests and no operations on duplicate abort file requests
        are performed.

-   *Status Codes (1.12)*

    -   Adeed: SRM\_NOT\_SUPPORTED is used, in general

        -   If a server does not support a method

        -   If a server does not support particular optional input
            parameters

-   Overwrite Mode (1.8)

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

-   srmReserveSpace

    -   Added: (b) If the input parameter
        *desiredLifetimeOfReservedSpace* is not provided, the lifetime
        of the reserved space may be set to "infinite (indefinite)" by
        default.

    -   Updated: (c) If particular values of the input parameter
        *retentionPolicyInfo* cannot be satisfied by the SRM server,
        SRM\_NOT\_SUPPORTED or SRM\_NO\_FREE\_SPACE must be returned

-   srmReleaseSpace

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

-   srmPrepareToPut

    -   Added: (v) When requested file storage type is VOLATILE, it
        cannot be promoted to PERMANENT to avoid complexities in space
        accounting and other cleanup tasks. SRM\_NOT\_SUPPORTED must be
        returned if the requested file storage type is not supported, or
        the request must be processed.

    -   Added: (w) After TURL is returned, *srmMv* operation on the
        corresponding SURL may be requested. *srmPutDone* on the
        original SURL will succeed, and SRM\_SUCCESS must be returned at
        the file level upon successful srmPutDone.

    -   Added: (x) Zero length files must not fail on srmPrepareToPut.

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

-   srmPutDone

    -   Added: (d) When srmPutDone is called on a subset of
        srmPrepareToPut request, the request level status for the
        srmPutDone must refer to the subset of the request that
        srmPutDone was called on.

    -   Added: (e) When srmPutDone is called without any file transfers
        into the TURL, SRM\_INVALID\_PATH must be returned at the file
        level status.

    -   Added: (f) Before srmPutDone is called, if one of the parent
        directories is "moved", srmPutDone on the old SURL must fail.
        The SURL must reflect the changes from the directory move.

-   srmPrepareToGet

    -   Added: (r) Zero length files must not fail on srmPrepareToGet.

-   TGetRequestFileStatus, TBringOnlineRequestFileStatus,
    TPutRequestFileStatus, TCopyRequestFileStatus

    -   fileSize is required as output parameter

-   srmStatusOfGetRequest, srmStatusOfBringOnlineRequest,
    srmStatusOfPutRequest, srmStatusOfCopyRequest

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