emc centera sdk for xam version 1.0 vim reference guide · 8/19/2008 · carnegie mellon...

EMC Centera® SDK for XAMVIM

Version 1.0

Reference GuideP/N 300-007-642

REV A01

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748-9103

1-508-435-1000www.EMC.com

2

Copyright © 2008 EMC Corporation. All rights reserved.

Published August, 2008

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.

All other trademarks used herein are the property of their respective owners.

Third-Party License Agreements

EMC Centera Software Development Kit

The EMC Software Development Kit (SDK) contains the intellectual property of EMC Corporation or is licensed to EMC Corporation from third parties. Use of this SDK and the intellectual property contained therein is expressly limited to the terms and conditions of the License Agreement.

Use of GPL

The EMC® version of Linux® , used as the operating system on the EMC Centera server, is a derivative of Red Hat® and SuSE Linux. The operating system is copyrighted and licensed pursuant to the GNU General Public License (GPL), a copy of which can be found in the accompanying documentation. Please read the GPL carefully, because by using the Linux operating system on the EMC Centera server, you agree to the terms and conditions listed therein.

SKINLF

This product includes software developed by L2FProd.com (http://www.L2FProd.com/).

Bouncy Castle

The Bouncy Castle Crypto package is Copyright © 2000 of The Legion Of The Bouncy Castle (http://www.bouncycastle.org).

RSA Data Security

Copyright © 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.

License to copy and use this software is granted provided that it is identified as the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing this software or this function. RSA Data Security, Inc. makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. It is provided "as is" without express or implied warranty of any kind.

These notices must be retained in any copies of any part of this documentation and/or software.

EMC Centera SDK for XAM Version 1.0 VIM Reference Guide

ICU License (IBM International Component on Unicode library)

Copyright (c) 1995-2002 International Business Machines Corporation and others. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE

Apache Software Foundation

Software from the Apache Software Foundation is included, which comprises certain Apache software including Apache Axis 1.2 and Apache Multipart Parser. Copyright 1999-2006 The Apache Software Foundation. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

ReiserFS

ReiserFS is hereby licensed under the GNU General Public License version 2.

Source code files that contain the phrase "licensing governed by reiserfs/README" are "governed files" throughout this file. Governed files are licensed under the GPL. The portions of them owned by Hans Reiser, or authorized to be licensed by him, have been in the past, and likely will be in the future, licensed to other parties under other licenses. If you add your code to governed files, and don't want it to be owned by Hans Reiser, put your copyright label on that code so the poor blight and his customers can keep things straight. All portions of governed files not labeled otherwise are owned by Hans Reiser, and by adding your code to it, widely distributing it to others or sending us a patch, and leaving the sentence in stating that licensing is governed by the statement in this file, you accept this. It will be a kindness if you identify whether Hans Reiser is allowed to license code labeled as owned by you on your behalf other than under the GPL, because he wants to know if it is okay to do so and put a check in the mail to you (for non-trivial improvements) when he makes his next sale. He makes no guarantees as to the amount if any, though he feels motivated to motivate contributors, and you can surely discuss this with him before or after contributing. You have the right to decline to allow him to license your code contribution other than under the GPL.

Further licensing options are available for commercial and/or other interests directly from Hans Reiser: [email protected]. If you interpret the GPL as not allowing those additional licensing options, you read it wrongly, and Richard Stallman agrees with me, when carefully read you can see that those restrictions on additional terms do not apply to the owner of the copyright, and my interpretation of this shall govern for this license.

Finally, nothing in this license shall be interpreted to allow you to fail to fairly credit me, or to remove my credits, without my permission, unless you are an end user not redistributing to others. If you have doubts about how to properly do that, or about what is fair, ask. (Last I spoke with him Richard was contemplating

EMC Centera SDK for XAM Version 1.0 VIM Reference Guide 3

4

how best to address the fair crediting issue in the next GPL version.)

MIT XML Parser

MIT XML Parser software is included. This software includes Copyright (c) 2002,2003, Stefan Haustein, Oberhausen, Rhld., Germany

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Carnegie Mellon University

Copyright 1994 by Carnegie Mellon University. All Rights Reserved.

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Carnegie Mellon University not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Carnegie Mellon University makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


Contents

Preface

Chapter 1 IntroductionXAM overview .................................................................................... 8XAM architecture................................................................................ 9

XAM process flow ......................................................................10VIM architecture ............................................................................... 12XAM objects....................................................................................... 13

Chapter 2 XAM-based Field OperationsXSystem connection.......................................................................... 16

VIM discovery.............................................................................16XSystem authentication ................................................................... 18

Reauthentication .........................................................................19XSystem and XSet authorization .................................................... 20XAM fields ......................................................................................... 21

Configuration settings .............................................................. 22XAM Library fields........................................................................... 23

Predefined global fields .............................................................23Options as global configuration fields.....................................25Application registration fields ................................................. 30

XSystem fields ................................................................................... 31FPPool capabilities fields.......................................................... 34FPPoolInfo fields........................................................................ 38Options as XSystem configuration fields ................................39

XSet fields........................................................................................... 40Profile XSet field ........................................................................ 41


Contents

Chapter 3 XSet OperationsXSet overview.................................................................................... 44

EMC Centera XUID................................................................... 44XSet operations ................................................................................. 45

XSet delete ................................................................................... 45XSet query.................................................................................... 46XSet import and export.............................................................. 47XSet export................................................................................... 47XSet import.................................................................................. 48

Conversion of legacy data ............................................................... 49Default conversion behavior..................................................... 49FPTag, metadata, and attribute conversion............................ 50Conversion of legacy data to numbered fields ...................... 52Compression of converted field names................................... 53

XSet retention management ............................................................ 54Retention levels.......................................................................... 54Order of precedence .................................................................. 54Retention types .......................................................................... 54Retention time criteria .............................................................. 55Management properties............................................................ 61

XSet hold management .................................................................... 62

Chapter 4 VIM LoggingLogging overview............................................................................. 64

Logging order of precedence .................................................... 64VIM logging fields ............................................................................ 65VIM logging configuration file ....................................................... 68VIM logging environment variables.............................................. 69

Polling behavior.......................................................................... 71Log file format............................................................................. 72

Chapter 5 XAM and VIM Error CodesError handling................................................................................... 76XAM error codes............................................................................... 77VIM error codes ................................................................................ 79

Chapter 6 Programming NotesCompatibility notes .......................................................................... 88

Feature differences .................................................................... 89XAM application considerations .................................................... 90

EMC Centera SDK for XAM Version 1.0 VIM Reference Guide6

Contents

Authentication............................................................................ 90Performance................................................................................ 90Fields............................................................................................ 91

Programming tips ............................................................................. 92

Glossary

Index

7EMC Centera SDK for XAM Version 1.0 VIM Reference Guide

Contents


Title Page

Tables

1 XAM objects and SDK equivalents ............................................................... 132 Mapping of XAM granules to capability settings....................................... 203 Field levels........................................................................................................ 224 Predefined XAMLibrary fields...................................................................... 235 Global options as XAMLibrary fields........................................................... 256 Application registration XAM Library object/XSystem fields................. 307 Predefined XSystem fields ............................................................................. 318 FPPool capabilities as XAMLibrary/XSystem fields ................................. 349 FPPoolInfo XSystem fields............................................................................. 3810 Int options on XSystem fields........................................................................ 3911 Predefined XSet fields..................................................................................... 4012 FPPoolInfo XSystem fields............................................................................. 4113 XUID byte format ............................................................................................ 4414 Conversion of tag elements ........................................................................... 5015 Numbered field ............................................................................................... 5216 Retention base/event settings ....................................................................... 5617 XSet retention management properties........................................................ 6118 XSet hold properties........................................................................................ 6219 Predefined logging fields ............................................................................... 6520 Logging environment variables .................................................................... 6921 XAM error codes ............................................................................................. 7722 EMC Centera VIM error codes ...................................................................... 79


Tables


Title Page

Examples

1 XUID in string format .................................................................................... 442 Nested tag conversion ................................................................................... 513 Custom metadata tags to field names ......................................................... 514 Tag names as numbered field ....................................................................... 525 Compressed field names ............................................................................... 536 Enabling logging ........................................................................................... 677 VIM logging configuration file ..................................................................... 688 XML-formatted log ........................................................................................ 739 Tab-formatted log ........................................................................................... 74


Examples


Preface

As part of an effort to improve and enhance the performance and capabilities of its product lines, EMC periodically releases revisions of its hardware and software. Therefore, some functions described in this document may not be supported by all versions of the software or hardware currently in use. For the most up-to-date information on product features, refer to your product release notes.

If a product does not function properly or does not function as described in this document, please contact your EMC representative.

Audience This document is part of the EMC Centera documentation set, and is intended for use by software developers who are developing XAM-based (eXtensible Access Method) applications to interface with the EMC Centera cluster via the EMC Centera VIM (Vendor Interface Module). It is also intended as a reference guide for system administrators who need to integrate enterprise applications based on the XAM technology and the EMC Centera VIM.

Note: This document is an adjunct to the set of XAM SDK specifications available from and distributed by SNIA (Storage Networking Industry Association). A working knowledge of the XAM technology and XAM public interfaces is assumed. “Related documentation” on page 4 lists the available SNIA XAM specifications.

Readers of this guide are expected to be familiar with the following topics:

◆ Content Addressed Storage (CAS)◆ XAM technology◆ EMC Centera architecture and features


4

Preface

Supported platforms EMC Centera SDK for XAM supports the following platforms in 32-bit and 64-bit, where applicable:

◆ AIX 5.2 and higher◆ HP-UX 11i (B.11.11 PA-RISC)◆ HP-UX 11iv2 (B.11.23 Itanium)◆ Linux GCC3.3 (X86)◆ Linux GCC4 (X86)◆ SunOS 5.8 and higher (SPARC)◆ Microsoft Windows 2000 SP4 and higher (32-bit only)◆ Microsoft Windows Server 2003 and higher (X86)

Note: EMC Centera SDK for XAM v1.0 requires the use of CentraStar v4.0.1 (or higher) on the target EMC Centera.

Relateddocumentation

Related documents include:

◆ Information Management —Extensible Access Method (XAM) – Part 1: Architecture, Version 1.0

◆ Information Management – Extensible Access Method (XAM) – Part 2: C API, Version 1.0

◆ Information Management – Extensible Access Method (XAM) – Part 3: Java API, Version 1.0

You can request these publications from the SNIA website at http://www.snia.org/forums/xam/technology/specs/.

Conventions used inthis document

EMC uses the following conventions for special notices.

Note: A note presents information that is important, but not hazard-related.

CAUTION!A caution contains information essential to avoid data loss or damage to the system or equipment.

IMPORTANT!An important notice contains information essential to operation of the software.


http://www.snia.org/forums/xam/technology/specs/

Preface

WARNING

A warning contains information essential to avoid a hazard that can cause severe personal injury, death, or substantial property damage if you ignore the warning.

DANGER

A danger notice contains information essential to avoid a hazard that will cause severe personal injury, death, or substantial property damage if you ignore the message.

Typographical conventionsEMC uses the following type style conventions in this document:

Normal Used in running (nonprocedural) text for:• Names of interface elements (such as names of windows,

dialog boxes, buttons, fields, and menus)• Names of resources, attributes, pools, Boolean expressions,

buttons, DQL statements, keywords, clauses, environment variables, functions, utilities

• URLs, pathnames, filenames, directory names, computer names, filenames, links, groups, service keys, file systems, notifications

Bold Used in running (nonprocedural) text for:• Names of commands, daemons, options, programs,

processes, services, applications, utilities, kernels, notifications, system calls, man pages

Used in procedures for:• Names of interface elements (such as names of windows,

dialog boxes, buttons, fields, and menus)• What user specifically selects, clicks, presses, or types

Italic Used in all text (including procedures) for:• Full titles of publications referenced in text• Emphasis (for example a new term)• Variables

Courier Used for:• System output, such as an error message or script • URLs, complete paths, filenames, prompts, and syntax when

shown outside of running text

Courier bold Used for:• Specific user input (such as commands)


6

Preface

Where to get help EMC support, product, and licensing information can be obtained as follows.

Product information — For documentation, release notes, software updates, or for information about EMC products, licensing, and service, go to the EMC Powerlink website (registration required) at:

http://Powerlink.EMC.com

Technical support — For technical support, go to EMC Customer Service on Powerlink. To open a service request through Powerlink, you must have a valid support agreement. Please contact your EMC sales representative for details about obtaining a valid support agreement or to answer any questions about your account.

Your comments Your suggestions will help us continue to improve the accuracy, organization, and overall quality of the user publications. Please send your opinion of this document to:

[email protected]

Courier italic Used in procedures for:• Variables on command line• User input variables

< > Angle brackets enclose parameter or variable values supplied by the user

[ ] Square brackets enclose optional values

| Vertical bar indicates alternate selections - the bar means “or”

{ } Braces indicate content that you must specify (that is, x or y or z)

... Ellipses indicate nonessential information omitted from the example


http://Powerlink.EMC.com

1

This chapter provides an overview of the architectures defined for the SNIA-distributed public XAM interfaces and the EMC Centera SDK for XAM Vendor Interface Module (VIM). The main sections are:

◆ XAM overview ..................................................................................... 8◆ XAM architecture ................................................................................. 9◆ VIM architecture................................................................................. 12◆ XAM objects ........................................................................................ 13

Introduction

Introduction 7

8

Introduction

XAM overview XAM (eXtensible Access Method) is the technology that supports a client-side framework and the use of a standard API for XAM-based applications to interface with XAM-compliant storage systems. XAM was developed by the Storage Networking Industry Association (SNIA), a consortium of storage platform providers.

This technology enables the metadata of fixed content (also known as reference information) to be commonly represented in data exchanges between applications and reference information storage systems. Applications can store and manage fixed content with multiple XAM storage providers concurrently. Conversely, multiple applications can access supported versions of the same XAM-compliant storage system concurrently.

In addition to XAM enabling application interoperability, other benefits include:

◆ Storage transparency◆ Retention compliance◆ Automated ILM-based practices◆ Standardized data management capabilities◆ Information security

For more information on XAM, visit the SNIA website at http://www.snia.org/xam.


http://www.snia.org/xam

Introduction

XAM architectureThe XAM architecture is a software framework consisting of the following main components:

◆ XAM Library and XAM API — The XAM Library is a thin software layer that defines bindings for either a XAM C API or a Java API implementation. The XAM Library manages an application’s ability to access and interact with multiple vendor storage systems via the XAM public APIs.

◆ Optional XAM Toolkit Extension Libraries — The XAM framework includes a supplemental set of extension libraries. This toolkit library contains interfaces to simplify the programming of XAM client applications.

◆ VIM API, Reference VIM Library, and optional vendor VIM Library — A VIM Library, which is loaded by the XAM Library when the application connects to an an XSystem, enables the XAM Library to communicate directly with the storage system via the VIM API.

The SNIA XAM specifications located at http://www.snia.org/forums/xam/technology/specs/ contain detailed information about each XAM component.

XAM architecture 9


10

Introduction

Figure 1 on page 10 shows a component view of the XAM architecture, which flows logically from the application level:

Figure 1 XAM architecture

XAM process flowFrom a high-level perspective, the following events occur when XAM-enabled applications interact with the XAM components:

1. Via the XAM API, the application specifies an XRI (XSystem Resource Identifier) to open or create an XSystem instance.

2. Before connection is granted, the XAM Library loads the appropriate VIM Library to establish the application’s right to access the storage system associated with that XRI.

Application

XAM API

XAM Library

XAM Toolkit(optional)

VIM API

Reference VIM

Library

VIM API

Vendor B VIM Library

VIM API

Vendor C VIM Library

File System

Vendor B Storage System

Vendor C Storage System

XAM Toolkit API(optional)

VIM API

Vendor A VIM Library

Vendor A Storage System


Introduction

3. If accepted, the XAM Library creates a XAM session that enables a connection between the application and XSystem via the VIM components.

4. The XAM Library sends application requests to the XSystem via the VIM API.

5. The VIM Library, in turn, communicates the requests to the vendor storage system (for example, EMC Centera cluster), performs the requests, and returns the appropriate responses to the XAM Library.

6. The XAM Library sends the resulting responses to the application.

Note: The application communicates only with the XAM API. Any interaction between the XAM API and VIM API is completely transparent to the application.

XAM architecture 11

12

Introduction

VIM architectureThe architecture of the EMC Centera VIM is a software layer that exists between the XAM Library and the EMC Centera cluster. It consists of the VIM API, centera_vim Library, and other core EMC Centera client components, as shown below the position of the centera_vim Library in Figure 2 on page 12.

The EMC Centera VIM exists on the client application server and communicates with the cluster via IP socket connections.

Figure 2 VIM architecture

The centera_vim Library implements the VIM API, the set of private interfaces that translates requests sent via XAM API calls into those that the VIM API can accept and communicate to the EMC Centera cluster.

Client operating system

FPOS (where applicable)

PAI_Module

FPStreams

FPXMLFPUtils

VIM API

FPCore

FPParser

Dynamic load

VIM (centera_vim) Library

XAM API

XAM Library


Introduction

XAM objectsFor existing SDK applications, the EMC Centera VIM refers to specific XAM objects and elements that have analogous equivalents in the SDK API, as listed in Table 1 on page 13.

Table 1 XAM objects and SDK equivalents

XAM object SDK equivalent Description

XSystem FPPool An XSystem is analogous to an FPPool object in the FPLibrary. It abstracts the connection between the application and the EMC Centera cluster, including any associated resource management and failover behavior. It also authenticates and authorizes users, and acts as a virtual XAM storage system.

XSet C-Clip An XSet is analogous to a C-Clip. Like a C-Clip, an XSet is assigned a unique identifier (XUID) at the time it is stored on the cluster. Similarly, as between a C-Clip and its ID, a binding relationship exists between an XSet and its XUID, where associated content is immutable and cannot be changed. An XSet, however, can contain both immutable (non-changing) and mutable (changing) content.

XStream Blob An XStream is analogous to a blob.

XUID FPClipID The XSet Unique Identifier (XUID) used to refer to the content of a specific XSet in EMC Centera.

XRI Connection string The XSystem Resource Identifier (XRI) or connection string that opens connections to an XSystem.

XAM objects 13

14

Introduction


2

This chapter describes the fields that are specific to the operations of the EMC Centera VIM. The main sections are:

◆ XSystem connection........................................................................... 16◆ XSystem authentication..................................................................... 18◆ XSystem and XSet authorization ..................................................... 20◆ XAM fields .......................................................................................... 21◆ XAM Library fields ............................................................................ 23◆ XSystem fields .................................................................................... 31◆ XSet fields............................................................................................ 40

XAM-basedField Operations

XAM-based Field Operations 15

16

XAM-based Field Operations

XSystem connectionA connection to an XSystem is made by means of the XRI (XSystem Resource Identifier). You can use an XRI to just connect or to connect and authenticate to an XSystem. The XRI allows the XAM Library object to determine which VIM and XSystem to use in the connection attempt and what name/value pairs to deliver to the VIM, if provided. As such, the XRI string contains the EMC Centera pool connection string, as shown in the following XRI syntax:

snia-xam://[<VIM name>!]<connection string>[? <name>=<value> [& <name>=<value>]...]]

Note: While the VIM library name (for example, centera_vim) is optional in the syntax, EMC recommends that you always specify it in the XRI string.

The following example of a connect API call shows the use of the optional VIM name in the XRI string:

Example connect snia-xam://centera_vim!10.241.55.1

Using the XRI for both a connection and an authentication is described in “XSystem authentication” on page 18.

VIM discoveryIf you do not specify a VIM library name in the XRI, the following sequence of events occurs in discovery of the appropriate VIM:

1. The XAM Library checks for the existence of any previously loaded VIM libraries. If detected, the XAM Library uses the most recently loaded VIM library for the XSystem connection.

2. If the connection cannot be made, the XAM Library tries the next available VIM library until the list is completely exhausted.

3. If the VIM list proves unsuccessful, the XAM Library tries to connect with the first library found in the directory specified in the XAM_VIM_PATH environment variable that implements the VIM_CreateXSystem interface. As in step 2, the XAM Library continues to find a connection with each successive library in the directory until all libraries are tried.



4. If a connection is not possible following the VIM discovery process, the XAM Library returns the XAM_VIM_NOT_FOUND error.

XSystem connection 17

18


XSystem authenticationAn XSystem instance, once connected to, must be authenticated before operations can run successfully on it. An authentication occurs by performing one of the following methods:

◆ XAM SASL authentication by XSystem_Authenticate API call: Using this XAM API method requires the XSystem handle to be SASL (Simple Authentication and Security Layer) authenticated, which allows authentication messages between the application and EMC Centera to be negotiated. If successful, the server inserts a security layer between the protocol and the connection for subsequent protocol interactions. The application is responsible for providing the correct series of authentication messages that is specific to a particular VIM library and its SASL mechanism implementation.

The EMC Centera VIM requires the implementation of two SASL mechanisms:

• ANONYMOUS: Used with a token to grant unauthenticated guest access, as shown in the following input syntax:

ANONYMOUS\0<required token>

• PLAIN: Used with the name-secret combination (of the access profile) in a simple, clear text password format, as shown in the following input syntax:

PLAIN\0[optional identity string] \0<name>\0<secret>

Note: The EMC Centera VIM does not support an optional identity string during authentication. This field must be empty, otherwise, authentication will fail.

◆ EMC Centera authentication by XAMLibrary_Connect API call: During an XSystem connect, you also can use the EMC Centera name-secret combination or PEA file to explicitly authenticate the XSystem. This XAM API method returns a fully authenticated xsystem_handle, which precludes the need to run the XSystem_Authenticate call on the XSystem instance.



Note: You can determine if an XSystem instance is already authenticated or is only connected to by checking the existence of the .xsystem.auth.identity.authentication field. If present, the XSystem does not require authentication through the XSystem_Authenticate call.

Examples The following example shows the legacy and XAM-supported syntax using the name-secret authentication:

snia-xam://centera_vim!10.241.55.1?name=myName & secret=myPassword

The following example shows the legacy and XAM-supported syntax using the PEA file:

snia-xam://centera_vim!10.241.55.1,10.241.55.2?pea=c:\\MyPeaFile.pea

Note: The PEA file you use for the authentication can be other than the one specified in the CENTERA_PEA_LOCATION environment variable, if used.

ReauthenticationDuring an XSystem session, you can change the profile used without having to close the XSystem instance. To reauthenticate with another profile on the same XSystem, run the XSystem_Authenticate XAM API call.

XSystem authentication 19

20


XSystem and XSet authorization

XAM granules XAM granules control access to XSystems and XSets. XAM granules, like capabilities in the legacy SDK, are associated with the access profile and refer to the operations that the VIM API is allowed to perform on the cluster. Table 2 lists the XAM granules and if enabled, mapped to which enabled capabilities on the EMC Centera:

Table 2 Mapping of XAM granules to capability settings

XAM granule (enabled) FP capability (enabled) FP attribute Value

read FP_READ FP_ALLOWED True

write-application • FP_WRITE • FP_CLIPCOPY (“clip_copy”)• FP_EXIST

FP_ALLOWED True

write-system • FP_WRITE • FP_CLIPCOPY (“clip_copy”)• FP_EXIST

FP_ALLOWED True

create • FP_WRITE • FP_CLIPCOPY (“clip_copy”)• FP_EXIST

FP_ALLOWED True

delete FP_DELETE FP_ALLOWED True

job • FP_READ• FP_WRITE• FP_CLIPCOPY (“clip_copy”)• FP_EXIST• FP_QUERY

FP_ALLOWED True

job-commit Always disallowed in this EMC Centera SDK for XAM v1.0 release

hold • FP_RETENTION_HOLD• FP_WRITE• FP_READ• FP_EXIST

FP_ALLOWED True

retention-event FP_COMPLIANCE FP_EVENT_BASED_RETENTION Supported



XAM fields XAM fields are the main constructs for uniquely identifying data belonging to a XAM Library object, an XSystem, or an XSet. Applications can create, iterate, update, query, and delete any user-defined XAM field. You can access any XAM field by its namespace regardless of the object type to which it is attached.

Note: The XAM Library object, XSystem, and XSet also have attached XAM- and VIM-defined fields, some of which are read only.

A XAM field can be either a property or an XStream type of field. Only fields attached to an XSet can persist to the EMC Centera, with definitions of metadata and data. All other fields exist for configuration or informational purposes. The SNIA XAM architecture specification provides complete definitions and descriptions of the following XAM elements:

◆ Field namespaces: XAM field data is accessible via globally flat namespaces associated with a XAM object type. XAM divides the field namespace into sub-namespaces, which are statically allocated between the SNIA standards, XAM system vendors, and XAM application vendors.

Note: The field namespace reserved for EMC Centera is .vnd.com.emc.centera.*. Namespaces reserved for SNIA use the .xam.* prefix, as shown in Table 4 on page 23.

◆ Field types: If not a defined property type, a XAM field is an XStream type that has a MIME type attribute other than those associated with a property.

◆ Field names: The following rules apply to application field name use and creation:

• Are application-defined at creation time• Are a valid UTF-8 string with a maximum length of 512 bytes• Cannot be an empty string• Are case-sensitive• Cannot have embedded NULL characters• Cannot have duplicate field names on a single object

XAM fields 21

22


◆ Field attributes: Each field has a required set of attributes that includes a valid MIME type, binding state, read-only state, and a data length in bytes. While the application defines the field’s binding state, only XAM or the EMC Centera VIM can define the read-only state.

◆ XAM-defined simple types (stypes): The defined stypes are xam_boolean, xam_int, xam_double, xam_xuid, xam_string, and xam_datetime. The XAM API validates property fields.

◆ Common MIME content-types: An XStream field must use a valid MIME content type to define the kind of blob being attached to an XSet. The official list of registered MIME types can be found at this site http://www.iana.org/assignments/media-types.

Configuration settings

Configuration settings that control XSystem behavior exist at both levels of the XAM Library object and XSystem, as described in Table 3 on page 22:

Table 3 Field levels

XAM field type Field impact Legacy SDK equivalent

XAMLibrary object Sets global configurations and default behavior that affect all XSystems to be created, for example, logging controls.

• Global options via the FPPool_SetGlobalOption API

• Environment variables

XSystem Sets local configurations that affect a specific XSystem only. If no local configurations are defined, the XSystem assumes the defaults of the global configurations already established in the XAM Library object.

Used locally for a pool:• Global options via the

FPPool_SetGlobalOptionand FPPool_SetIntOption APIs.

• Environment variables

XSet Sets attribute values of properties and XStreams on XSets.

C-Clip tags and attributes


http://www.iana.org/assignments/media-types




XAM Library fieldsAs the XAM Library object acts as both a factory for creating XSystem instances and a global field repository of configuration information, the predefined fields associated with the XAM Library determine the initial configuration settings of an XSystem when the XSystem is created and stored in an EMC Centera.

In addition, any application-defined fields you create for the XAM Library object also are copied to XSystem instances (for example, global options as listed in Table 5 on page 25).

Predefined global fieldsTable 4 describes the XAM Library fields:

Table 4 Predefined XAMLibrary fields (page 1 of 2)

Field name MIME type Binding Read only Description

.xam.identity xam_string FALSE TRUE The origin of the XAM Library (for example, org.snia).

Note: This field is informational only and should not be used in the context of coding specific behavior.

.xam.api.level xam_string FALSE TRUE The current version of the XAM API in effect.

.xam.log.level xam_int FALSE FALSE The current level of log event types to display in the file. The higher the value is, the greater the amount of detail to capture in the log. Values are:0 = None (Logging is disabled)1 = FATAL (Fatal Errors)2 = ERROR (Errors)3 = WARNING (Errors, Warnings)4 = INFO (Errors, Warnings, Log, Debug5 = ALL (Errors, Warnings, Log, Debug, Debug+)

Note: The default setting is 0. You can control the log level by specifying the appropriate value.

XAM Library fields 23

24


Note: “VIM logging fields” on page 65 provides more information on VIM logging behavior.

.xam.log.verbosity xam_int FALSE FALSE The current level of log activities for the log components being logged.0 = No debug output 1 = Minimal XAM_API debugging2 = Verbose XAM_API debugging3 = Verbose XAM_API and VIM_API debugging 4 = Verbose XAM_API and VIM_API debugging, VIM log events, XAM Library debug messages5 =Verbose XAM_API and VIM_API debugging, VIM log events, additional XAM Library debug messages

Note: The default setting is 0. You can control the amount of log output by specifying the appropriate value.

.xam.log.path xam_string FALSE FALSE The path to the output log file.

Note: The default setting is ./xam.log.

.xam.vim.list.<vimName> xam_string FALSE TRUE The prefix used in properties to list the names of VIMs that the XAM Library has already discovered.

Table 4 Predefined XAMLibrary fields (page 2 of 2)




Options as global configuration fields In the legacy EMC Centera API, global and int options establish initial settings for all pools and specific pools, respectively. Similarly, in the EMC Centera SDK for XAM, you can set global options as global fields on the XAM Library object. Setting options on the XAM Library object ensures that all created XSystem instances have the expected set of configurations. This practice is especially important and relevant if a global option is used to effect connection behavior. For example, if you preset the XAM Library object with the FP_NORMAL_OPEN connection strategy, the object uses that method to open IP connections to the XSystem after it creates the XSystem.

In order to access symbolic names for SDK option values, it is necessary for a XAM application to include the FPAPI.h header file. Including this header file allows you to use FP_NORMAL_OPEN as an option value, instead of inserting an integer value directly. It is not necessary to link against the FPLibrary shared library when including FPAPI.h.

Note: You can set any global option field as an environment variable. The option settings that an application sets take precedence and override those that were previously set as environment variables.

Table 5 lists the field names of the corresponding equivalent options. Each field name has the following attributes:

◆ MIME type: xam_int◆ Binding: FALSE◆ Read-only: FALSE

Table 5 Global options as XAMLibrary fields (page 1 of 5)

Field name EMC Centera equivalent/description

.vnd.com.emc.centera.cluster.non.avail.time FP_OPTION_CLUSTER_NON_AVAIL_TIMEThe time in seconds that a cluster is marked as not available before retrying with a probe. Other clusters in the pool will be used while the cluster is unavailable. The default value is 600 (10 minutes). The minimum is 0. The maximum is 36000 (10 hours).


26


.vnd.com.emc.centera.embedded.data.threshold FP_OPTION_EMBEDDED_DATA_THRESHOLDThe maximum data size, in bytes, for data to be embedded in the CDF instead of being stored as separate blobs. The default value is 0 bytes, meaning data is never embedded in the CDF. The maximum value is 102400 bytes (100 KB). The value for the embedded data threshold can be set to less than or equal to 102400 bytes.

.vnd.com.emc.centera.maxconnections FP_OPTION_MAXCONNECTIONSThe maximum number of sockets that the SDK will allocate for your application. Sockets are used to communicate with the EMC Centera clusters managed in each pool object. The default value is 100. The maximum value is 999.

.vnd.com.emc.centera.multicluster.read/write/delete/exists/query.clusters

FP_OPTION_MULTICLUSTER_READ/WRITE/DELETE/EXISTS/QUERY_CLUSTERS— The cluster types that are eligible for multicluster failover. In addition to defining the multicluster failover strategy for each SDK operation, you can specify which cluster types participate in that strategy for each operation. Refer to Table 16 on page 64. Choices are:FP_ALL_CLUSTERS: The multicluster strategy uses all clusters in the pool. The typical order of access is: primary cluster, replica of the primary cluster, secondary clusters, and replicas of secondary clusters. The SDK, however, does not guarantee this order of access. This value is the default for read (FP_OPTION_MULTICLUSTER_READ_CLUSTERS), exists (FP_OPTION_MULTICLUSTER_EXISTS_CLUSTERS), and query (FP_OPTION_MULTICLUSTER_QUERY_CLUSTERS) operations.FP_PRIMARY_AND_PRIMARY_REPLICA_CLUSTER_ONLY: The multicluster strategy uses the primary cluster and its replicas only. Secondary clusters and replicas of secondary clusters are not used.FP_NO_REPLICA_CLUSTERS: The multicluster strategy uses secondary clusters, but no replica clusters.FP_PRIMARY_ONLY: Operations are performed on the primary cluster only, irrespective of the multicluster strategy. This value is the default for write (FP_OPTION_MULTICLUSTER_WRITE_CLUSTERS) and delete (FP_OPTION_MULTICLUSTER_DELETE_CLUSTERS) operations.You identify clusters as being eligible to be primary clusters or not when you open the pool by specifying primary= and secondary= address prefixes in the connection string.

Note: These failover options are global to the application. Once set, the options should not be changed for different threads.

Note: You can disable failover for all capabilities for a particular System instance by setting FP_OPTION_ENABLE_MULTICLUSTER_FAILOVER to false.





.vnd.com.emc.centera.multicluster.delete.strategy FP_OPTION_MULTICLUSTER_DELETE_STRATEGYThe multicluster failover strategy for delete operations: FPClip_Delete(), FPClip_AuditedDelete(). This option also controls failover for the deprecated purge operations: FPClip_Purge(), FPTag_BlobPurge().FP_NO_STRATEGY (Default): Content is deleted from the primary cluster only. If a connection to a node with the access role fails while a delete is in progress, the next eligible node with the access role is used (an operation retry, not failover). Nodes with the access role from other clusters are not used. If connections to all nodes with the access role of a primary cluster fail, then the operation fails.FP_FAILOVER_STRATEGY: Not supported.FP_REPLICATION_STRATEGY: Content is deleted from all eligible clusters synchronously before the call returns.

.vnd.com.emc.centera.multicluster.exists.strategy FP_OPTION_MULTICLUSTER_EXISTS_STRATEGYThe multicluster failover strategy for exists operations: FPClip_Exists(), FPTag_BlobExists(). Choices are:FP_NO_STRATEGY: The existence of content is validated on the primary cluster only. If a connection to a node with the access role fails while a check is in progress, the next eligible node with the access role is used (an operation retry, not failover). nodes with the access role from other clusters are not used. If connections to all nodes with the access role of a primary cluster fail, then the operation fails.FP_FAILOVER_STRATEGY (Default): If a connection to a node with the access role fails while a check is in progress, the next eligible node with the access role is used (an operation retry, not failover). If connections to all nodes with the access role of a cluster fail, then the next eligible cluster is used.FP_REPLICATION_STRATEGY: If a connection to a node with the access role fails while a check is in progress, the next eligible node with the access role is used (an operation retry, not failover). If connections to all nodes with the access role of a cluster fail, then the next eligible cluster is used. In addition, if the content is not found on a given cluster, the exists operation is replicated—performed on the next eligible cluster—which is not considered a retry. The resulting behavior is that the existence check returns true if the content is found on any of the eligible clusters.




28


.vnd.com.emc.centera.multicluster.read.strategy FP_OPTION_MULTICLUSTER_READ_STRATEGYThe multicluster failover strategy for read operations: FPClip_Open(), FPTag_BlobRead(), FPTag_BlobReadPartial(). Choices are:FP_NO_STRATEGY: Content is read from the primary cluster only. If a connection to a node with the access role fails while a read is in progress, the next eligible node with the access role is used (an operation retry, not failover). Nodes with the access role from other clusters are not used. If connections to all nodes with the access role of the primary cluster fail, then the operation fails.FP_FAILOVER_STRATEGY: If a connection to an node with the access role fails while a read is in progress, the next eligible node with the access role is used (an operation retry, not failover). If connections to all nodes with the access role of a cluster fail, then the next eligible cluster is used.FP_REPLICATION_STRATEGY (Default): If a connection to a node with the access role fails while a read is in progress, the next eligible node with the access role is used (an operation retry, not failover). If connections to all nodes with the access role of a cluster fail, then the next eligible cluster is used. In addition, if the content is not found on a given cluster, the read operation is replicated—performed on the next eligible cluster—which is not considered a retry.

.vnd.com.emc.centera.multicluster.write.strategy FP_OPTION_MULTICLUSTER_WRITE_STRATEGYThe multicluster failover strategy for write operations: FPClip_Write(), FPTag_BlobWrite(). Choices are:FP_NO_STRATEGY (Default): Content is written to the primary cluster only. If a connection to a node with the access role fails while a write is in progress and the stream can be reset, the next eligible node with the access role is used (an operation retry, not failover). If the stream cannot be reset, then the operation fails. Nodes with the access role from other clusters are not used. If connections to all nodes with the access role of a primary cluster fail, then the operation fails.FP_FAILOVER_STRATEGY: Not supported.FP_REPLICATION_STRATEGY (Default): If a connection to a node with the access role fails while a read is in progress, the next eligible node with the access role is used (an operation retry, not failover). If connections to all nodes with the access role of a cluster fail, then the next eligible cluster is used. In addition, if the content is not found on a given cluster, the read operation is replicated—performed on the next eligible cluster—which is not considered a retry.





.vnd.com.emc.centera.open.strategy FP_OPTION_OPENSTRATEGYThe approach used by FPPool_Open() to open connections to addresses in the connection string:FP_NORMAL_OPEN: FPPool_Open() attempts to open connections to all addresses in the connection string, and to all associated replication addresses. Consider using this strategy if your application performs numerous operations while the pool is open. This strategy is the default. This option is equivalent to FP_OPTION_DEFAULT_OPTIONS.FP_LAZY_OPEN: FPPool_Open() opens connections to addresses only as needed. Consider using this strategy if your application frequently opens and closes the pool.

.vnd.com.emc.centera.multicluster.query.strategy FP_OPTION_MULTICLUSTER_QUERY_STRATEGYThe multicluster failover strategy for query operations: FPPoolQuery_Open().FP_NO_STRATEGY: Content is queried from the primary cluster only. If a connection to a node with the access role fails when starting a query, the next eligible node with the access role is used (an operation retry, not failover). Nodes with the access role from other clusters are not used. If connections to all nodes with the access role of a primary cluster fail, then the operation fails.FP_FAILOVER_STRATEGY (Default): If a connection to a node with the access role fails while starting a query, the next eligible node with the access role is used (an operation retry, not failover). If connections to all nodes with the access role of a cluster fail, then the next eligible cluster is used.FP_REPLICATION_STRATEGY: A query is started on all eligible clusters. Query results are collated to preserve the increasing time sequence of results. Times are normalized to the primary cluster.

.vnd.com.emc.centera.probe.limit FP_OPTION_PROBE_LIMITThe threshold for how long an application probe is allowed to attempt communication with a node with the access role. The maximum threshold is 60 seconds (1 minute). If a probe exceeds the limit, the SDK returns an error.

.vnd.com.emc.centera.retrycount FP_OPTION_RETRYCOUNTThe number of times an operation will be retried before a failure is reported to the client application. The default value is 6. If the first execution of the function fails, the system retries the function 6 times. In total the function executes 7 times. The maximum value is 99.

.vnd.com.emc.centera.retrysleep FP_OPTION_RETRYSLEEPThe time to wait before the failed API function call should be retried, in milliseconds. The maximum value is 100000 ms. If no retrysleep has been defined, the SDK uses an exponential back-off scheme. The sleep time increases after each retry, starting at 1 second, and doubles after each retry.




30


Application registration fields

You can register an application’s name and version on the EMC Centera VIM by creating two string fields only once on the XAM Library object. This information is then automatically created on each XSystem instance prior to the VIM connection. If undefined on the XAM Library object, the VIM automatically generates the full path to the application at the XSystem level via .xystem.identity. If the generated name exceeds the maximum size of a xam_string, the VIM truncates and NULL-terminates it accordingly.

Note: A XAM Library object field containing the same name takes precedence. The VIM cannot generate the application version automatically; you must manually create it from the application.

Table 6 lists the applicaton registration fields, which use the following attributes:

Table 6 Application registration XAM Library object/XSystem fields


.vnd.com.emc.centera.application.name xam_string FALSE FALSE The name of the application that is accessing the EMC Centera VIM.

.vnd.com.emc.centera.application.version xam_string FALSE FALSE The current version of the application in use.



XSystem fieldsEach XSystem instance created by the XAM Library object contains not only the predefined global fields copied from the XAM Library object in Table 4 on page 23, but also the following predefined XSystem fields listed in Table 7, with the following attributes:

Table 7 Predefined XSystem fields (page 1 of 3)


.xsystem.identity xam_string FALSE TRUE The identity of the XSystem.

.xsystem.time xam_datetime FALSE TRUE The current time on the XSystem in UTC.

.xsystem.limits.maxFieldsPerXSet xam_int FALSE TRUE The maximum number of fields allowed for each XSet created on a particular XSystem.

.xsystem.limits.maxSizeOfXStream xam_int FALSE TRUE The maximum number of bytes allowed for each XStream created on a particular XSystem.

.xsystem.auth.SASLmechanisms.<mechanism>

xam_boolean FALSE TRUE The set of Boolean properties indicating a list of valid SASL mechanism keywords supported by the XSystem (for example, ANONYMOUS, PLAIN).

.xsystem.auth.SASLmechanism.default xam_boolean FALSE TRUE The default SASL mechanism in use by the XSystem.

.xsystem.auth.granule.list.<granule> xam_boolean FALSE TRUE The set of Boolean properties indicating a list of valid XAM granules.

.xsystem.auth.identity.authentication xam_string FALSE TRUE The SASL authentication identity of the current XAM session.

.xsystem.auth.identity.authorization xam_string FALSE TRUE The SASL authorization identity of the current XAM session.

.xsystem.auth.expiration xam_int FALSE TRUE The number of seconds remaining before you need to reauthenticate the XSystem (-1 for no limit).

.xsystem.job.commit.supported xam_boolean FALSE TRUE Whether the XSystem supports invoking the XSet.Commit() method on an XSet that currently identifies a running job.

.xsystem.job.list.<jobType> xam_boolean FALSE TRUE A list of valid XAM job types.

XSystem fields 31

32


.xsystem.job.list.query xam_boolean FALSE TRUE The property indicating that the XSystem supports the query jobType.

.xsystem.job.<jobType>.<capability> xam_boolean FALSE TRUE The set of properties of various types, indicating various capabilities and characeristics of a particular XAM jobType.

.xsystem.job.query.continuance. supported

xam_boolean FALSE TRUE The capability to continue to process a job while an XSystem is not open.

.xsystem.job.query.level1.supported xam_boolean FALSE TRUE The capability supported by the query jobType on this partcular XSystem.

Note: This value is always set to True.

.xsystem.job.query.level2.supported xam_boolean FALSE TRUE The capability supported by the query jobType on this partcular XSystem.

Note: This value is always set to False.

.xsystem.deletion.autodelete xam_boolean FALSE TRUE Whether the XSystem suports (and has enabled) the shredding capability.


.xsystem.deletion.autodelete.policy.list.<name>

xam_string FALSE TRUE A set of string properties indicating a list of XSet policy names applicable to the XSystem’s autodelete management discipline, and available on this XSystem.

Note: This feature is not supported in this v1.0 release.

.xsystem.deletion.shred xam_boolean FALSE TRUE Whether this XSystem supports (and has enabled) the shredding capability.






Other XSystem fields that you can create on the XAM Library object or directly on the XSystem are VIM fields related to FPPool capabilities and FPPoolInfo:

.xsystem.deletion.shred.policy.list.<name>

xam_string FALSE TRUE A set of string properties indicating a list of XSet policy names applicable to the XSystem’s shredding capability, and available on this XSystem.


.xsystem.management.policy.list.<name> xam_string FALSE TRUE A set of string properties indicating a list of XSet policy names applicable to the XSystem’s management discipline, and available on this XSystem.

.xsystem.management.policy.default xam_string FALSE TRUE The default management policy available on this XSystem.

.xsystem.storage.policy.list.<name> xam_string FALSE TRUE A set of string properties indicating a list of XSet policy names applicable to the XSystem’s storage discipline, and available on this XSystem.


.xsystem.retention.duration.policy.list.<name>

xam_string FALSE TRUE A string property indicating a list of XSet policy names applicable to various aspects of the XSystem’s retention discipline, and available on this XSystem.

.xsystem.retention.enabled.policy.list.<name>

xam_string FALSE TRUE A string property indicating a list of XSet policy names applicable to various aspects of the XSystem’s retention discipline, and available on this XSystem.




XSystem fields 33

34


FPPool capabilities fields

FPPool capabilities are associated with the access profile and refer to the operations that the EMC Centera SDK for VIM is allowed to perform on the XSystem. Each capability field name has the following attributes:

◆ MIME type: xam_string ◆ Binding: FALSE◆ Read-only: TRUE

Table 8 describes the capability field names and their legacy equivalents:

Table 8 FPPool capabilities as XAMLibrary/XSystem fields (page 1 of 5)

Field name Description EMC Centera equivalent

.vnd.com.emc.centera.capabilities.blobnaming.supportedschemes

The supported naming schemes. FP_BLOBNAMINGAttribute name: FP_SUPPORTED_SCHEMESAttribute value: MD5/MG

.vnd.com.emc.centera.capabilities.clip-enumeration.allowed

If true, FPPoolQuery_Open( ) is allowed.

FP_CLIPENUMERATIONAttribute name: FP_ALLOWED Attribute value: true/false

.vnd.com.emc.centera.capabilities.clip-enumeration.pools

The list of pools associated with the field capability. Pools display in a comma-separated list. If there are no pools, the string is empty.

FP_CLIPENUMERATIONAttribute name: FP_POOLS Attribute value: string

.vnd.com.emc.centera.capabilities.compliance.ebr

If supported, this compliance capability allows the SDK to quickly verify an application’s Advanced Retention Management license for EBR. If unsupported, the SDK rejects the call before the XSet is committed, and generates the error FP_ADVANCED_RETENTION_DISABLED_ERR.

FP_COMPLIANCEAttribute name: FP_EVENT_BASED_RETENTION Attribute value: supported/unsupported

.vnd.com.emc.centera.capabilities.compliance.min-max

If supported, this compliance capability determines whether the EBR retention period falls within the retention minimum and maximum range. If not within the range and the license is supported, the SDK generates the error FP_RETENTION_OUT_OF_BOUNDS_ERR.

FP_COMPLIANCEAttribute name: FP_RETENTION_MIN_MAX Attribute value: supported/unsupported



.vnd.com.emc.centera.capabilities.compliance.mode

The compliance mode of the cluster being connected to in an XSystem.

Note: The CE mode refers to the Governance Edition (GE).

FP_COMPLIANCEAttribute name: FP_MODE Attribute value: basic/CE/CE+

.vnd.com.emc.centera.capabilities.compliance.retention-hold

If supported, this compliance capability allows the SDK to quickly verify an application’s Advanced Retention Management license for retention hold. If unsupported, the SDK rejects the call before the XSet is committed, and generates the error FP_ADVANCED_RETENTION_DISABLED_ERR.

FP_COMPLIANCEAttribute name: FP_RETENTION_HOLD Attribute value: supported/unsupported

.vnd.com.emc.centera.capabilities.delete.allowed

If true, FPClip_Delete() and FPClip_AuditedDelete() are allowed.

FP_DELETEAttribute name: FP_ALLOWEDAttribute value: true/false

.vnd.com.emc.centera.capabilities.delete.pools The list of pools associated with the field capability. Pools display in a comma-separated list. If there are no pools, the string is empty.

FP_DELETEAttribute name: FP_POOLS Attribute value: string

.vnd.com.emc.centera.capabilities.deletionlogging.supported

If true, the server creates reflections when deleting XSets.

FP_DELETIONLOGGINGAttribute name: FP_SUPPORTEDAttribute value: true/false

.vnd.com.emc.centera.capabilities.exist.allowed If true, FPClip_Exists() and FPTag_BlobExists() are allowed.

FP_EXISTAttribute name: FP_ALLOWED Attribute value: true/false

.vnd.com.emc.centera.capabilities.exist.pools The list of pools associated with the field capability. Pools display in a comma-separated list. If there are no pools, the string is empty.

FP_EXISTAttribute name: FP_POOLS Attribute value: string

.vnd.com.emc.centera.capabilities.monitor.allowed

If true, the server supports the FPMonitor_xxx calls.

FP_MONITORAttribute name: FP_ALLOWEDAttribute value: true/false

.vnd.com.emc.centera.capabilities.poolmappings.pools

The pool mappings for all the profiles or pools.

FP_POOL_POOLMAPPINGSAttribute name: FP_POOLS Attribute value: string



XSystem fields 35

36


.vnd.com.emc.centera.capabilities.poolmappings.profiles

The list of profiles with a pool mapping. FP_POOL_POOLMAPPINGSAttribute name: FP_PROFILESAttribute value: string

.vnd.com.emc.centera.capabilities.privileged-delete.allowed

If true, privileged deletion using FPClip_AuditedDelete() is allowed. This value is never true for a CE+ model.

FP_PRIVILEGEDDELETEAttribute name: FP_ALLOWED Attribute value: true/false

.vnd.com.emc.centera.capabilities.privileged-delete.pools


FP_PRIVILEGEDDELETEAttribute name: FP_ALLOWED Attribute value: string

.vnd.com.emc.centera.capabilities.read.allowed If true, XSet_Commit() and FPTag_BlobRead() (Partial) are allowed.

FP_READAttribute name: FP_ALLOWED Attribute value: true/false

.vnd.com.emc.centera.capabilities.read.pools The list of pools associated with the field capability. Pools display in a comma-separated list. If there are no pools, the string is empty.

FP_READAttribute name: FP_POOLSAttribute value: true/false

.vnd.com.emc.centera.capabilities.retention.default

If the CDF does not specify a retention period or retention class, the default value is FP_NO_RETENTION_PERIOD (0) for a CE mode (GE model), FP_INFINITE_RETENTION_PERIOD (-1) for a CE+ mode (CE+ model), or FP_DEFAULT_RETENTION_PERIOD (-2) for a default value.

Note: The system administrator can edit the default value only for the CE mode.

FP_RETENTIONAttribute name: FP_DEFAULT Attribute value: integer

.vnd.com.emc.centera.capabilities.retention.fixedmaximum

The maximum time allowed for a fixed retention period. If absent, the default value is -1 for FP_INFINITE_RETENTION_PERIOD.This maximum constraint applies to all newly written C-Clips in CentraStar v3.1.

FP_RETENTIONAttribute name: FP_FIXED_RETENTION_MAX Attribute value: 64-bit integer





.vnd.com.emc.centera.capabilities.retention.fixedminimum

The minimum time allowed for a fixed retention period. If absent, the default value is 0 for FP_NO_RETENTION_PERIOD. This minimum constraint applies to all newly written C-Clips in CentraStar v3.1.

FP_RETENTIONAttribute name: FP_FIXED_RETENTION_MIN Attribute value: 64-bit integer

.vnd.com.emc.centera.capabilities.retention.variablemaximum

The maximum time allowed for an EBR period. If absent, the default value is -1 for FP_INFINITE_RETENTION_PERIOD.This maximum constraint applies to all newly written C-Clips in CentraStar v3.1.

FP_RETENTIONAttribute name: FP_VARIABLE_RETENTION_MAX Attribute value: 64-bit integer

.vnd.com.emc.centera.capabilities.retention.variableminimum

The minimum time allowed for an EBR period. If absent, the default value is 0 for FP_NO_RETENTION_PERIOD. This minimum constraint applies to all newly written C-Clips in CentraStar v3.1.

FP_RETENTIONAttribute name: FP_VARIABLE_RETENTION_MIN Attribute value: 64-bit integer

.vnd.com.emc.centera.capabilities.retention-hold.allowed

If true, retention hold is enabled, which allows the access profile to set and release retention holds at the XSet level.This capability also allows the SDK to check if retention hold is allowed. If false, the SDK rejects any retention hold call before the XSet is committed, and generates the error FP_OPERATION_NOT_ALLOWED.

FP_RETENTION_HOLDAttribute name: FP_ALLOWED Attribute value: true/false

.vnd.com.emc.centera.capabilities.retention-hold.pools


FP_RETENTION_HOLDAttribute name: FP_POOLSAttribute value: string

.vnd.com.emc.centera.capabilities.write.allowed If true, XSet_Commit() and XStream_Write() are allowed.

FP_WRITEAttribute name: FP_ALLOWED Attribute value: true/false



XSystem fields 37

38


FPPoolInfo fields FPPoolInfo XSystem fields specify information about the active pool connection. The application should not deallocate or modify the pointer member variables. Each FPPoolInfo field name has the following attributes:

.vnd.com.emc.centera.capabilities.write.pools The list of pools associated with the field capability. Pools display in a comma-separated list. If there are no pools, the string is empty.

FP_WRITEAttribute name: FP_POOLSAttribute value: string



Table 9 FPPoolInfo XSystem fields

Field name MIME type Binding Read Only Description

.vnd.com.emc.centera.poolinfo.capacity xam_int FALSE TRUE The total capacity of the pool, in bytes.

.vnd.com.emc.centera.poolinfo.freeSpace xam_int FALSE TRUE The total free, usable space of the pool, in bytes.

.vnd.com.emc.centera.poolinfo.clusterID xam_string FALSE TRUE The cluster identifier of the pool.

.vnd.com.emc.centera.poolinfo.clusterName xam_string FALSE TRUE The name of the cluster.

.vnd.com.emc.centera.poolinfo.version xam_string FALSE TRUE The current CentraStar version of this structure.

.vnd.com.emc.centera.poolinfo.replicaAddress

xam_string FALSE TRUE A comma-separated list of the replication cluster’s node (with the access role) addresses as specified when replication was enabled; empty if replica cluster not identified or configured.



Options as XSystem configuration fieldsTo effect specific and consistent behavior for XSets associated with a particular XSystem, you can set int options as configurations fields directly on the XSystem itself.

Table 10 lists the field names of the corresponding equivalent options. Each field name has the following attributes:

◆ Binding: FALSE◆ Read-only: FALSE

Table 10 Int options on XSystem fields

Field name MIME type EMC Centera equivalent/description

.vnd.com.emc.centera.buffersize xam_int FP_OPTION_BUFFERSIZEThe size of an internal C-Clip buffer in bytes. The default value is 16*1024. This value must be greater than 0.

.vnd.com.emc.centera.timeout xam_int FP_OPTION_TIMEOUTThe TCP/IP connection timeout in milliseconds. The default value is 120000 ms (2 minutes). The maximum value is 600000 ms (10 minutes).

.vnd.com.emc.centera.enable.multicluster.failover xam_boolean FP_OPTION_ENABLE_MULTICLUSTER_FAILOVERWhen this option is true (the default), multicluster failover is enabled. You can define the failover behavior for each capability using FPPool_SetGlobalOption(). By default this option is true (1). To turn multicluster failover off for all capabilities, specify false (0).

.vnd.com.emc.centera.default.collision.avoidance xam_boolean FP_OPTION_DEFAULT_COLLISION_AVOIDANCEThis option can either be true (1) or false (0). This option is false by default. To enable collision avoidance at pool level, set this option to true. If you enable this option, the SDK uses an additional blob discriminator for read and write operations of C-Clips and blobs. Refer to the EMC Centera Programmer’s Guide for more information on collision avoidance. To disable this option at pool level, reset the option to false. Collision avoidance can also be enabled or disabled at blob level.

.vnd.com.emc.centera.prefetch.size xam_int FP_OPTION_PREFETCH_SIZEThe size of the prefetch buffer. This buffer is used to assist in determining the size of the blob. The default size is 32 KB. The maximum size is 1 MB.

XSystem fields 39

40


XSet fieldsAn XSystem creates an XSet instance when the OpenXSet() is called. An XSet binds data and metadata into a single entity that is persisted to the EMC Centera as a unit containing fields. The following XAM-defined fields in Table 11 provide the metadata properties of each XSet:

Table 11 Predefined XSet fields


.xset.time.creation xam_datetime TRUE TRUE The time the XSet was created.

.xset.time.xuid xam_datetime TRUE TRUE The time when the XUID was assigned to the XSet.

.xset.time.commit xam_datetime FALSE TRUE The most recent time that the XSet was committed.

.xset.time.access xam_datetime FALSE TRUE The most recent time that the XSet was opened or committed.

.xset.time.residency xam_datetime FALSE TRUE The time that the XSet was first stored in the XSystem.

.xset.xuid xam_xuid FALSE TRUE The unique identifier of the XSet. This field, in conjunction with the .xset.dirty field, determines the state of the XSet instance. This field exists only in a non-dirty, committed state.

.xset.dirty xam_boolean FALSE TRUE Whether the XSet was previously modified. This field is used in conjunction with the .xset.xuid field to determine the dirty state, when a dirty state exists.



Profile XSet field The EMC Centera VIM provides a function similar to the equivalent profile C-Clip. In the legacy SDK API, a profile C-Clip ID is a Content Address containing C-Clips associated with an access profile. The VIM uses the profile.xset field and the following attributes to associate a XUID with the appropriate access profile on an XSystem:

Note: To obtain the XUID value of the profile XSet that is associated with the access profile on an XSystem, you must first create and commit this XSet. You cannot delete this field after the XSet is created.

Table 12 FPPoolInfo XSystem fields


com.emc.centera.profile.xset xam_xuid FALSE FALSE The identity of the XSystem.

XSet fields 41

42



3

This chapter describes the EMC Centera XSet behavior and available XSet operations. It also describes how the EMC Centera VIM handles the conversion of legacy C-Clips. The main sections are:

◆ XSet overview..................................................................................... 44◆ XSet operations................................................................................... 45◆ Conversion of legacy data ................................................................ 49◆ Conversion of legacy data ................................................................ 49◆ XSet retention management ............................................................. 54◆ XSet hold management ..................................................................... 62

XSet Operations

XSet Operations 43

44

XSet Operations

XSet overviewAn XSet in the EMC Centera VIM environment is the XAM equivalent of a legacy C-Clip. Like the legacy C-Clip, the XSet receives a globally unique identifier called the XUID when the content of the application’s data and metadata binds to the XSet and is committed to a cluster upon storage.

EMC Centera XUID The XUID is analogous to the FPClipID, which EMC Centera uses to identify a specific C-Clip. An EMC Centera XUID contains the FPClipID of the underlying EMC Centera object as part of its data. Opening an XSet via its XUID retrieves the whole XSet, including all associated binding and non-binding references.

Table 13 shows the byte format of the EMC Centera XUID:

Example 1 XUID in string format

AAAEcwA9ew5FMFNDMk0zQ1JINjFWZTBKVkJMQjZFTUEyNzZHNDEzQVRLOUk0RzBDNjZDR0FCUFZBMEM5SQ==

Table 13 XUID byte format

Byte index Contents

[0 (reserved)] Must be zero

[1-3 (OID)] EMC=1139

[4 (reserved)] Must be zero

[5 (length)] The full length of the XUID in bytes

[6-7 (CRC)] Allows the integrity of the XUID to be checked

[8-79] Vendor-specific data


XSet Operations

XSet operationsThe following XSet operations are available via the EMC Centera VIM:

◆ Create, commit, and store XSets

◆ Read XSets, including the reading of legacy C-Clips as XSets

◆ Write XStream data to XSets

◆ Retrieve and get information on XSets

◆ Delete XSets

◆ Query XSets by job control function

◆ Import XSets to EMC Centera from any XAM-enabled device

◆ Export XSets from EMC Centera to any other XAM-enabled device

◆ Migrate XSets between XSystems

◆ Retain XSets by retention management

◆ Hold and release XSets by hold management

Extensive information about these XSet functions are available in the SNIA publications located at http://www.snia.org/forums/xam/technology/specs/. This section describes the VIM-specific behavior of certain XSet operations. “XSet retention management” on page 54 describes the retention and hold management operations supported by the EMC Centera VIM.

XSet deleteAn XSet delete involves the removal of all elements that make up the XSet.

Note: CentraStar v4.0.1 retains some elements of deleted XSets for processing by upgraded XSet management features in a future CentraStar release.

XSet operations 45


46

XSet Operations

XSet queryXAM queries use the XAM-defined query language (XAM QL) to search XSystems for XSet content using a content-based criteria. A query definition exists in the XStream of an XSet, which then is submitted as a XAM job. Query results are stored in a special XStream on the XSet field.

For query job runs on an EMC Centera, the VIM accesses the following XSet fields for legacy C-Clips and XSets:

◆ Only description attribute fields for legacy C-Clips

◆ Both description attributes and XAM fields for XSets

To run a query job, an XSystem must be open. When using description attributes in a query command, you must reference them by their XAM converted field namespaces (for example, ".vnd.com.emc.centera.meta.standard.binding.type" instead of "type"). All legacy C-Clip description attribute fields are binding.

Note: As EMC Centera SDK for XAM v1.0 supports query level 1 only, the xam.job.query.level field is hard-coded as "org.snia.xam.job.query.level.1” on the XSet when you run a query job. Level 1 is based on metadata query.

Contrary to the legacy SDK query, a XAM query has the following characteristics:

◆ Allows filtering on field values.

◆ Returns a filtered list of XSets instead of field values (metadata attributes as columns).

◆ Does not access EMC Centera reflections.

Note: The EMC Centera SDK for XAM v1.0 processes query operations on the client. XAM applications must remain connected to the target EMC Centera for the duration of the query operation.


XSet Operations

XSet import and exportThe export and import of complete XSets to and from a canonical XSet format allow XSets to be moved between different XSystems and storage systems without changing the XUID. In both XSet import and export XStreams, XAM uses the XML-binary Optimized Packaging (XOP) to represent the XSet canonical format in external form. The XOP format consists of an XML file that describes the content (policies, properties, and streams) of the XSet, and includes binary data as MIME attachments.

The SNIA specification Information Management —Extensible Access Method (XAM) – Part 1: Architecture, Version 1.0 contains detailed information on the XSet import and export process.

Optional vendor annotations for exportAs the XSet canonical format allows optional attributes and elements to be included, vendors can annotate existing XSet properties and XStreams with added attributes and elements. These vendor annotations can exist only in an added vendor namespace. For example, EMC Centera annotations must appear under the com.emc.centera.emcannotations namespace.

XSet exportWhen XSet_openExportXStream() is called during an XSet export, the created stream reads the contents of an XSet in canonical format from the XOP package. The XOP contains all the exported information needed to reconstruct the XSet on another vendor XSystem.

For applications that want to export XSets to another EMC Centera, the benefit of using the EMC-added annotations allows specific C-Clip data like internal GUIDs, blob sizes, and sequential numbers to be included in the XSet canonical format. By default, this data appears automatically when the XSet is opened for exporting to a stream. Applications can easily migrate XSets from one EMC Centera to another. The EMC Centera VIM restores the XSets exactly bit for bit on the target EMC Centera.

XSet operations 47

48

XSet Operations

XSet importXSets import into EMC Centera from either another EMC Centera or from a different storage system as foreign XSets.

EMC Centera XSets During imports of existing EMC Centera XSets, the EMC Centera VIM uses the meta field annotations found in the canonical export format to generate EMC Centera objects that are guaranteed to be identical to the exported objects. The VIM performs the following steps during the import process:

1. First checks for the presence of specific EMC Centera data.

2. If confirmed, uses the available EMC data provided by XSet export to begin a restore of the XSet from the source EMC Centera to the target EMC Centera.

3. Creates identical EMC Centera objects on the target EMC Centera.

4. Performs a thorough cryptographic validation and checks the pool address for a match. If the imported content is identical to the exported content, the import operation will succeed.

Note: If an EMC Centera XSet is imported to a foreign storage system and is then reimported into an EMC Centera, no validation check is possible. The EMC Centera VIM handles it as a foreign XSet.

Foreign XSets A foreign XSet is any XSet that imports to EMC Centera from a non-native storage system. To integrate the content of a foreign XSet during the import process, the EMC Centera VIM performs the following steps:

1. Marks a foreign state on the XSet when it does not detect any EMC Centera-specific data.

2. Generates a new set of EMC Centera objects in memory.

3. Stores the XSet objects to EMC Centera.

4. Returns the original foreign XUID to the API caller.


XSet Operations

Conversion of legacy dataIn XAM v1.0, the EMC Centera VIM supports full access to legacy C-Clips on an EMC Centera cluster for any preexisting data written by the legacy SDK API v1.0 and higher. The VIM API converts these C-Clips to XSets when XAM-enabled applications initially open those C-Clips.

This conversion automatically takes place when you specify the FPClipID instead of the xam_xuid parameter in the XSystem_OpenXSet() API call, as shown in the following example:

xset_handle vXSet;xam_xuid vLegacyClipID = "3M0NH9BACNCOIe3G9GCJ3PKTSP6G412MSDVRT3090V8ILCU19M1DS";

vStatus = XSystem_OpenXSet(vXSystem, vLegacyClipID, XAM_XSET_READ_ONLY, &vXSet); handleStatus(vStatus);

If the FPClipID cannot be located in the specified XSystem, the server returns the XAM_INVALID_XUID_FORMAT error.

Default conversion behaviorDuring a conversion of a legacy C-Clip to an XSet, the VIM API converts all FPTags to the appropriate field type and namespace. It performs the following default actions:

◆ Exposes all FPTags on the legacy C-Clip as XSet fields.

◆ Converts any FPTag with blob references to an XStream field.

◆ Converts all FPTag attributes to string property fields. If the maximum size of a xam_string field is exceeded, the tags convert to XStream fields with the text/plain MIME type.

◆ Empties FPTags that have no blobs or converts attributes to XStream fields, assigning them a 0 byte length with an application/octet-stream type.

◆ Puts all converted tag names into the com.emc.centera namespace.

◆ Generates only fields for attributes of FPTags with no child tags.

Conversion of legacy data 49

50

XSet Operations

◆ Puts all converted tag attribute names into the com.emc.centera.<tag name>.attrib. namespace, where tag name is the converted tag name following the handling of collision and name compression.

◆ Maintains existing C-Clip retention settings, which appear under the equivalent XAM fields.

◆ Compresses any synthesized field names longer than the allowed 512 characters and puts them into the com.emc.centera.compressed namespace.

Note: As XAM does not support nested tags, duplicate tag names, and the concept of custom metadata, these tags are renamed to the appropriate field format and namespace.

FPTag, metadata, and attribute conversionTable 14 describes the handling and conversion of SDK-defined and custom metadata, FPTags, and FPTag attributes:

Table 14 Conversion of tag elements

Tag type Conversion description

Custom metadata tags Custom metadata tags convert to xam_string fields.

Standard and profile metadata tags

SDK standard and profile metadata tags convert to read-only xam_string fields on the XSet in the .vnd.com.centera.meta namespace. If an SDK standard tag maps to a XAM-defined field, it converts to that XAM field (for example, related to retention data).

FPTags FPTags convert to fields under the same hierarchy as they existed in the legacy C-Clip.

Nested tags Nested tags convert to fields under the same hierarchy as they existed in the legacy C-Clip.

Tag names with collision Tag names with collisions convert to fields appended with a 4-digit hex value that indicates the number of detected collisions.

FPTag attributes FPTag attributes convert to fields as previously defined and ordered under the same original tag hierarchy. THe fields appear in an attrib. namespace.


XSet Operations

Example 2 shows nested tags converted to fields under the same hierarchy as they existed in the legacy C-Clip:

Example 2 Nested tag conversion

1. Existing tag hierarchy

<eclipcontents> <tag1> <eclipblob md5="3B6JJABG2TAMBxAET431ANOCNNNG4112F8DDK00U2T4RU9B3QC8QN" size="1024"/> <tag2> <eclipblob md5="5D6JJABG2TAMBxAET431ANOCNNNG4112F8DDK00U2T4RU9B3QC8QN"

size="1024"/> <tag3/> </tag2> </tag1> </eclipcontents>

2. Converted field hierarchy

Field Name Type Binding Read-only Length-----------------------------------------------------------------------------------------------------com.emc.centera.tag1 "application/octet-stream" true false 1024com.emc.centera.tag1.tag2 "application/octet-stream" true false 1024com.emc.centera.tag1.tag2.tag3"application/octet-stream" true false 0

Example 3 shows a conversion of custom metadata tags to field names:

Example 3 Custom metadata tags to field names

1. Existing meta tags:

<custom-meta name="Country" value="Canada"/> <custom-meta name="Location" value="Hopkinton"/> <custom-meta name="Organization" value="Engineering"/>

2. Converted fields

Field Name Value Type Binding Read-only ----------------------------------------- ------------ ----------- -------- --------- com.emc.centera.meta.custom.Country Canada xam_string true false com.emc.centera.meta.custom.Location Hopkinton xam_string true false com.emc.centera.meta.custom.Organization Engineering xam_string true false


52

XSet Operations

Conversion of legacy data to numbered fieldsAs an alternative, applications can simplify the conversion of legacy C-Clips by representing custom metadata, FPTags, and FPTag attributes as numbered fields on the XSets. This alternative is available as a control field on the XSystem, as shown in Table 15:

If you use this field and set the binding to true, each tag iterates in sequential order and is assigned a hexadecimal number in place of its name. In the case of tag names with collisions, instead of appending a 4-digit hex value to the fields, the tags are assigned sequential numbers.

Example 4 shows tags converted as sequential numbers in the field:

Example 4 Tag names as numbered field

1. Existing tag hierarchy

<eclipcontents> <tag1> <eclipblob md5="3B6JJABG2TAMBxAET431ANOCNNNG4112F8DDK00U2T4RU9B3QC8QN" size="1024"/> </tag1> <tag2> <eclipblob md5="5D6JJABG2TAMBxAET431ANOCNNNG4112F8DDK00U2T4RU9B3QC8QN" size="1024"/> </tag2> <tag3/> </eclipcontents>

2. Converted field “as numbers” in hierarchy

Field Name Type Binding Read-only Length-----------------------------------------------------------------------------------------------------com.emc.centera.1 "application/octet-stream" true false 1024com.emc.centera.2 "application/octet-stream" true false 1024com.emc.centera.3 "application/octet-stream" true false 0

Table 15 Numbered field

Field name MIME type Binding Read-only

vnd.com.emc.centera.legacy.tags.as.numbers xam_boolean FALSE FALSE


XSet Operations

Compression of converted field namesIf a converted field name exceeds the maximum size allowed for the xam_string field (512 bytes), the VIM compresses the field name, designating it with a com.centera.compressed namespace. Trailing segments at the end of the name are truncated until the name fits into the allowable 512 bytes. As the namespace com.centera.compressed accounts for 16 characters, the maximum size of the converted field name must be within 496 characters, otherwise, the field name is compressed and assigned to the compressed namespace.

Tag names with collisions convert to fields appended with a 4-digit hex value that indicates the number of detected collisions.

Example 5 shows a long tag name converted to a compressed field name:

Example 5 Compressed field names

1. Existing tag hierarchy:

<eclipcontents> <very_long_tag_name_that_will_exceed_512_characters_when_converted..._end> <eclipblob md5="3B6JJABG2TAMBxAET431ANOCNNNG4112F8DDK00U2T4RU9B3QC8QN" size="1024"/> </very_long_tag_name_that_will_exceed_512_characters_when_converted..._end> </eclipcontents>

2. Converted compressed field:

Field Name Type Binding Read-only Length-----------------------------------------------------------------------------------------------------com.emc.centera.compressed.very_long_tag_name..."application/octet-stream" true false 1024


54

XSet Operations

XSet retention managementRetention is the ability of an XSystem to prevent XSet deletion for a time period specified by the application. The EMC Centera VIM v1.0 supports the use of XAM retention duration policies only, which are the equivalent of retention classes in the legacy SDK API.

Note: Other than the retention duration policy and the default management policy, the EMC Centera VIM v1.0 does not support any other type of XAM policy (for example, retention enabled, storage, access, autodelete, and shred policies).

Retention levels Applications can enforce XSet retention at the XSet level or at the XSystem level, where retention duration policies apply to all XSets associated with a specific XSystem. In the absence of retention at these levels, the default principal management policy prevails, with the use of the base retention duration that is set by the cluster default.

Note: You create retention duration policies for XSystems only through EMC Centera Viewer or an equivalent application.

Order of precedence

To evaluate existing retention settings, an XSystem observes the following order of precedence from the most granular to the least granular level:

1. Field: Per retention value management properties (Level 3)

2. Policy: Per retention duration policy properties (Level 2)

3. Management policy: Per principal management policy property (default) (Level 1)

Retention types XAM provides three ways of applying retention upon commit of an XSet, as described in Table 16 on page 56. Every XSet has existing base and event fields that can be set. Values can change only if increased (for example, duration). All C-Clips belonging to an XSet are subject to the same base retention associated with the XSet, including event retention and hold settings.


XSet Operations

◆ Base: Base retention is triggered at the time an XSet is created and committed (analogous to fixed retention in the legacy SDK). Base retention includes the setting of base duration directly on the XSet, or indirectly by the assigned base retention duration policy or default management policy.

◆ Event: Event retention is triggered when an event occurs at some indeterminate amount of time after the original XSet creation (analogous to event-based retention in the legacy SDK). Event retention includes the setting of event duration directly on the XSet, or indirectly by the assigned event retention duration policy or default management policy.

Note: EMC Centera SDK for XAM v1.0 does not support user-defined retention criteria other than “event”.

Retention time criteria

XSet retention uses a retention time criteria to determine the time period(s) during which an XSet cannot be deleted from an XSystem until that criteria is met. Each set of retention criteria has the following elements:

◆ Retention identifier: An application-specified string used to identify and define the retention criteria.

◆ Enable flag: A Boolean value that indicates whether retention is or was enforced.

◆ Start time: When XSet retention begins as set by the application.

◆ Time duration: The time in milliseconds during which an XSet cannot be deleted. The combination of start time and duration represents the point in time at which the retention time criteria was met and the XSet can be deleted.

XSet retention management 55

56

XSet Operations

Table 16 lists the base and event retention calls and fields, including what the VIM behavior is on the XSet:

Table 16 Retention base/event settings (page 1 of 6)

XAM API call type Retention field type modified Binding Effect on EMC Centera XSet

base base

XSet.setBaseRetention .xset.retention.list.base true Creates the retention.base.enabled=true meta attribute in the CDF of all XSet objects.

.xset.retention.base.enabled

.xset.retention.base.duration true Sets the retention.period meta attribute in the CDF of all XSet objects to the specified duration (converted to seconds)Removes xam.xset.retention.base.duration entry in the mutable metadata of all XSet objects (if found).

Note: The EMC Centera storage system enforces this base retention.

false Sets the xam.xset.retention.base.duration entry in the mutable metadata of all XSet objects to the specified duration (converted to seconds)Removes retention.period meta attribute in the CDF of all XSet objects (if found).

Note: When XAM data is managed by CentraStar v4.0.1, the VIM enforces this base retention .

.xset.retention.base.starttime true This field is synthesized by the VIM, returning the value of the .xset.time.xuid field. This field exists in the binding C-Clip metadata as xam.time.xuid, and is created only during commit.


XSet Operations

XSet.applyBaseRetentionPolicy .xset.retention.base.duration.policy true If “.xset.retention.list.base” does not exist, both it and the “.xset.retention.base.enabled” field are created exactly as described under setBaseRetention.Sets the retention.class meta attribute in the CDF of all XSet objects to the specified policy (for example, retention class) name.Removes the xam.xset.retention.base.duration.policy entry in the mutable metadata of all XSet objects (if found).

false If “.xset.retention.list.base” does not exist, both it and the “.xset.retention.base.enabled” field are created exactly as described under setBaseRetention.Sets the xam.xset.retention.base.duration.policy entry in the mutable metadata of all XSet objects to the specified policy (for example, retention class) name.Removes the retention.class meta attribute in the CDF of all XSet objects (if found).

event event

XSet.createRetention .xset.retention.list.event true Creates a retention.list.event meta attribute in the CDF of all XSet objects with a value of event.Removes the xam.xset.retention.list.event entry in the mutable metadata of all XSet objects (if found).

false Creates a xam.xset.retention.list.event entry in the mutable metadata of all XSet objects with a value of event.Removes the retention.list.event meta attribute in the CDF of all XSet objects (if found).




58

XSet Operations

XSet.setRetentionEnabledFlag .xset.retention.event.enabled true Creates the retention.wait_state meta attribute in the CDF of all XSet objects and sets value to true.Removes the xam.xset.retention.event.enabled entry in the mutable metadata of all XSet objects (if found).

Note: The EMC Centera storage system enforces this event retention.

false Creates the xam.xset.retention.event.enabled entry in the mutable metadata of all XSet objects and sets value to true.Removes the retention.wait_state meta attribute in the CDF of all XSet objects (if found).

Note: Only the VIM enforces this event retention.

XSet.setRetentionDuration .xset.retention.event.duration true Creates the retention.vperiod meta attribute in the CDF of all XSet objects and sets to the specified duration (in seconds).If enabled is binding:Creates the eclipdescription.retention.period entry in the mutable metadata of all XSet objects and sets to the specified duration (converted to seconds) and removes the xam.xset.retention.event.duration entry in the mutable metadata of all XSet objects (if found).If enabled is non-binding:Creates the xam.xset.retention.event.duration entry in the mutable metadata of all XSet objects and sets to the specified duration (converted to seconds) and removes the eclipdescription.retention.period entry in the mutable metadata of all XSet objects (if found).




XSet Operations

false Removes the retention.vperiod meta attribute in the CDF of all XSet objects (if found).If enabled is binding:Creates the eclipdescription.retention.period entry in the mutable metadata of all XSet objects and sets to the specified duration (converted to seconds) and removes the xam.xset.retention.event.duration entry in the mutable metadata of all XSet objects (if found).If enabled is non-binding:Creates the xam.xset.retention.event.duration entry in the mutable metadata of all XSet objects and sets to the specified duration (converted to seconds) and removes the eclipdescription.retention.period entry in the mutable metadata of all XSet objects (if found).

XSet.applyRetentionDurationPolicy

.xset.retention.event.duration.policy true Creates the retention.vclass meta attribute in the CDF of all XSet objects and sets to the specified policy name (for example, retention class name).If enabled is binding:Creates the eclipdescription.retention.class entry in the mutable metadata of all XSet objects and sets to the specified policy name (for example, retention class name) and removes the xam.xset.retention.event.duration.policy entry in the mutable metadata of all XSet objects (if found).If enabled is non-binding:Creates the xam.xset.retention.event.duration.policy entry in the mutable metadata of all XSet objects and sets to the specified policy name (for example, retention class name) and removes the eclipdescription.retention.class entry in the mutable metadata of all XSet objects (if found).




60

XSet Operations

false Removes the retention.vclass meta attribute in the CDF of all XSet objects (if found).If enabled is binding:Creates the eclipdescription.retention.class entry in the mutable metadata of all XSet objects and sets to the specified policy name (for example, retention class name) and removes the xam.xset.retention.event.duration.policy entry in the mutable metadata of all XSet objects (if found).If enabled is non-binding:Creates the xam.xset.retention.event.duration.policy entry in the mutable metadata of all XSet objects and sets to the specified policy name (for example, retention class name) and removes the eclipdescription.retention.class entry in the mutable metadata of all XSet objects (if found).

XSet.setRetentionStarttime .xset.retention.event.starttime true Creates the retention.starttime meta attribute in the CDF of all XSet objects.If enabled is binding:Creates the eclipdescription.retention.etime entry in the mutable metadata of all XSet objects (set to the cluster time in seconds since the epoch) and removes the xam.xset.retention.event.starttime entry in the mutable metadata of all XSet objects (if found).If enabled is non-binding:Creates the xam.xset.retention.event.starttime entry in the mutable metadata of all XSet objects (set to the xam_datetime formatted start date) and removes the eclipdescription.retention.etime entry in the mutable metadata of all XSet objects (if found).




XSet Operations

Management properties

Table 17 lists the retention properties of the principal management policy (for example, used as default settings):

false Removes the retention.starttime meta attribute in the CDF of all XSet objects (if found).If enabled is binding:Creates the eclipdescription.retention.etime entry in the mutable metadata of all XSet objects (set to the cluster time in seconds since the epoch) and removes the xam.xset.retention.event.starttime entry in the mutable metadata of all XSet objects (if found).If enabled is non-binding:Creates the xam.xset.retention.event.starttime entry in the mutable metadata of all XSet objects (set to the xam_datetime formatted start date) and removes the eclipdescription.retention.etime entry in the mutable metadata of all XSet objects (if found).



Table 17 XSet retention management properties

Field name MIME type Binding Read only Update rules

.xset.retention.list.base xam_string TRUE TRUE Set only when created.

.xset.retention.list.event xam_string Application-defined TRUE Set only when created.

.xset.retention.list.<id> xam_string Application-defined TRUE Set only when created.

.xset.retention.base.enabled xam_boolean TRUE TRUE The binding value cannot be changed to FALSE.

.xset.retention.<id>.enabled xam_boolean Application-defined TRUE Once binding is set to true, it cannot be changed.

.xset.retention.<id>.duration xam_int Application-defined TRUE The value cannot be decreased.

.xset.retention.base.starttime xam_boolean TRUE TRUE Set only when created with the value of .xset.time.xuid.

.xset.retention.<id>.starttime xam_boolean Application-defined TRUE Set only when created.


62

XSet Operations

XSet hold managementAn XSet on hold puts the XSet on indefinite hold from deletion. This hold state overrules the existence of any or all base and event retentions that may be in effect for the XSet, until all existing holds are released. During a hold, an XSystem strictly enforces read-only access to the XSet.

The .xset.hold.list namespace provides the following fields and properties as shown in Table 18:

Table 18 XSet hold properties

Field name MIME type Binding Read-only Description

.xset.hold xam_boolean FALSE TRUE This field is set to false when added to the XUID during a commit of the XSet. If set to true, the XSet is on active hold with an existing hold list.

.xset.hold.list.<hold_id> xam_string FALSE TRUE The name of the hold identifier.


4

This chapter describes the EMC Centera VIM logging behavior. The main sections are:

◆ Logging overview .............................................................................. 64◆ VIM logging fields ............................................................................. 65◆ VIM logging configuration file ........................................................ 68◆ VIM logging environment variables ............................................... 69

VIM Logging

VIM Logging 63

64

VIM Logging

Logging overviewThe EMC Centera VIM v1.0 allows logging to be configurable through the following logging control options:

◆ VIM logging fields◆ VIM logging configuration file◆ VIM logging environment variables

Note: VIM logging is thread safe and does not create new threads.

Logging order of precedenceWhen checking for logging configurations, the EMC Centera VIM observes the following order of priority, from highest to lowest:

1. Logging fields set for the XSystem

2. FPLogState.cfg in the working directory

3. FP_LOG_STATE_PATH environment variable

4. Logging environment variables

During application startup, the VIM first checks for the presence of the FPLogState.cfg properties file in the working directory. If this file exists, the VIM automatically reads and uses the settings contained in that file, including the log path for the logging output. No attempt is made to read any logging environment variables unless FPLogState.cfg is absent from the working directory.

If this is the case and environment variables are to be used, the log state settings of the configuration file defined in FP_LOG_STATE_PATH (if specified) take precedence. That is, the VIM ignores the log path specified in the FP_LOGPATH environment variable.

If FP_LOG_STATE_PATH is not defined, the VIM uses the values specified in the logging environment variables. For example, the path set in the FP_LOGPATH is where the VIM directs the logging output. “Polling behavior” on page 71 describes how the VIM handles poll events.


VIM Logging

VIM logging fieldsThe XAM Library object provides predefined logging fields on an XSystem instance when it is first created. Using these logging fields, as described in Table 19, applications can programmatically enable logging. Example 6 on page 67 shows sample code for enabling logging. The EMC Centera VIM refers to the logging fields to determine if logging is enabled, and if so, the location of the log file to which to send logging information, and the level of logging activity to populate in the log.

Table 19 defines the available logging fields:

Table 19 Predefined logging fields (page 1 of 2)


.xsystem.log.level xam_int FALSE FALSE The current level of log event types to display in the file. The higher the value is, the greater the amount of detail to capture in the log. Values are:0 = None (Logging is disabled)1 = FATAL (Fatal Errors)2 = ERROR (Errors)3 = WARNING (Errors, Warnings)4 = INFO (Errors, Warnings, Log, Debug5 = ALL (Errors, Warnings, Log, Debug, Debug+)

Note: The default setting is 0. You can control the log level by specifying the appropriate value.

VIM logging fields 65

66

VIM Logging

To disable extra logging on an XSystem, set the value of .xsystem.log.verbosity to zero (0).

.xsystem.log.verbosity xam_int FALSE FALSE The current level of log activities for the log components being logged.0 = No debug output 1 = Minimal XAM_API debugging(Logged components are logger, api_enter, api_status, and api_exit.)2 = Verbose XAM_API debugging(Logged components are logger, api_enter, api_status, api_params, and api_exit.)3 = Verbose XAM_API and VIM_API debugging (Logged components are logger, api_enter, api_status, api_params, api_exit, vim_enter, vim_params, vim_exit, and lib.)4 = Verbose XAM_API and VIM_API debugging, VIM log events, XAM Library debug messages(Logged components are logger, api_enter, api_status, api_params, api_exit, vim_enter, vim_params, vim_exit, and lib.)5 =Verbose XAM_API and VIM_API debugging, VIM log events, additional XAM Library debug messages(Logged components are logger, api_enter, api_status, api_params, api_exit, vim_enter, vim_params, vim_exit, lib, and xam_debug++.)

Note: The default setting is 0. You can control the amount of log output by specifying the appropriate value.

.xsystem.log.path xam_string FALSE FALSE The path to the output log file. You can modify the default path indicated below to an alternate log file path and log file.

Note: The default setting is .centera_vim.log.

Table 19 Predefined logging fields (page 2 of 2)



VIM Logging

Example 6 shows an example of enabling VIM logging programmatically by connecting to the EMC Centera VIM and setting the logging fields.

Example 6 Enabling logging

// Connect to the XSystem using the Centera VIM xsystem_handle vXSystem; vStatus = XAMLibrary_Connect("snia-xam://centera_vim!sdk2.centera.lab.emc.com", &vXSystem); handleError(vStatus);

// Enable SDK logging vStatus = XAM_SetInt(vXSystem, ".xsystem.log.level", 5); handleError(vStatus); vStatus = XAM_SetInt(vXSystem, ".xsystem.log.verbosity", 5); handleError(vStatus);

VIM logging fields 67

68

VIM Logging

VIM logging configuration fileThe EMC Centera VIM supports the use of all legacy SDK logging configuration files. The default VIM behavior looks for the log configuration file named FPLogState.cfg in the working directory. Table 20 on page 69 contains definitions of the VIM logging controls.

Example 7 VIM logging configuration file

################################### FPLoggingState##################################

FP_LOGPATH=C:\Logs\DefaultSDK.logFP_LOGLEVEL=4FP_LOGFORMAT=TABFP_LOGFILTER=ALLFP_LOGKEEP=OVERWRITEFP_LOG_DISABLE_CALLBACK=FALSEFP_LOG_STATE_POLL_INTERVAL=5FP_LOG_MAX_SIZE=-1FP_LOG_MAX_OVERFLOWS=1

The following format conventions apply:

◆ The # character defines comment lines.

◆ Whitespace is ignored.

◆ Lines are expected to be name-value pairs (delimited by =) with no spaces.

◆ The supported logging name-value pairs correspond directly to the defined environment variable name-values.

◆ The <NULL> string may optionally be used to indicate an "unset" value (for example, FP_LOGPATH=<NULL> to disable logging, or just FP_LOGPATH= to clear it).


VIM Logging

VIM logging environment variablesIf set, the logging environment variables listed in Table 20 allow application administrators to control logging behavior for XSystems without having to change or write (additional) application code. The application administrator can specify the following:

◆ Dynamically modify log settings (via configuration file) for an application without requiring an application restart.

◆ Control the interval at which the VIM polls and applies the log configuration file at runtime.

◆ Limit the size at which log files are allowed to grow.

◆ Retain a fixed number of backup log files.

Note: For optimal debugging practice, EMC recommends setting the VIM logging fields at the XSystem level.

Table 20 describes the environment variables that can be used to define EMC Centera VIM logging:

Table 20 Logging environment variables (page 1 of 3)

Environment variable Description Possible values or data type

FP_LOGPATH Defines the full path to the log file on disk. This is required to enable logging. If defined, the default VIM behavior enables debug level logging to the specified file with no filtering and a 1 GB maximum size limit, including 1 retained overflow file.If unset to indicate logging is disabled, this field is set to the <NULL> string.

Path and file name of the logExample C:\MyLog.txt

FP_LOGLEVEL Determines which level of log data displays in the file.

Note: If you do not use the FP_LOGLEVEL environment variable, the default message level is set to 3.

• 1 (Error messages only)• 2 (Warning and Error

messages)• 3 (Log, Warning, and Error

messages)• 4 (Debug, Log, Warning, and

Error messages)

VIM logging environment variables 69

70

VIM Logging

FP_LOGFORMAT Determines the log file format—either XML or TAB. By default, the VIM generates a tab-delimited log file, including upon error.XML log format per line<log level tID=ProcessID.ThreadID sec=timestamp comp=component API=high level API><![CDATA[message]]></log level>

Tab-delimited log format per linewhere:\t = tab\s = space\n = newlineMS TimeStamp\tDate\sTime\t[LogLevel]\tProcessID.ThreadID\t[Component]\tMessage\n

\s\sPacketInfo\n //when applicable

• XML• TAB

FP_LOGFILTER Determines which VIM components are logged.If FP_LOGFILTER is set, you designate the individual components in a comma-separated list, otherwise, the default of ALL is used to log all components. See possible values in the adjacent column.

POOL, RETRY, XML, API, NET, TRANS, PACKET, EXCEPT, REFS, MOPI, STREAM, CSOD, CSO, MD5, APP (for application level logging), SHA, LIB (for library loading), and ALL (for all components).

FP_LOGKEEP Determines how the file is generated.If a log file does not exist, the VIM automatically creates a log file as named in FP_LOGPATH regardless of the set value. If the log file exists, the VIM uses the set value to perform one of the following actions:• OVERWRITE: (Default) Replaces the existing log

file by writing over it.• APPEND: Adds the logging information to the end

of the existing log in the log file.• CREATE: Creates a new log file name by

appending a timestamp to the end of the existing log file name and writes log messages to the new file.

• OVERWRITE• APPEND• CREATE

FP_LOG_DISABLE_CALLBACK Disables any registered log callback when set. The default is FALSE.

• TRUE or 1• FALSE or 0The value is not case-sensitive.




VIM Logging

Polling behaviorThe polling of a log state file automatically occurs regardless if logging is turned on or off. The conditions that affect logging polling behavior are as follows:

◆ If you specify a log state configuration file with the FP_LOG_STATE_PATH environment variable, the VIM polls the file at the interval defined in the configuration file (or the 5-minute default if unspecified) or in the FP_LOG_STATE_POLL_INTERVAL environment variable. If the log interval is set to 0, the VIM polls the log configuration file prior to every log event.

◆ If you modify the FP_LOGPATH field of an active configuration file during a poll event, the state dynamically changes in real time. For example, you change the log file path by editing it in the configuration file and saving it.

◆ Similarly, if you modify the path to a filename in the FP_LOGPATH field during a poll event, the VIM immediately redirects the log output to the new file based on the settings specified in FP_LOGFORMAT and FP_LOGKEEP.

◆ When a poll event interval occurs, any updates made to the following configuration file fields are applied:

FP_LOG_STATE_POLL_INTERVAL Defines the interval at which a log state configuration file is polled (in minutes). If the log interval is set to 0, the VIM polls the log configuration file prior to every log event.The default is 5 (minutes).

FPInt

FP_LOG_MAX_SIZE Determines the maximum size a log file is allowed to grow (in KB).The default is FP_LOG_SIZE_UNBOUNDED.

FPLong

FP_LOG_MAX_OVERFLOWS Determines the maximum number of backup (overflow) files to retain. The default is 1.

FPInt

FP_LOG_STATE_PATH Defines a path to the log state configuration file. This file contains log configuration information for controlling logging behavior. This file is polled at the interval set in FP_LOG_STATE_POLL_INTERVAL.

Path and file name of the log




72

VIM Logging

• FP_LOGPATH• FP_LOGLEVEL• FP_LOGFORMAT• FP_LOGFILTER• FP_LOGKEEP• FP_LOG_DISABLE_CALLBACK• FP_LOG_STATE_POLL_INTERVAL• FP_LOG_MAX_SIZE• FP_LOG_MAX_OVERFLOWS

Log file formatThe log file contains the following information:

◆ MS Timestamp — The current time of the client system when the message was logged. This timestamp records the number of milliseconds since the epoch 1 January 1970 00:00:00.000.

◆ FormattedTime — The current time of the logged message in HH:MM:SS.ms format.

◆ LogLevel — The verbosity level of the message to indicate how much information to include in the log (for example, log or debug).

◆ PID.Thread ID — The process ID of the message and the ID of the thread that logged the message.

◆ Component/Module — A two-part field that first displays the API component that logged the message, followed by the root SDK API call in the stack that generated the log message.

◆ Message — The actual message string.


VIM Logging

Example 8 XML-formatted log

<?xml version='1.0' encoding='UTF-8' standalone='no'?><SDKLog SDKVersion="4.0.657">

<log procID="3944" tID="1400" msec="1219168568625" usec="qu" comp="API"><![CDATA[[VIM API] VIM_CreateXSystem]]></log>

<log procID="3944" tID="1400" msec="1219168568625" usec="qu" comp="API"><![CDATA[[VIM API] VIM_XSystem_CreateBoolean]]></log>

<log procID="3944" tID="1400" msec="1219168568625" usec="qu" comp="API"><![CDATA[[VIM API] VIM_XSystem_CreateInt]]></log>

<debug procID="3944" tID="1400" msec="1219168568640" usec="qu" comp="CORE"><![CDATA[Start ClusterCloud::createClusterInterfaceHelper(-,-,false,true,false,-,120000,false)]]></debug>

<debug procID="3944" tID="1400" msec="1219168568640" usec="qu" comp="RETRY"><![CDATA[AN(cse2) Access Role (enabled)]]></debug>

<debug procID="3944" tID="1400" msec="1219168568640" usec="qu" comp="POOL"><![CDATA[Open FPSocket (mSocket=1180) Connection open,unlocked marked(GOOD) Type(2) for CSE2]]></debug>

<debug procID="3944" tID="1400" msec="1219168568640" usec="qu" comp="TRANSACTION"><![CDATA[Probe Request emc-lov2kpza2g6/1/PROBE]]></debug>...</SDKLog>


74

VIM Logging

Example 9 Tab-formatted log

Note: Because of space limitations on the page, the following example displays the 6-column in wrap text format.

.

.

Time FormattedTime LogLevel PID.Thread Module Message

1219168236828 2008-08-19 17:50:36.828

[none] 344.3012 [---] SDK Version 4.0.657

1219168236828 2008-08-19 17:50:36.828

[log] 344.3012 [API] [VIM API] VIM_CreateXSystem

1219168236828 2008-08-19 17:50:36.828

[log] 344.3012 [API] [VIM API] VIM_XSystem_CreateBoolean

1219168236828 2008-08-19 17:50:36.828

[log] 344.3012 [API] [VIM API] VIM_XSystem_CreateInt

1219168239640 2008-08-19 17:50:39.640

[debug] 344.3012 [POOL] Open FPSocket (mSocket=1188) Connection open,unlocked marked(GOOD) Type(2) for CSE2

1219168239640 2008-08-19 17:50:39.640

[debug] 344.3012 [TRANSACTION]

Probe Request emc-lov2kpza2g6/1/PROBE

1219168239640 2008-08-19 17:50:39.640

[debug] 344.3012 [PACKET] send SmartPacket NET_SYSTEMID type=string value=emc-lov2kpza2g6 NET_TRANSACTIONID type=string value=emc-lov2kpza2g6/1/PROBE NET_VERSION type=integer value=3 HPP_CLIENT_VERSION type=integer value=262144 POOLSERVER_VERSION type=integer value=1 NET_MESSAGEID type=integer value=36 POOLSERVER_OPCODE type=integer value=1


5

This chapter describes the XAM and EMC Centera VIM error codes that can occur during processing in the XAM Library and VIM Library. The main sections are:

◆ Error handling .................................................................................... 76◆ XAM error codes ................................................................................ 77◆ VIM error codes.................................................................................. 79

XAM and VIMError Codes

XAM and VIM Error Codes 75

76

XAM and VIM Error Codes

Error handlingAll XAM API calls return a 32-bit status code. The XAM uses error tokens to return error statuses. If a call succeeds, the XAM API returns a zero (0) status code. If a failure occurs, either the XAM or VIM library returns a positive, XAM-defined error code, as described in Table 21 on page 77.

Applications can use the XAM_GetErrorToken() API call to get more information on a returned error code.

Applications must check status after every API call.

If a negative status code returns, an error has occurred in the VIM library, for which no equivalent XAM error code is available, as described in Table 22 on page 79.



XAM error codesTable 21 lists the possible error codes that can occur in the XAM API. These standard error codes are defined in xam_errors.h.

Table 21 XAM error codes (page 1 of 2)

Value Error name Description and action

1001 XAM_UNKNOWN_ERROR An unknown error occurred

1002 XAM_OUT_OF_MEMORY Out of memory

1003 XAM_INVALID_PARAM Encountered an invalid API parameter

1004 XAM_PARAM_NOT_UTF8 Parameter found not to be UTF-8

1005 XAM_INVALID_HANDLE Invalid handle parameter

1006 XAM_INVALID_MIME_TYPE Invalid mime type

1007 XAM_INVALID_XSTREAM_MODE Invalid XStream mode

1008 XAM_INVALID_XRI XAM_INVALID_XRI

1009 XAM_INVALID_XSET_MODE Invalid operating mode for the XSet

1010 XAM_INVALID_FIELD_NAME The specified field name is invalid

1011 XAM_VIM_NOT_FOUND VIM could not be located or loaded

1012 XAM_VIM_SYMBOL_NOT_FOUND Required symbol not found in VIM

1013 XAM_FIELD_NOT_FOUND Field not found for a given handle

1014 XAM_FIELD_IS_READ_ONLY Attempted to write to a read only field

1015 XAM_FIELD_EXISTS Field already exists

1016 XAM_FIELD_IN_USE Field in use error

1017 XAM_MAX_FIELDS_EXCEEDED Too many fields exist in this object

1018 XAM_FILESYSTEM_ERROR Filesystem error

1019 XAM_XSYSTEM_ABANDONED The XSystem instance has been abandoned

1020 XAM_XSET_ABANDONED The XSet instance has been abandoned

1021 XAM_XSTREAM_ABANDONED The XStream instance has been abandoned

1022 XAM_XSYSTEM_CORRUPT The XSystem instance has been corrupted

XAM error codes 77

78


1023 XAM_XSET_CORRUPT The XSet instance has been corrupted

1024 XAM_XSTREAM_CORRUPT The XStream instance has been corrupted

1025 XAM_CONNECT_FAILED Failed to connect to the XSystem

1026 XAM_AUTH_REQUIRED Authentication is required

1027 XAM_AUTH_DATA_NEEDED Additional authentication data is required

1028 XAM_AUTH_FAILED Authentication failed

1029 XAM_BAD_XUID_FORMAT Bad XUD format

1030 XAM_XSET_INACCESSIBLE The XSet was inaccessible

1031 XAM_XASYNC_PENDING Asynchronous operation is pending

1032 XAM_NOT_SUPPORTED The operation requested is not supported

1033 XAM_OPERATION_NOT_ALLOWED Operation not allowed

1034 XAM_OBJECT_IN_USE This object is currently in use

1035 XAM_NOT_A_JOB The XSet does not contain a job request

1036 XAM_JOB_INVALID_CMD The job command is invalid

1037 XAM_JOB_INVALID_CMD_SYNTAX The job command syntax is invalid

1038 XAM_JOB_LEVEL_NOT_SUPPORTED The job level is insufficent

1039 XAM_JOB_INSUFFICIENT_PERMISSIONS The job permissions are insuffient

1040 XAM_JOB_INSUFFICIENT_RESOURCES The job resources are insufficent

1041 XAM_JOB_RUNNING A job is already running

1042 XAM_XSET_UNDER_RETENTION The XSet is under retention

1043 XAM_XSET_UNDER_HOLD The XSet is under hold and cannot be deleted

1044 XAM_XSET_INVALID_HOLD_ID The hold id is invalid

1045 XAM_XSET_INVALID_RETENTION_VALUE Invalid retention value or sequence

1046 XAM_INVALID_POLICY_NAME Invalid policy name for this operation

1047 XAM_XASYNC_HALTED The async operation was halted

Table 21 XAM error codes (page 2 of 2)




VIM error codesThe XAM API returns any EMC Centera VIM-related error codes as negative values.

To access the errors described in this section, you must include FPErrors.h.

Table 22 EMC Centera VIM error codes (page 1 of 7)


-10001 FP_INVALID_NAME The name that you have used is not XML compliant.

-10002 FP_UNKNOWN_OPTION You have used an unknown option name with FPPool_SetIntOption() or FPPool_GetIntOption().

-10003 FP_NOT_SEND_REQUEST_ERR An error occurred when you sent a request to the server.This internal error was generated because the server could not accept the request packet. Verify all LAN connections and try again.

-10004 FP_NOT_RECEIVE_REPLY_ERR No reply was received from the server.This internal error was generated because the server did not send a reply to the request packet. Verify all LAN connections and try again.

-10005 FP_SERVER_ERR The server reports an error.An internal error on the server occurred. Try again.

-10006 FP_PARAM_ERR You have used an incorrect or unknown parameter.

Example: Is a string-variable too long, null, or empty when it should not be? Does a parameter have a limited set of values? Check each parameter in your code.

-10007 FP_PATH_NOT_FOUND_ERR This path does not correspond to a file or directory on the client system.The path in one of your parameters does not point to an existing file or directory. Verify the path in your code.

-10008 FP_CONTROLFIELD_ERR The server reports that the operation generated a “Controlfield missing” error.This internal error was generated because the required control field was not found. Try again.(Obsolete from v2.0.)

VIM error codes 79

80


-10009 FP_SEGDATA_ERR The server reports that the operation generated a “Segdatafield missing” error.This internal error was generated because the required field containing the blob data was not found in the packet. Try again.(Obsolete from v2.0.)

-10010 FP_DUPLICATE_FILE_ERR A duplicate CA already exists on the server.If you did not enable duplicate file detection, verify that you have not already stored this data and try again.

-10011 FP_OFFSET_FIELD_ERR The server reports that the operation generated an “Offsetfield missing” error.This internal error was generated because the offset field was not found in the packet. Try again.(Obsolete from v2.0.)

-10012 FP_OPERATION_NOT_SUPPORTED This operation is not supported.If FPClip_Write(), FPTag_GetSibling(), FPTag_GetPrevSibling(), FPTag_GetFirstChild() or FPTag_Delete() returned this error, then this operation is not supported for C-Clips opened in ‘flat’ mode.If FPStream returned this error, then you are trying to perform an operation that is not supported by that stream.

-10013 FP_ACK_NOT_RCV_ERR A write acknowledgement was not received.Verify your LAN connections and try again.

-10014 FP_FILE_NOT_STORED_ERR Could not write the blob to the server OR could not find the blob on the server.This internal error was generated because the store operation of the blob was not successful. Verify that the original data was correctly stored, verify your LAN connections and try again.

-10015 FP_NUMLOC_FIELD_ERR The server reports that the operation generated a “Numlockfield missing” error.This internal error was generated because the numlock field was not found in the packet. Try again.(Obsolete from v2.0.)





-10016 FP_SECTION_NOT_FOUND_ERR The GetSection request could not retrieve the defined section tag.This internal error was generated because a required section is missing in the CDF. Verify the content of your code and try again.(Obsolete from v2.0.)

-10017 FP_TAG_NOT_FOUND_ERR The referenced tag could not be found in the CDF.This internal error was generated because information is missing from the description section in the CDF. Verify the content of your code and try again.

-10018 FP_ATTR_NOT_FOUND_ERR Could not find an attribute with that name.

-10019 FP_WRONG_REFERENCE_ERR The reference that you have used is invalid.The reference was not opened, already closed, or not of the correct type.

-10020 FP_NO_POOL_ERR It was not possible to establish a connection with a cluster.The server could not be located. This means that none of the IP addresses could be used to open a connection to the server or that no cluster could be found that has the required capability. Verify your LAN connections, server settings, and try again.

-10021 FP_CLIP_NOT_FOUND_ERR Could not find the referenced C-Clip in the cluster.The CDF could not be found on the server. Verify that the original data was correctly stored and try again.

-10022 FP_TAGTREE_ERR An error exists in the tag tree.Verify the content of your code and try again.

-10023 FP_ISNOT_DIRECTORY_ERR A path to a file has been given but a path to a directory is expected.Verify the path to the data and try again.

-10024 FP_UNEXPECTEDTAG_ERR Either a “file“ or “folder“ tag was expected but not given.An unexpected tag was found when retrieving the CDF. The CDF is probably corrupt.

-10025 FP_TAG_READONLY_ERR The tag cannot be changed or deleted (it is probably a top tag). Verify your program logic.

-10026 FP_OUT_OF_BOUNDS_ERR The options parameter is out of bounds.One of the function parameters exceeds its preset limits. Verify each parameter in your code.



VIM error codes 81

82


-10027 FP_FILESYS_ERR A file system error occurred, for example an incorrect path was given, or you are trying to open an unknown file or a file in the wrong mode. Verify the path and try again.

-10029 FP_STACK_DEPTH_ERR You have exceeded the nested tag limit. Review the structure of your content description and try again. Deprecated.

-10030 FP_TAG_HAS_NO_DATA_ERR You are trying to access blob data of a tag that does not contain blob data.

-10031 FP_VERSION_ERR The XSet has been created using a more recent version of the client software than you are using. Upgrade to the latest version.

-10032 FP_MULTI_BLOB_ERR The tag already has data associated with it.You need to create a new tag to store the new data or delete this tag and recreate it and try again.

-10033 FP_PROTOCOL_ERR You have used an unknown protocol option (Only HPP is supported).Verify the parameters in your code. It is also possible that an internal communication error occurred between the server and client. If you have verified your code and the problem persists then you need to upgrade to the latest client and server versions.

-10034 FP_NO_SOCKET_AVAIL_ERR No new network socket is available for the transaction.Reduce the number of open transactions between the client and the server or use the appropriate function to increase the number of available sockets with FP_OPTION_MAXCONNECTIONS.

-10035 FP_BLOBIDFIELD_ERR A BlobID field (the Content Address) was expected but not given.Upgrade to the latest client and server versions.(Obsolete from v2.0.)

-10036 FP_BLOBIDMISMATCH_ERR The blob is corrupt: a BlobID mismatch occurred between the client and server.The Content Address calculation on the client and the server has returned different results. The blob is corrupt.If this error is returned in an XSet open, it means the blob data or metadata of the XSet is corrupt and cannot be decoded.





-10037 FP_PROBEPACKET_ERR The probe packet does not contain valid server addresses.Upgrade to the latest client and server versions. (Obsolete from v2.0.)

-10038 FP_CLIPCLOSED_ERR (Java only.) You tried to perform an operation on a closed XSet. This operation requires access to an open XSet.Verify your code and try again.

-10039 FP_POOLCLOSED_ERR (Java only.) You tried to perform an operation on a closed pool. This operation requires access to an open pool. Verify your code and LAN connections and try again.

-10040 FP_BLOBBUSY_ERR The blob on the cluster is busy and cannot be read from or written to.You tried to read from or write to a blob that is currently busy with another read/write operation. Try again.

-10041 FP_SERVER_NOTREADY_ERR The server is not ready yet.This error can occur when a client tries to connect to the server to execute an operation and the nodes with the access role are running but the nodes with the storage role have not been initialized yet. This error can also occur when not enough mirror groups are found on the server. Allow the EMC Centera VIM to perform the automatic number of configured retries.

-10042 FP_SERVER_NO_CAPACITY_ERR The server has no capacity to store data.Enlarge the server’s capacity and try again.

-10043 FP_DUPLICATE_ID_ERR The application passed in a sequence ID that was previously used.

-10044 FP_STREAM_VALIDATION_ERR A generic stream validation error occurred.

-10045 FP_STREAM_BYTECOUNT_MISMATCH_ERR

A generic stream byte count mismatch was detected.

-10101 FP_SOCKET_ERR An error on the network socket occurred. Verify the network.

-10102 FP_PACKETDATA_ERR The data packet contains wrong data. Verify the network, the version of the server or try again later.

-10103 FP_ACCESSNODE_ERR No node with the access role can be found. Verify the IP addresses provided.



VIM error codes 83

84


-10151 FP_OPCODE_FIELD_ERR The Query Opcode field is missing from the packet.

-10152 FP_PACKET_FIELD_MISSING_ERR The packet field is missing.

-10153 FP_AUTHENTICATION_FAILED_ERR Authentication to get access to the server failed. Check the profile name and secret.

-10154 FP_UNKNOWN_AUTH_SCHEME_ERR An unknown authentication scheme has been used.

-10155 FP_UNKNOWN_AUTH_PROTOCOL_ERR An unknown authentication protocol has been used.

-10156 FP_TRANSACTION_FAILED_ERR Transaction on the server failed.

-10157 FP_PROFILECLIPID_NOTFOUND_ERR No profile clip was found.

-10158 FP_ADVANCED_RETENTION_DISABLED_ERR The Advanced Retention Management feature is not licensed or enabled for event retention and retention hold.

-10159 FP_NON_EBR_CLIP_ERR An attempt was made to trigger an event retention on a XSet that is not eligible to receive an event.

-10160 FP_EBR_OVERRIDE_ERR An attempt was made to trigger or enable the event retention period/policy of an XSet a second time. You can set event information only once.

-10161 FP_NO_EBR_EVENT_ERR The XSet is under event retention protection and cannot be deleted.

-10162 FP_RETENTION_OUT_OF_BOUNDS_ERR The event retention period being set does not meet the minimum/maximum rule.

-10163 FP_RETENTION_HOLD_COUNT_ERR The number of retention holds exceeds the limit of 100.

-10164 FP_METADATA_MISMATCH_ERR Mutable metadata mismatch found.

-10165 FP_METADATA_CONSTRAINT_ERR Mutable metadata constraint error.

-10166 FP_METADATA_CONCURRENCY_ERR Mutable metadata concurrent update error.

-10201 FP_OPERATION_REQUIRES_MARK The application requires marker support but the stream does not provide that.

-10202 FP_QUERYCLOSED_ERR The FPQuery for this object is already closed. (Java only).

-10203 FP_WRONG_STREAM_ERR The function expects an input stream and gets an output stream or vice-versa.

-10204 FP_OPERATION_NOT_ALLOWED The use of this operation is restricted or this operation is not allowed because the server capability is false.





-10205 FP_SDK_INTERNAL_ERR A VIM internal programming error has been detected.

-10206 FP_OUT_OF_MEMORY_ERR The system ran out of memory. Check the system’s capacity.

-10207 FP_OBJECTINUSE_ERR Cannot close the object because it is in use. Check your code.

-10208 FP_NOTYET_OPEN_ERR The object is not yet opened. Check your code.

-10209 FP_STREAM_ERR An error occurred in the generic stream. Check your code.

-10210 FP_TAG_CLOSED_ERR The FPTag for this object is already closed. (Java only.)

-10211 FP_THREAD_ERR An error occurred while creating a background thread.

-10212 FP_PROBE_TIME_EXPIRED_ERR The probe limit time was reached.

-10213 FP_PROFILECLIPID_WRITE_ERR There was an error while storing the profile clip ID.

-10214 FP_INVALID_XML_ERR The specified string is not valid XML.

-10215 FP_UNABLE_TO_GET_LAST_ERROR The last call to get the last error failed. The error status of the previous function call is unknown; the previous call may have succeeded.

-10216 FP_LOGGING_CALLBACK_ERR An error occurred in the application-defined FPLogging callback.



VIM error codes 85

86



6

This chapter provides useful programming notes and tips for application developers and system integrators who are implementing the XAM API and the EMC Centera VIM. The main sections are:

◆ Compatibility notes ........................................................................... 88◆ XAM application considerations ..................................................... 90◆ Programming tips .............................................................................. 92

Programming Notes

Programming Notes 87

88

Programming Notes

Compatibility notesThe following statements provide practical information on software interoperability between the XAM and EMC Centera SDK for XAM distributed packages:

◆ Do not mix libraries between XAM SDK, EMC Centera VIM, and EMC Centera SDK packages. Only libraries provided in a given distribution are verified to be compatible with one another.

◆ Applications may utilize the XAM API, the EMC Centera SDK API, or both from within the same application by linking to the xam library and/or FPLibrary.

◆ Do not ever link prior versions of the EMC Centera SDK with applications that utilize the XAM libraries. If a XAM application requires use of the EMC Centera SDK API, only the FPLibrary provided with a given VIM distribution is supported.

◆ When opened with the EMC Centera VIM library, C-Clips created with the legacy EMC Centera SDK automatically convert to the the XAM XSet format. If committed using the XAM API calls, the converted content is stored in XSet format, and the VIM returns a new (XUID) identifier.

◆ Do not ever use the FPLibrary API calls to manage, access, modify, or delete XSet C-Clips written with the EMC Centera VIM. The consequence of doing so can result in data loss or data unavailability.

◆ You can use the XAM API calls (via the EMC Centera VIM) to manage, access, modify, or delete legacy C-Clips. All XAM API calls that take a XUID parameter can also accept an FPClipID when using the EMC Centera VIM.

◆ Where legacy C-Clips on EMC Centera have the description attribute type set to standard, the XSet C-Clips on EMC Centera have type set to either xam.binding, xam.nonbinding, or xam.alias.

◆ At a minimum, you must install the CentraStar v4.0.1 (SP1) on the cluster in order to use the EMC Centera VIM. An error occurs during a connection attempt if the target EMC Centera software version is unsupported.


Programming Notes

Feature differences The following EMC Centera SDK features are not available or supported in this EMC Centera VIM v1.0 release:

◆ Privileged Delete◆ Audited Delete◆ Blob Purge◆ Monitoring API (MoPI)◆ Query of deleted EMC Centera content (reflections)

Note: The features that involve file and generic streams, query, nested tags, and blob write partial have similar feature equivalents in XAM. For example, XAM uses a field-naming namespace to represent nested tags and their hierarchical structures.

Compatibility notes 89

90

Programming Notes

XAM application considerationsThis section contains suggested best practices for designing XAM applications.

Authentication The following considerations relate to using authentication:

◆ To authenticate, each VIM may require different challenge/response messages, even if using the same authentication mechanisms. For details on how to initiate the transaction and respond to any server messages, see the applicable VIM documentation.

◆ Some XAM applications may authenticate to a VIM using XRI name-pair values. In this situation, you do not need to use proactive authentication API calls.

To determine if you need to make authentication calls after a connection, check to see if the .xsystem.auth.identity.authentication field exists. If present, further authentication calls are unnecessary.

Performance The following considerations relate to the performance area:

◆ Always specify the VIM name in the XRI (connection string). This avoids costly VIM discovery sequences.

◆ For increased write performance, split a large blob into multiple XStreams and write them in parallel using multiple threads (file > file.1, file.2, file.3).

To reconstruct them, read the XStream segments in parallel (file.1, file.2, file.3 > file).

EMC recommends that the minimum segment size be 5 MB or greater.

◆ Avoid using any non-binding data, if not required. The use of non-binding data may introduce a performance impact on some platforms, and may also lead to non-binding data loss under certain migration use cases where there is insufficient application prevention.

Buffer size For optimal performance reads and writes, EMC recommends that you use a buffer size of at least 5 MB. Increasing this buffer size to 20 MB provides a marginal performance improvement.


Programming Notes

Fields The following considerations relate to field usage:

◆ Set global field values on the XAMLibrary object. All created XSystem instances inherit these fields, and change the default value of any existing fields with the same name.

◆ Use an application namespace for field names. The XIterator allows for field discovery of categories of fields under an application-defined namespace, thereby making it easier to find and manage data.

◆ Each VIM may contain a different set of configuration fields. Allow users to discover and modify them as needed.

XAM application considerations 91

92

Programming Notes

Programming tipsThe following tips are intended to enhance your programming in a XAM and EMC Centera SDK for XAM environment:

◆ Use commit sparingly:

Committing an XSet stores the XSet on a XAM system. Performing additional operations on that XSet and then recommitting it will create an additional copy on EMC Centera. Your application may need to do this, but avoid overuse.

◆ Avoid frequent changing of binding and non-binding:

The binding flag for an item in an XSet affects the name of the XSet (the XUID). The continual changing of the binding characteristics of an XSet field is an expensive operation for an archival device.

◆ For adding and deleting XSet fields:

An XSet can hold a variable number of fields (attributes and/or content). The frequent adding or removing of fields from an XSet can be an expensive operation for an archival device.

◆ Avoid frequent overwriting and/or appending to a stream:

While programmers can add content to an XSet (for example, pictures, documents, and so on), frequently seeking into that content and overwriting is not a good use case for a XAM device.

◆ Avoid frequent changes to standard fields of an XSet.

XAM v1.0 has a standard set of XSet attributes (for example, retention) that can be set and changed. Avoid frequent changes to these XSet fields.

◆ Exploit parallelism for performance:

If you are new to the world of EMC Centera client programming, you should be aware that EMC Centera performance relies on an application’s use of multithreading. As EMC Centera is a large grid-based storage application running on dedicated hardware, the more of that hardware that you can get “spun up” by your application, the better the write/read performance.

Note: EMC Centera supports 10-30 concurrent application threads per access node, depending on cluster configuration and application workload.


Glossary

This glossary contains terms related to the XAM technology and the EMC Centera cluster and EMC Centera VIM. Many of these terms are used in this manual, as well as in the SNIA-sponsored XAM specifications.

Bbinding field An XSet field that affects the value assigned to the XUID when the

XUID is created while committing XSet to persistent storage.

binding modification A modification that includes adding or deleting binding fields, changing binding field values, changing the binding field type, modifying the binding flag (changing it from binding to nonbinding or vice versa), resetting the management properties, or opening a binding XStream in writeonly or appendonly mode.

CCRC The acronym for Cyclic Redundance Check.

Ffield A piece of uniquely identifiable data that can be attached to an XSet,

an XSystem, or a XAM Library. Two types of fields exist: a property and an XStream.

field attribute One or more features associated with a field. A field has multiple attributes associated with it, including type (MIME type), binding


94

Glossary

(TRUE/FALSE), readonly (TRUE/FALSE), and length (length of the value).

Mmethod An abstract interface definition for a specific piece of functionality.

When mapped to a specific programming language definition of the method, this may be a function, a procedure, a macro, or an object-oriented method.

MIME The acronym for Multipurpose Internet Mail Extensions. MIME types are used by XAM to indicate the format of the data contained in an XStream.

Nnonbinding field An XSet field that does not affect the value assigned to the XUID

when the XUID is created after committing the XSet to persistent storage.

nonbindingmodification

A modification that includes all field editing that is not a binding modification, specifically, adding or deleting nonbinding fields, changing nonbinding field values, changing the nonbinding field type, or opening a nonbinding XStream in writeonly or appendonly mode.

OOID The acronym for object identifier.

Pproperty A field whose MIME type attribute is one of the XAM-defined simple

types (stypes).

RRBAC The acronym for Role Based Access Control.

reference information Data that changes infrequently once written. Also commonly referred to as fixed content.


Glossary

Role Based AccessControl

An approach to controlling the system access of authorized users based on the user’s role within an organization.

SSASL The acronym for Simple Authentication and Security Layer.

Simple Authenticationand Security Layer

A framework for providing authentication and data security services in connection-oriented protocols and interfaces via replaceable mechanisms.

stype A set of MIME types defined in the XAM specification that are used for field type attributes and are commonly referred to as simple types.

synthetic field A XAM field that may not be physically represented within the XAM Storage System. Some fields may be derived from other state information within the XAM Storage System. From a XAM application perspective, it does not matter whether a specific XAM field is synthetic or not.

system properties A property that is created and managed by the XSystem or the XAM Library.

TTLS The acronym for Transport Layer Security.

VVIM The acronym for Vendor Interface Module.

Vendor InterfaceModule

A vendor-specific shared library that implements the standard API calls (known as the VIM API) used by the XAM Library to communicate with a specific storage system.

VIM API The methods that the XAM Library uses to communicate with the VIMs.

XXAM The acronym for eXtensible Access Method.


96

Glossary

XAM API The methods that a XAM application uses to communicate with an XSystem, via the XAM Library.

XAM application An entity that uses the XAM API to access services provided by an XSystem.

XAM job A XAM mechanism that submits work to the XSystem. The only XAM job defined is the query job.

XAM Library A shared library that implements the standardized abstraction layer between the XAM API used by applications and XAM Storage System VIMs.

XAM QL The XAM query language.

XAM query A way to search an XSystem to identify specific content. XAM uses an SQL variant, known as XAM QL, as its query language. Query results consist of a list of XUIDs identifying the XSets that match the query.

XAM session The communication mechanism and context (for example, authentication and authorization) used to access a logical container of XSets and the XSystem itself.

XAM Storage System A storage system that provides XAM-compliant storage services. Typically, this system is for data that is not expected to change during its lifetime (for example, fixed content, reference information, archival data). The contents of a XAM Storage System are exposed to applications via one or more XSystem objects in the XAM API.

XRI The acronym for XSystem Resource Identifier.

XSet The primary storage abstraction in XAM. An XSet binds data and metadata into a single entity that is stored and retrieved as a unit. MIME types are used to specifiy data and metadata formats.

XSet instance An instantiation of an XSet object. An XSet handle manipulates an XSet instance.

XSet Unique Identifier A globally unique external reference identifier for a specific XSet. Abbreviated XUID.

XStream A field that is not a simple type (stype). The XSystem does not type check the value of an XStream. An XStream’s MIME type attribute is any defined type except for the XAM-defined stypes.


Glossary

XStream instance An instantiation of an XStream object. An XStream handle manipulates an XStream instance.

XSystem A logical container of XSets that is visible to XAM applications as an abstraction in the XAM API.

XSystem instance An XSystem (for example, a logical container of XSets) and the communication mechanism and context (for example, authentication, authorization) that is used to access the XSystem. Also known as a XAM session or an instantiation of an XSystem object.

XSystem ResourceIdentifier

An identifier used to specify a target XSystem that can include optional parameters that are useful when connecting to a XAM Storage System. The syntax is similar to an Internationalized Resource Identifier (IRI), with field definitions specific to XAM.

XUID The acronym for XSet Unique Identifier.


98

Glossary


Index

AAccess Node error 83acknowledgement error 80annotations 47application considerations 90application registration fields 30attribute error 81authentication 18authentication error 84authentication protocol error 84authentication scheme error 84

Bbase retention 55best practices

authentication 90fields 91performance 90

bloberror 80, 83

BlobID mismatch 82buffer size 90

CCA

duplicate 80C-Clip

error 81closed C-Clip error 83closed pool error 83comments 6compatibility notes 88

configuration settings 22connection error 81conversion

compressed names 50, 53nested tag 51numbered fields 51

conversion legacy data 49custom metadata tags 51

Ddata

error 82data packet error 83default conversion behavior 49directory error 81documentation, related 4duplicate CA 80

EEMC

import 48enabling logging 67error

acknowledgement 80attribute 81authentication 84authentication protocol 84authentication scheme 84blob 80capacity server 83C-Clip 81connection 81data 82


100

Index

data packet 83descriptions 79directory 81file system 82generic stream 85network socket 83node with the access role 83number 79object in use 85object not open 85packet field 84parameter 79path 79protocol 82section 81send request 79server 79socket 82stack depth 82system memory 85tag 81, 82tag tree 81thread 85VIM internal 85wrong reference 81

error handling 76event retention 55

Ffield

attributes 22names 21namespace 21types 21

file system error 82foreign XSet 48FP_ACCESSNODE_ERR 83FP_ACK_NOT_RCV_ERR 80FP_ADVANCED_RETENTION_DISABLED_ERR

84FP_ATTR_NOT_FOUND_ERR 81FP_AUTHENTICATION_FAILED_ERR 84FP_BLOBBUSY_ERR 83FP_BLOBIDFIELD_ERR 82FP_BLOBIDMISMATCH_ERR 82FP_CLIP_NOT_FOUND_ERR 81

FP_CLIPCLOSED_ERR 83FP_CONTROLFIELD_ERR 79FP_DUPLICATE_FILE_ERR 80FP_DUPLICATE_ID_ERR 83FP_EBR_OVERRIDE_ERR 84FP_FILE_NOT_STORED_ERR 80FP_FILESYS_ERR 82FP_INVALID_NAME 79FP_INVALID_XML_ERR 85FP_ISNOT_DIRECTORY_ERR 81FP_LOGGING_CALLBACK_ERR 85FP_METADATA_MISMATCH_ERR 84FP_MULTI_BLOB_ERR 82FP_NO_EBR_EVENT_ERR 84FP_NO_POOL_ERR 81FP_NO_SOCKET_AVAIL_ERR 82FP_NON_EBR_CLIP_ERR 84FP_NOT_RECEIVE_REPLY_ERR 79FP_NOT_SEND_REQUEST_ERR 79FP_NOTYET_OPEN_ERR 85FP_NUMLOC_FIELD_ERR 80FP_OBJECTINUSE_ERR 85FP_OFFSET_FIELD_ERR 80FP_OPCODE_FIELD_ERR 84FP_OPERATION_NOT_ALLOWED 84FP_OPERATION_NOT_SUPPORTED 80FP_OPERATION_REQUIRES_MARK 84FP_OUT_OF_BOUNDS_ERR 81FP_OUT_OF_MEMORY_ERR 85FP_PACKET_FIELD_MISSING_ERR 84FP_PACKETDATA_ERR 83FP_PARAM_ERR 79FP_PATH_NOT_FOUND_ERR 79FP_POOLCLOSED_ERR 83FP_PROBE_TIME_EXPIRED_ERR 85FP_PROBEPACKET_ERR 83FP_PROFILECLIPID_NOTFOUND_ERR 84FP_PROFILECLIPID_WRITE_ERR 85FP_PROTOCOL_ERR 82FP_QUERYCLOSED_ERR 84FP_RETENTION_HOLD_COUNT_ERR 84FP_RETENTION_OUT_OF_BOUNDS_ERR 84FP_SDK_INTERNAL_ERR 85FP_SECTION_NOT_FOUND_ERR 81FP_SEGDATA_ERR 80FP_SERVER_ERR 79FP_SERVER_NO_CAPACITY_ERR 83


Index

FP_SERVER_NOTREADY_ERR 83FP_SOCKET_ERR 83FP_STACK_DEPTH_ERR 82FP_STREAM_BYTECOUNT_MISMATCH_ ERR

83FP_STREAM_ERR 85FP_STREAM_VALIDATION_ERR 83FP_TAG_CLOSED_ERR 85FP_TAG_HAS_NO_DATA_ERR 82FP_TAG_NOT_FOUND_ERR 81FP_TAG_READONLY_ERR 81FP_TAGTREE_ERR 81FP_THREAD_ERR 85FP_TRANSACTION_FAILED_ERR 84FP_UNABLE_TO_GET_LAST_ERROR 85FP_UNEXPECTEDTAG_ERR 81FP_UNKNOWN_AUTH_SCHEME_ERR 84FP_UNKNOWN_OPTION 79FP_VERSION_ERR 82FP_WRONG_REFERENCE_ERR 81FP_WRONG_STREAM_ERR 84FPPool capabilities 34FPPoolInfo 38

Ggeneric stream error 85global fields 23, 25Governance Edition (GE) 35granules 20

Hhold management 62

Iint options 39interoperability 88invalid name 79

Llogging

configuration file 68enabling 67environment variables 69fields 65

log file format 72log level 65log path 66log verbosity 66order of precedence 64tab-formatted log 74XML formatted log 73

logging configuration file 68logging environment variables

FP_LOG_DISABLE_CALLBACK 70FP_LOG_MAX_OVERFLOWS 71FP_LOG_MAX_SIZE 71FP_LOG_STATE_PATH 71FP_LOG_STATE_POLL_INTERVAL 71FP_LOGFILTER 70FP_LOGFORMAT 70FP_LOGKEEP 70FP_LOGLEVEL 69FP_LOGPATH 69

logging fields 65logging functions 64

Mmanagement policy 61MIME types 22mismatch BlobID 82

Nname

error 79namespace 21nested tag conversion 51network socket error 83

Ooperation, not supported 80option name, unknown 79out of bounds, options parameter 81

Ppacket field error 84parameter

error 79unknown 79


102

Index

path error 79performance

recommended buffer size 90polling behavior 71profile XSet 41programming tips 92protocol

error 82unknown 82

Rread-only tag 81reauthentication 19retention

base 55event 55levels 54order of precedence 54settings 56time criteria 55types 54

retention management 54retention time criteria 55

SSASL 18

ANONYMOUS 18PLAIN 18

send request error 79server capacity error 83server error 79server not ready error 83simple types 22SNIA specifications web site 9SNIA website 8socket error 82stack depth error 82system memory error 85

Ttab-formatted log 74tag

read-only 81unexpected 81

tag error 81, 82

tag tree error 81thread error 85

Uunexpected tag 81unknown

option name 79parameter 79protocol 82

Vvendor annotations 47version error 82VIM architecture 12VIM discovery 16VIM error codes 79VIM internal error 85VIM Library 9VIM logging configuration file 68

Wwrong reference error 81

XXAM

architecture 9error codes 76, 77fields 21granules 20import/export 47overview 8process flow 10query 46SNIA 8

XAM API 9XAM Library 9

fields 23global options 25

XML-formatted log 73XOP 47XRI 13, 16XRI syntax 16XSet

canonical format 47


Index

export 47fields 40hold 62operations 45overview 44

XSet definition 13XStream definition 13

XSystemauthentication 18connection 16fields 31

XSystem definition 13XUID 13XUID byte format 44


104

Index


emc centera sdk for xam version 1.0 vim reference guide · 8/19/2008 · carnegie mellon...

Documents