Atmos CAS 2.0 API Reference Guide 300-012-505 A01

EMC Atmos
Version 2.0
CAS API Reference Guide

P/N 300-012-505
REV A01
EMC Corporation
Corporate Headquarters:
Hopkinton, MA 01748-9103
1-508-435-1000
www.EMC.com
Copyright 2008 - 2011 EMC Corporation. All rights reserved.

Published June, 2011
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 regulatory document for your product line, go to the Technical Documentation and
Advisories section on EMC Powerlink.
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.
EMC Atmos Version 2.0 CAS API Reference Guide
Contents
Tables
Preface
Chapter 1
Introduction
Overview............................................................................................ 18
Function syntax ................................................................................. 19
Function call ............................................................................... 19
Parameter list.............................................................................. 20
Unicode and wide character support............................................. 21
Unicode and wide character routines...................................... 23
API data types ................................................................................... 25
Atmos CAS specifications................................................................ 28
Chapter 2
Pool Functions
Pool functions.................................................................................... 32
FPPool_Close............................................................................... 33
FPPool_GetCapability................................................................ 34
FPPool_GetClipID ..................................................................... 37
FPPool_GetClusterTime ............................................................ 38
FPPool_GetComponentVersion................................................ 39
FPPool_GetGlobalOption .......................................................... 40
FPPool_GetIntOption................................................................. 41
FPPool_GetLastError ................................................................. 42
FPPool_GetLastErrorInfo .......................................................... 43
FPPool_GetPoolInfo ................................................................... 44
FPPool_GetRetentionClassContext.......................................... 46
FPPool_Open............................................................................... 47
FPPool_RegisterApplication ..................................................... 50
FPPool_SetClipID ...................................................................... 51
FPPool_SetGlobalOption........................................................... 54
FPPool_SetIntOption.................................................................. 57
Chapter 3
Clip Functions
Clip functions .................................................................................... 60
Clip handling functions ................................................................... 60
FPClip_AuditedDelete............................................................... 61
FPClip_Close ............................................................................... 64
FPClip_Create ............................................................................. 65
FPClip_Delete ............................................................................. 67
FPClip_EnableEBRWithClass ................................................... 69
FPClip_EnableEBRWithPeriod................................................. 69
FPClip_Open ............................................................................... 70
FPClip_RawOpen ....................................................................... 72
FPClip_RawRead........................................................................ 73
FPClip_RemoveRetentionClass................................................ 74
FPClip_SetName......................................................................... 75
FPClip_SetRetentionClass ......................................................... 76
FPClip_SetRetentionHold ......................................................... 76
FPClip_SetRetentionPeriod....................................................... 77
FPClip_TriggerEBREvent.......................................................... 79
FPClip_TriggerEBREventWithClass........................................ 79
FPClip_TriggerEBREventWithPeriod ..................................... 80
FPClip_Write............................................................................... 80
FPClipID_GetCanonicalFormat ............................................... 82
FPClipID_GetStringFormat....................................................... 84
Clip info functions ............................................................................ 85
FPClip_Exists .............................................................................. 85
FPClip_GetClipID ...................................................................... 87
FPClip_GetCreationDate........................................................... 88
FPClip_GetEBRClassName....................................................... 89
FPClip_GetEBREventTime........................................................ 90
FPClip_GetEBRPeriod ............................................................... 91
FPClip_GetName........................................................................ 92
FPClip_GetNumBlobs................................................................ 93
FPClip_GetNumTags................................................................. 94
FPClip_GetPoolRef..................................................................... 95
FPClip_GetRetentionClassName ............................................. 96
FPClip_GetRetentionHold ........................................................ 96
FPClip_GetRetentionPeriod...................................................... 98
FPClip_GetTotalSize...................................................................99
FPClip_IsEBREnabled ..............................................................100
FPClip_IsModified....................................................................101
FPClip_ValidateRetentionClass..............................................102
Clip attribute functions .................................................................. 103
FPClip_GetDescriptionAttribute ............................................103
FPClip_GetDescriptionAttributeIndex ..................................105
FPClip_GetNumDescriptionAttributes .................................107
FPClip_RemoveDescriptionAttribute....................................108
FPClip_SetDescriptionAttribute .............................................109
Clip tag functions ............................................................................ 111
FPClip_FetchNext .....................................................................111
FPClip_GetTopTag ...................................................................112
Chapter 4
Tag Functions
Tag functions.................................................................................... 116
Tag handling functions................................................................... 116
FPTag_Close ..............................................................................117
FPTag_Copy ..............................................................................118
FPTag_Create.............................................................................120
FPTag_Delete.............................................................................121
FPTag_GetBlobSize...................................................................122
FPTag_GetClipRef ....................................................................123
FPTag_GetPoolRef ....................................................................124
FPTag_GetTagName ................................................................125
Tag navigation functions................................................................ 127
FPTag_GetFirstChild ................................................................129
FPTag_GetParent ......................................................................130
FPTag_GetPrevSibling .............................................................131
FPTag_GetSibling......................................................................132
Tag attribute functions.................................................................... 133
FPTag_GetBoolAttribute..........................................................134
FPTag_GetIndexAttribute .......................................................135
FPTag_GetLongAttribute ........................................................137
FPTag_GetNumAttributes.......................................................138
FPTag_GetStringAttribute.......................................................139
FPTag_RemoveAttribute .........................................................140
FPTag_SetBoolAttribute...........................................................141
FPTag_SetLongAttribute .........................................................142
FPTag_SetStringAttribute........................................................144
Chapter 5
Blob Handling Functions

Blob handling functions................................................................. 148
FPTag_BlobExists ..................................................................... 148
FPTag_BlobRead....................................................................... 150
FPTag_BlobReadPartial ........................................................... 152
FPTag_BlobWrite...................................................................... 155
FPTag_BlobWritePartial .......................................................... 160
Chapter 6
Retention Class Functions

Retention class functions ............................................................... 168
FPRetentionClass_Close .......................................................... 168
FPRetentionClassContext_Close ............................................ 169
FPRetentionClassContext_GetFirstClass .............................. 170
FPRetentionClassContext_GetLastClass............................... 170
FPRetentionClassContext_GetNamedClass ......................... 171
FPRetentionClassContext_GetNextClass.............................. 171
FPRetentionClassContext_GetNumClasses ......................... 172
FPRetentionClassContext_GetPreviousClass....................... 173
FPRetentionClass_GetName................................................... 173
FPRetentionClass_GetPeriod.................................................. 174
Chapter 7
Stream Functions
Stream functions ............................................................................. 178
Stackable stream support ........................................................ 178
Generic stream operation ........................................................ 178
Stream creation functions .............................................................. 181
FPStream_CreateBufferForInput............................................ 181
FPStream_CreateBufferForOutput ........................................ 182
FPStream_CreateFileForInput ................................................ 183
FPStream_CreateFileForOutput ............................................. 184
FPStream_CreateGenericStream ............................................ 186
FPStream_CreatePartialFileForInput .................................... 203
FPStream_CreatePartialFileForOutput ................................. 205
FPStream_CreateTemporaryFile ............................................ 207
FPStream_CreateToNull.......................................................... 208
FPStream_CreateToStdio......................................................... 208
Stream handling functions ............................................................ 209
FPStream_Close ........................................................................ 209
FPStream_Complete................................................................. 210
FPStream_GetInfo .................................................................... 211
FPStream_PrepareBuffer ......................................................... 212
FPStream_ResetMark ...............................................................213
FPStream_SetMark ...................................................................214
Chapter 8
Query Functions
Query functions............................................................................... 216
Query expression functions ........................................................... 217
FPQueryExpression_Close ......................................................218
FPQueryExpression_Create.....................................................218
FPQueryExpression_DeselectField ........................................219
FPQueryExpression_GetEndTime..........................................220
FPQueryExpression_GetStartTime ........................................221
FPQueryExpression_GetType.................................................222
FPQueryExpression_IsFieldSelected......................................223
FPQueryExpression_SelectField .............................................224
FPQueryExpression_SetEndTime ..........................................227
FPQueryExpression_SetStartTime .........................................228
FPQueryExpression_SetType..................................................229
Pool query functions....................................................................... 230
FPPoolQuery_Close..................................................................231
FPPoolQuery_FetchResult.......................................................231
FPPoolQuery_GetPoolRef .......................................................233
FPPoolQuery_Open..................................................................234
Query result functions.................................................................... 236
FPQueryResult_Close...............................................................236
FPQueryResult_GetClipID ......................................................237
FPQueryResult_GetField .........................................................238
FPQueryResult_GetResultCode..............................................239
FPQueryResult_GetTimestamp ..............................................240
FPQueryResult_GetType .........................................................241
Chapter 9
Time Functions
Time functions ................................................................................. 244
FPTime_MillisecondsToString ................................................244
FPTime_SecondsToString ........................................................246
FPTime_StringToMilliseconds ................................................247
FPTime_StringToSeconds ........................................................248
Chapter 10
Logging Functions
Logging overview ........................................................................... 250
FPLogging mechanism.............................................................250
FPLogState................................................................................. 251
Logging environment variables ............................................. 252
Polling behavior........................................................................ 252
Log file format........................................................................... 253
Application strings in SDK log............................................... 253
Redirecting log output............................................................. 254
FPLogging functions ...................................................................... 255
FPLogging_CreateLogState .................................................... 255
FPLogging_Log......................................................................... 256
FPLogging_OpenLogState ...................................................... 257
FPLogging_RegisterCallback.................................................. 258
FPLogging_Start ....................................................................... 259
FPLogging_Stop........................................................................ 259
FPLogState_Delete.................................................................... 260
FPLogState_Save....................................................................... 261
FPLogState functions...................................................................... 262
FPLogState_GetAppendMode................................................ 262
FPLogState_GetDisableCallback ............................................ 263
FPLogState_GetLogFilter ........................................................ 264
FPLogState_GetLogFormat ..................................................... 264
FPLogState_GetLogLevel ........................................................ 265
FPLogState_GetLogPath.......................................................... 265
FPLogState_GetMaxLogSize................................................... 266
FPLogState_GetMaxOverflows .............................................. 267
FPLogState_GetPollInterval.................................................... 267
FPLogState_SetAppendMode................................................. 268
FPLogState_SetDisableCallback ............................................. 269
FPLogState_SetLogFilter ......................................................... 270
FPLogState_SetLogFormat...................................................... 271
FPLogState_SetLogLevel ......................................................... 272
FPLogState_SetLogPath........................................................... 273
FPLogState_SetMaxLogSize.................................................... 274
FPLogState_SetMaxOverflows ............................................... 275
FPLogState_SetPollInterval..................................................... 276
Environment variables................................................................... 277
Example: XML-formatted log ................................................. 279
Example: Tab-formatted log ................................................... 280
Example: FPLogState configuration file................................ 281
Chapter 11
Error Codes
Error codes....................................................................................... 284
Appendix A
Deprecated Functions
Deprecated functions...................................................................... 294
Deprecated options ......................................................................... 295
Glossary
Index
10
Tables
Title
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Page
Mapping of terms between Centera and Atmos......................................... 18

API function types........................................................................................... 19
Function variants............................................................................................. 21
String encoding................................................................................................ 22
Atmos CAS data types.................................................................................... 25
FPErrorInfo structure...................................................................................... 26
FPPoolInfo structure ....................................................................................... 26
FPStreamInfo structure................................................................................... 26
Content specifications..................................................................................... 28
SDK pool operations ....................................................................................... 30
Capability names and attributes ................................................................... 35
Generic stream to Atmos CAS FPStreamInfo/callbacks ..................... 187
Generic stream from Atmos CAS FPStreamInfo/callbacks............... 188
FPStreamInfo field descriptions per callback............................................ 189
Standard C-Clip description attributes ...................................................... 224
Standard reflection description attributes ................................................. 225
Logging environment variables .................................................................. 277
Error codes ..................................................................................................... 284
Deprecated functions .................................................................................... 294
Deprecated options ....................................................................................... 295
11
12
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.
Note: This document was accurate as of the time of publication. However, as
information is added, new versions of this document may be released to the
EMC Powerlink website. Check the Powerlink website to ensure that you are
using the latest version of this document.
Purpose
Audience
This guide is for experienced programmers who are developing

applications that interface with an Atmos CAS-enabled node using
the Atmos CAS API. This guide is a companion supplement to the
EMC Atmos CAS Programmers Guide. It provides the API calls used to
access Atmos CAS.
Readers of this guide are expected to be familiar with the following
topics:
Content Addressed Storage (CAS)

Atmos CAS architecture and features
13
Preface
Related
documentation
Conventions used in
this document
The EMC Atmos documentation set also includes the following titles:
EMC Atmos Release Notes
EMC Atmos CAS Programmers Guide
EMC Atmos CAS for XAM VIM Reference Guide
EMC Atmos Administrators Guide
EMC Atmos Programmers Guide
EMC Atmos System Management API Guide
EMC Atmos Security Configuration Guide
EMC Atmos Non-EMC Software License Agreements
EMC Atmos Hardware Guide
EMC Atmos online help
EMC uses the following conventions for special notices.

Note: A note presents information that is important, but not hazard-related.
IMPORTANT
An important notice contains information essential to operation of
the software.
Typographical conventions
EMC 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, filenames, functions, utilities
URLs, pathnames, filenames, directory names, computer
names, 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 call, 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
14
Preface
Where to get help
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)
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
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 Powerlink and

choose Support. On the Support page, you will see several options,
including one for making a service request. Note that to open a
service request, you must have a valid support agreement. Please
contact your EMC sales representative for details about obtaining a
valid support agreement or with 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 opinions of this document to:
techpubcomments@emc.com
15
Preface
16
Invible Body Tag
Introduction
This chapter introduces the C API function types and syntax

conventions that comprise the EMC Atmos CAS API. It also includes
detailed Atmos CAS specifications.
The main sections in this chapter are:
Function syntax ..................................................................................

Unicode and wide character support..............................................
API data types ....................................................................................
Atmos CAS specifications.................................................................
Introduction
19
21
25
28
17
Introduction
Overview
Applications use the native Atmos CAS API (aka the EMC Centera
SDK or SDK) to interact with Atmos CAS, an access method for
Content Addressable Storage on the Atmos platform. Atmos CAS
requires CAS API version 3.1 or higher.
This first release of Atmos CAS on Atmos supports a set of CAS
features that is nearly equivalent to the functions of the Centera Basic
Edition, however, with some limitations. Any restrictions that relate
to specific API calls are indicated in the description section of those
API calls, where applicable.
Note: You also can find limitations generally described in Chapter 4: Best
Practices in the EMC Atmos CAS Programmers Guide.
In this guide, the following Centera terms in Table 1 are mapped to

their equivalents in Atmos. The terms can be used interchangeably as
references to describe the same concepts:
Table 1
18
Mapping of terms between Centera and Atmos

Centera term
Atmos equivalent
Pool
A combination of subtenant ID and user ID (UID)
Profile
Subtenant UID
Cluster
CAS-enabled access nodes
PEA file
PEA file or the shared secret of the UID
C-Clip ID
Atmos object ID
Introduction
Function syntax
This section details the syntax of the EMC Atmos CAS Access API
function calls.
Function call
Function names consist of a prefix followed by the actual function.

The prefix refers to the object type on which the function operates.
Table 2 on page 19 shows the API functions categorized by function
class:
Table 2
Example
API function types

Function class
Function name prefix
Pool functions
FPPool
C-Clip functions
FPClip or FPClipID
Tag functions
FPTag
Retention Class functions
FPRetentionClassContext or
FPRetentionClass
Stream functions
FPStream
Query functions
Pool query functions
Query result functions
FPQueryExpression
FPPoolQuery
FPQueryResult
Time format functions
FPTime
Logging functions
FPLogging or FPLogState
FPPool_Open() opens a pool, FPClip_Open() opens a C-Clip.
Function syntax
19
Introduction
Parameter list
The parameter list contains all parameters that a function requires.

Each parameter is preceded by its type definition and is prefixed by
one of the following:
"in" Input parameter
"out" Output parameter
"io" Input and output parameter
Commas separate parameters in the parameter list:

(parameter_type parameter1, parameter_type parameter2, )
Some parameter types are API-specific. Refer to API data types on

page 25.
Example
FPPoolRef inPool is a reference to a pool.
The void type is used for functions that do not require a parameter or
have no return value.
FPPool_GetLastError (void)
20
Introduction
Unicode and wide character support

The Atmos CAS API supports Unicode characters (ISO-10646) for
specific calls that read, write or update C-Clip metadata, specifically
UTF-8, UTF-16 and UTF-32 encodings. On architectures that support
2-byte wide characters, the Atmos CAS API also supports UCS-2
encodings.
Functions that accept string arguments have a wide character and
three Unicode variants. Each variant has a suffix indicating its type of
string support.
For example, the function to open a pool (FPPool_Open (const char
*inPoolAddr)) accepts a string argument (the connection string).
Therefore, the FPPool_Open function has the following wide
character and Unicode variants:
FPPool_OpenW (const wchar_t *inPoolAddr)
FPPool_Open8 (const FPChar8 *inPoolAddr)
Note: A separate reference page is not provided for each variant function,
since aside from the function name and data type, the calls are all the same.
If you are localizing your application, use the "8", "16", and "32"
functions. Otherwise, you can use the default Latin-1 (no suffix) and
wide ("W") functions.
Table 3 on page 21 lists the function variants.
Table 3
Function variants
Function
suffix
String parameter
type
Character width
(bits)
Encoding
None
char *
Latin-1
wchar_t *
16 or 32 (platform
dependent)
UCS2 (for 16-bit characters) or

UCS4 (for 32-bit characters)
char *
UTF-8
16
FPChar16 *
16
UTF-16
32
FPChar32 *
32
UTF-32
21
Introduction
Note: Atmos CAS API calls that retrieve metadata (for example,
FPClip_GetDescriptionAttribute) may have parameters that contain
the address of an integer value that specifies the size of a user-provided
buffer in this way: as an input parameter that sizes the user supplied buffer
which the API may overwrite with the size that the output text actually
requires.
This integer value is determined by the data type that the API call is using.
For example, if the ioAttrValueLen parameter of the
FPClip_GetDescriptionAttribute16 routine is set to 20 by the user,
then a buffer of 40 bytes would be provided. After the call, the value of
ioAttrValueLen may be set to 10 by the API, indicating that 20 bytes was
actually needed to store the UTF-16 string into outAttrValue.
Table 4 on page 22 lists the input and output units for API calls that
deal with string encoding.
Table 4
String encoding
API string-encoded calls
Input and output units
Latin-1
Number of char
Wide
Number of wchar_t
UTF-8
Number of char
UTF-16
Number of FPChar16
UTF-32
Number of FPChar32
Note: A UTF-8 encoded character may take up 6 bytes, while a UTF-16

encoded character may take up 4 bytes. Therefore, care should be taken when
allocating UTF-8 and UTF-16 related buffers.
22
Introduction
Unicode and wide character routines

The following routines support Unicode and wide characters. These
characters append to the routine name, for example, FPPool_OpenW,
FPPool_Open8, FPPool_Open16, and FPPool_Open32:
FPClip_AuditedDelete
FPClip_Create
FPClip_GetDescriptionAttribute
FPClip_GetDescriptionAttributeIndex
FPClip_GetEBRClassName
FPClip_GetEBREventTime
FPClip_GetName
FPClip_GetRetentionClassName
FPClip_RemoveDescriptionAttribute
FPClip_SetDescriptionAttribute
FPClip_SetRetentionHold
FPLogging_Log
FPLogging_OpenLogState
FPLogState_SetLogPath
FPLogState_Save
FPPool_GetCapability
FPPool_GetClusterTime
FPPool_GetComponentVersion
FPPool_GetGlobalOption
FPPool_GetIntOption
FPPool_Open
FPPool_RegisterApplication
FPPool_SetGlobalOption
FPPool_SetIntOption
FPQueryExpression_DeselectField
FPQueryExpression_IsFieldSelected
FPQueryExpression_SelectField
FPQueryResult_GetField
FPRetentionClass_GetName
FPRetentionClassContext_GetNamedClass
FPTag_Create
FPStream_CreatePartialFileForInput
FPStream_CreatePartialFileForOutput
FPTag_GetBoolAttribute
FPTag_GetIndexAttribute
FPTag_GetLongAttribute
FPTag_GetStringAttribute
FPTag_GetTagName
FPTag_RemoveAttribute
FPTag_SetBoolAttribute
FPTag_SetLongAttribute
23
Introduction
24
FPTag_SetStringAttribute
FPTime_MillisecondsToString
FPTime_SecondsToString
FPTime_StringToMilliseconds
FPTime_StringToSeconds
Introduction
API data types

Table 5 on page 25 lists the data types used by the Atmos CAS API:
Table 5
Atmos CAS data types

Data type
Definition
FPLong
64-bit signed integer
FPInt
FPShort
FPBool
Boolean with possible values true (1) and false (0)
FPChar16
16-bit character with UTF-16 encoding
FPChar32
32-bit character with UTF-32 encoding
FPClipID
Character array used to identify a C-Clip
FPErrorInfo
The structure that holds error information, which is retrieved

by FPPool_GetLastErrorInfo(). The application
should not deallocate or modify the pointer member variables.
The FPErrorInfo structure is detailed in Table 6 on page 26.
FPPoolInfo
The structure that specifies pool information. The application

should not deallocate or modify the pointer member variables.
The FPPoolInfo structure is detailed in Table 7 on page 26.
FPStreamInfo
The stream structure that passes information to and from

callback functions. The FPStreamInfo structure is detailed in
Table 8 on page 26.
API data types
25
Introduction
Table 6
Table 7
Table 8
26
FPErrorInfo structure
Errorinfo type
Definition
FPInt error
The last FPLibrary error that occurred on the current thread.
FPInt systemError
The last system error that occurred on this thread.
char* trace
The function trace for the last error that occurred.
char* message
The message associated with the FPLibrary error.
char* errorString
The error string associated with the FPLibrary error.
FPShort errorClass
The class of message:

FP_NETWORK_ERRORCLASS (network error)
FP_SERVER_ERRORCLASS (cluster error)
FP_CLIENT_ERRORCLASS (client application error,
probably due to coding error or wrong usage)
FPPoolInfo structure
PoolInfo type
Definition
FPInt poolInfoVersion
The current version of this structure (2).
FPLong capacity
The total capacity of the pool, in bytes.
FPLong freeSpace
The total free usable space of the pool, in bytes.
char clusterID[128]
The cluster identifier of the pool.
char clusterName[128]
The name of the cluster.
char version[128]
The version of the pool server software.
char replicaAddress[256]
A comma-separated list of the replication clusters node

(with the access role) addresses as specified when
replication was enabled; empty if replica cluster not
identified or configured.
FPStreamInfo structure (page 1 of 2)

StreamInfo type
Definition
short mVersion
The current version of FPStreamInfo.
void *mUserData
Application-specific data, untouched by the SDK.
Introduction
Table 8
FPStreamInfo structure (page 2 of 2)

FPLong mStreamPos
The current position in the stream.
FPLong mMarkerPos
The position of the stream marker.
FPLong mStreamLen
The length of the stream in bytes, if known, else 1.
FPBool mAtEOF
True if the end of stream has been reached.
FPBool mReadFlag
Read/write indicator, true on FPTag_BlobWrite(), false on

FPTag_BlobRead().
void *mBuffer
The data buffer supplied by the application.
FPLong mTransferLen
The number of bytes to be transferred or actually

transferred.
API data types
27
Introduction
Atmos CAS specifications

This section lists the specifications that apply to Atmos CAS
operations.
Note: Contact your EMC representative if there is a need to exceed any of the
product specifications listed in the following tables.
Table 9 on page 28 shows the general C-Clip specifications.

Table 9
Content specifications (page 1 of 2)

Specification
Value
Note
Maximum number of tags per CDF
131072 or 100MB,
whichever is larger
Atmos CAS API: The

number of tags cannot
exceed 131072. The
maximum is limited to how
many tags can fit into 100MB
(max CDF size).
Maximum CDF size
100MB
The maximum allowed

segment size of 100MB.
Maximum blob size
100GB
The EMC-recommended limit.
Maximum size of an embedded blob
100KB (default)
The maximum by default. An

application can change this
default up to a maximum of
1MB.
Note: Exceeding 100KB can
have a negative impact on
performance.
Maximum size of internal CDF buffer
10MB
The maximum size of data

stored in memory before it is
written to disk.
Maximum size of tag name
1KB (default)

1MB.
performance.
28
Introduction
Table 9
Content specifications (page 2 of 2)

Specification
Value
Note
Maximum size of attribute name
1KB (default)

1MB.
performance.
Maximum size of attribute value
100KB (default)

1MB.
performance.
Maximum number of attributes in a

tag
256 or 100MB,
whichever is larger
Atmos CAS API: The

number of attributes cannot
exceed 256. The maximum is
limited to how many attributes
can fit into 100MB (max CDF
size).
Maximum number of nested tags in

CDF
256 or 100MB,
whichever is larger
Atmos CAS API: The

number of tags cannot
exceed 256. The maximum is
limited to how many nested
tags can fit into 100MB (max
CDF size).
Atmos CAS specifications
29
Introduction
Table 10 on page 30 shows the specifications for SDK operations.

Table 10
30
SDK pool operations

Specification
Value
Maximum number of parallel queries
10
Maximum number of connections to

a pool
999
The default is 100.
Maximum number of SDK-provided

sockets
999
The default is 100.
Stream memory buffer
VALUE > 0
The VALUE must be greater

than 0, where VALUE is the
OS minimum and is
application-specified.
Maximum prefetch buffer
1MB
Note
Invible Body Tag
Pool Functions
This chapter describes the FPPool API functions.

The main section in this chapter is:
Pool functions ..................................................................................... 32
Pool Functions
31
Pool Functions
Pool functions
The application must establish a connection to the pool before
performing a pool operation, with the exception of
FPPool_SetGlobalOption() and FPPool_GetComponentVersion().
The application should provide one or more addresses of the
CAS-enabled nodes to make a connection to a pool.
The pool functions are thread safe.
Note: You should close the connection to a pool if that connection is no longer
needed, in order to free all used resources. However, it is better to reuse
existing pool connections than to frequently open and close connections.
Here is the list of SDK pool functions:
32
FPPool_Close
FPPool_GetClipID
FPPool_GetIntOption
FPPool_GetLastError
FPPool_GetLastErrorInfo
FPPool_GetPoolInfo
FPPool_GetRetentionClassContext
FPPool_Open
FPPool_SetClipID
FPPool_SetIntOption
Pool Functions
FPPool_Close
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPPool_Close (const FPPoolRef inPool)

void
const FPPoolRef inPool
This function is thread safe.

This function closes the connection to the given pool and frees
resources associated with the connection. Note that calling this
function on pool that is already closed may produce unwanted
results.
Note: Be sure to close all pool connections that are no longer needed in order
to avoid performance loss and resource leakage. However, it is better to reuse
existing pool connections than to frequently open and close connections.
Parameters
The reference to a pool opened by FPPool_Open().

Example
Error handling
FPPool_Close (myPool);
FPPool_GetLastError() returns ENOERR if successful. If
unsuccessful, the following is a partial list of possible errors:
FP_WRONG_REFERENCE_ERR (program logic error)

FP_OBJECTINUSE_ERR (client error)
Pool functions
33
Pool Functions
Syntax
Return value
FPPool_GetCapability (const FPPoolRef inPool, const char

*inCapabilityName, const char
*inCapabilityAttributeName, char *outCapabilityValue,
FPInt *ioCapabilityValueLen)
void
Input parameters
const FPPoolRef inPool, const char *inCapabilityName,

const char *inCapabilityAttributeName, FPInt
*ioCapabilityValueLen
Output parameters
char *outCapabilityValue, FPInt *ioCapabilityValueLen
Concurrency
requirement
Unicode support
This function has variants that support wide character and 8, 16, and
32-bit Unicode. For more information, see Unicode and wide
character support on page 21.
Description
This function returns the attribute value for the given attribute name
of a capability. The capabilities are associated with the access
credentials and refer to the operations that the SDK is allowed to
perform on the CAS-enabled nodes. Refer to the EMC Atmos CAS
Programmers Guide for more information.
Parameters
const char *inCapabilityName
The name of the capability.

Refer to Table 11 on page 35 for the capability names, attribute
names, and attribute values that represent the capabilities.
34
Pool Functions
Table 11
Capability names and attributes (page 1 of 2)
Capability name
Attribute name
Attribute
values
Atmos CAS behavior
FP_BLOBNAMING
FP_SUPPORTED_SCHEMES
MD5/MG
MD5/MG
FP_CLIPENUMERATION
FP_ALLOWED
true/false
True. FPPoolQuery_Open() is
allowed.
FP_POOLS
string
Empty string.
FP_MODE
basic/CE/CE+ Basic only. The compliance mode of

the subtenant using Atmos CAS.
FP_EVENT_BASED_RETENTION
FP_RETENTION_HOLD
FP_RETENTION_MIN_MAX
supported/
unsupported
Unsupported.
FP_ALLOWED
true/false
True. If true, FPClip_Delete()

and FPClip_AuditedDelete()
are allowed.
FP_POOLS
string
Empty string.
FP_DELETIONLOGGING
FP_SUPPORTED
true/false
True. If true, the server creates

reflections when deleting C-Clips.
FP_EXIST
FP_ALLOWED
true/false
True. If true, FPClip_Exists()

and FPTag_BlobExists() are
allowed.
FP_POOLS
string
Empty string.
FP_MONITOR
FP_ALLOWED
true/false
False.
FP_POOL_POOLMAPPINGS
FP_POOLS
string
Empty string.
FP_COMPLIANCE
FP_DELETE
Empty string.
FP_PROFILES
FP_PRIVILEGEDDELETE
FP_PURGE
FP_READ
FP_ALLOWED
true/false
False.
FP_POOLS
string
Empty string.
FP_ALLOWED
true/false
False. Deprecated.
FP_POOLS
string
Empty string.
FP_ALLOWED
true/false
True. If true, FPClip_Open() and

FPTag_BlobRead() (Partial)
are allowed.
Pool functions
35
Pool Functions
Table 11
Capability name
FP_RETENTION
Capability names and attributes (page 2 of 2)
Attribute name
Attribute
values
Atmos CAS behavior
FP_POOLS
string
Empty string.
FP_DEFAULT
integer
FP_FIXED_RETENTION_MIN
64-bit integer
FP_FIXED_RETENTION_MAX
-1
FP_VARIABLE_RETENTION_MIN
FP_VARIABLE_RETENTION_MAX
-1
Note: Retention is not supported in
this release.
FP_RETENTION_HOLD
FP_WRITE
FP_ALLOWED
true/false
False.
FP_POOLS
string
Empty string.
FP_ALLOWED
true/false
True. If true, FPClip_Write() and

FPTag_BlobWrite() are allowed.
FP_POOLS
string
Empty string.
const char *inCapabilityAttributeName
The name of the capability attribute.
char *outCapabilityValue
outCapabilityValue is the memory buffer that receives the
value of the capability upon successful completion of the

function.
FPInt *ioCapabilityValueLen
Input: The reserved length, in characters, of the

outCapabilityValue buffer.
Output: The actual length of the string, in characters, including
the end-of-string character.
Example
Check if the SDK is allowed to perform a privileged delete operation:

char vCapability[256];
FPInt vCapabilityLen = sizeof (vCapability);
FPPool_GetCapability(vPool, FP_PRIVILEGEDDELETE,
FP_ALLOWED, vCapability, &vCapabilityLen);
if (strcmp(vCapability,FP_TRUE) == 0) { ... }
36
Pool Functions
Error handling


FP_PARAM_ERR (program logic error)
FP_ATTR_NOT_FOUND_ERR (program logic error)
FPPool_GetClipID
Syntax
Return value
Parameters
void FPPool_GetClipID (const FPPoolRef inPool,

FPClipID outContentAddress)
void
The reference to a pool that has been opened by a call to the

FPPool_Open function.
const FPClipID outContentAddress
The buffer that receives the ID of the subtenant and UID pair.
Description
The FPPool_GetClipID function retrieves the C- Clip ID associated

with a subtenant and UID pair, and places it in the buffer specified by
the outContentAddress parameter.
A subtenant and UID pair contains information about the identity of
a client application and determines the operations that the client
application can perform on the CAS-enabled node. For more
information on the subtenant and UID pair, see the EMC Atmos CAS
Programmers Guide.
Note: A subtenant and UID pair can be associated with only one C-Clip ID.
Example
Error handling
For an example of how to call this routine, see the manpage for Clip
functions on page 60.
The FPPool_GetClipID function returns ENOERR if successful or
the following error codes:

FP_SDK_INTERNAL_ERR (program logic error)
Pool functions
37
Pool Functions
Note: This call fails from the SDK side if the specified subtenant and UID pair
was not previously opened, if the C-Clip ID associated with the subtenant
and UID pair was not previously set by a call to FPPool_SetClipID, or if
the C-Clip ID was deleted.
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Description
FPPool_GetClusterTime (const FPPoolRef inPool, char

*outClusterTime, FPInt *ioClusterTimeLen)
void
const FPPoolRef inPool, FPInt *ioClusterTimeLen
char *outClusterTime, FPInt *ioClusterTimeLen

This function retrieves the current cluster time. The time is specified
in UTC (Coordinated Universal Time, also known as GMT
Greenwich Mean Time).
For example, February 21, 2004 is expressed as: 2004.02.21
10:46:32 GMT.
Parameters
char *outClusterTime
outClusterTime is the memory buffer that will store the cluster
time. The time is specified in YYYY.MM.DD hh:mm:ss GMT
format.
FPInt *ioClusterTimeLen
Input: The reserved length, in characters, of the outClusterTime

buffer.
Example
38
char vClusterTime[256];
FPInt vClusterTimeLen=256;
FPPool_GetClusterTime(vPool, vClusterTime,
&vClusterTimeLen);
Pool Functions
Error handling


Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPPool_GetComponentVersion (const FPInt inComponent, char

*outVersion, FPInt *ioVersionLen)
void
const FPInt inComponent, FPInt *ioVersionLen
char *outVersion, FPInt *ioVersionLen
Description
This function retrieves the version of SDK components that are

currently in use.
Parameters
const FPInt inComponent

inComponent refers to the component queried for its version. Use
one of the following values:

FP_VERSION_FPLIBRARY_DLL
FP_VERSION_FPLIBRARY_JAR (Java only)
char *outVersion
outVersion is the memory buffer that will store the version
number.
FPInt *ioVersionLen
Input: The reserved length, in characters, of the outVersion

buffer.
Example
char vVersion[128];
Pool functions
39
Pool Functions
FPInt vVersionLen=128;
FPPool_GetComponentVersion(FP_VERSION_FPLIBRARY_DLL,
vVersion, &vVersionLen);
Error handling

FP_UNKNOWN_OPTION (program logic error)

Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPPool_GetGlobalOption (const char *inOptionName)

FPInt
const char *inOptionName
This function returns the value of inOptionName that is set by
FPPool_SetGlobalOption().
Parameters
Refer to FPPool_SetGlobalOption on page 54 for the option names

and their possible values.
Example
Error handling
40
FPPool_GetGlobalOption(FP_OPTION_RETRYCOUNT);
unsuccessful, the SDK may return FP_UNKNOWN_OPTION (program
logic error).
Pool Functions
FPPool_GetIntOption
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPPool_GetIntOption (const FPPoolRef inPool, const char

*inOptionName)
FPInt
const FPPoolRef, const char *inOptionName
This function returns the value of inOptionName that is set by
FPPool_SetIntOption().
Parameters
Refer to FPPool_SetClipID on page 51 for the option names and

their possible values.
Example
Error handling
FPPool_GetIntOption(myPool,
FP_OPTION_ENABLE_MULTICLUSTER_FAILOVER);
FP_POOLCLOSED_ERR (program logic error)

Pool functions
41
Pool Functions
FPPool_GetLastError
Syntax
Return value
Concurrency
requirement
Description
FPPool_GetLastError (void)
FPInt

This function returns the error status of the last FPLibrary function
call on the same thread and returns the error number. It is
recommended that your application check the error status after each
function call. Error codes on page 284 contains a complete list of
FPLibrary-specific errors. If no error was generated, the return value
is ENOERR (zero).
Call FPPool_GetLastErrorInfo() to retrieve additional information
about the error.
Note: If the SDK is unable to return the error status of the last FPLibrary
function call, the return value is FP_UNABLE_TO_GET_LAST_ERROR. This
value indicates that an error was generated by the
FPPool_GetLastError() call itself and not the previous function call. The
error status of the previous function call is unknown and may have
succeeded.
Parameters
Example
void
FPInt errorCode;
errorCode = FPPool_GetLastError();
if (errorCode != ENOERR)
{
/* Process the error ... */
}
42
Pool Functions
FPPool_GetLastErrorInfo
Syntax
Return value
Output parameters
Concurrency
requirement
Description
FPPool_GetLastErrorInfo (FPErrorInfo *outErrorInfo)

void
FPErrorInfo *outErrorInfo

This function retrieves the error status of the last FPLibrary function
call and returns information about the error in the FPErrorInfo
structure. The error can be FPLibrary-specific or OS-specific. Refer to
Table 6 on page 26 for details of the FPErrorInfo structure.
If no errors are generated, the returned structure has null values in
its data fields.
Note: Do not modify the contents of the outErrorInfo structure. Do not
deallocate the string member variables.
Parameters
FPErrorInfo *outErrorInfo
The structure that will store the error information that the function
retrieves. Refer to Table 6 on page 26 for details of the FPErrorInfo
structure. If no errors are generated, the returned structure has null
values in its data fields.
Example
FPInt errorCode;
FPErrorInfo errInfo;
errorCode = FPPool_GetLastError();
if (errorCode != ENOERR)
{
FPPool_GetLastErrorInfo(&errInfo);
/* Process the Error ...*/
}
Pool functions
43
Pool Functions
FPPool_GetPoolInfo
Syntax
Return value
Input parameters
FPPool_GetPoolInfo (const FPPoolRef inPool, FPPoolInfo

*outPoolInfo)
void
Output parameters
FPPoolInfo *outPoolInfo
Concurrency
requirement
Description
This function retrieves information about the current CAS-enabled

nodes and saves it into outPoolInfo.
Parameters
FPPoolInfo *outPoolInfo
The structure that will store the pool information that the
function retrieves. The structure is defined as follows:
poolInfoVersion [FPInt]: The current version of this
information structure.
capacity [FPLong]: The total usable capacity (in bytes) of all
online nodes in the current CAS-enabled nodes.
freeSpace [FPLong]: The total free space (in bytes) in the
current CAS-enabled nodes.
Note: This function returns an approximate value for the free space. The
returned values can vary within 2% when compared to subsequent calls of
the function. The free space reflects the total amount of usable space on all
online nodes to store data mirrored.
clusterID [string]: The cluster identifier of the current

cluster (maximum of 128 characters).
clusterName [string]: The cluster name of the current
cluster (maximum of 128 characters).
version [string]: The version of the CentraStar software on
the current cluster (maximum of 128 characters).
44
Pool Functions
replicaAddress [string]: A comma-separated list of the

replica access node addresses as specified when replication
was configured. The maximum number of characters is 256.
The string is empty if replication is not configured.
Example
Error handling
FPPoolInfo PoolInfo;
FPPool_GetPoolInfo(myPool, &PoolInfo);

FP_VERSION_ERR (internal error)
FP_NO_POOL_ERR (network error)
FP_NO_SOCKET_AVAIL_ERR (network error)
FP_PROTOCOL_ERR (internal error)
FP_PROBEPACKET_ERR (internal error)
FP_SERVER_ERR (server error)
FP_CONTROLFIELD_ERR (server error)
FP_SERVER_NOT_READY_ERR (server error)
Pool functions
45
Pool Functions
FPPool_GetRetentionClassContext
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPPool_GetRetentionClassContext (const FPPoolRef

inPoolRef)
FPRetentionClassContextRef
const FPPoolRef inPoolRef

This function returns a valid retention class contextthe set of all
defined retention classesfor the CAS-enabled node(s) of the given
pool. However, because Atmos CAS does not provide the ability to
create retention classes, the list is empty. This function returns NULL
and sets the FP_SERVER_ERR error status if the CAS-enabled node
does not support retention classes.
Use the FPRetentionClassContext_xxx() functions to retrieve
individual classes from the retention class context.
Call FPRetentionClassContext_Close() when you no longer need
the FPRetentionClassContextRef object to free all associated
(memory) resources.
Parameters

Example
Error handling
FPRetentionClassContextRef myRetClassContext;
myRetClassContext = FPPool_GetRetentionClassContext
(myPool);

FP_OUT_MEMORY_ERR
Additional server errors
46
Pool Functions
FPPool_Open
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPPool_Open (const char *inPoolAddress)

FPPoolRef
const char *inPoolAddress
This function initiates connections to one or more CAS-enabled
nodes. The pool object manages these connections. This function
returns a reference to the opened pool.
The pool address (inPoolAddress) is a comma-separated string of IP
addresses or DNS names of CAS-enabled nodes. The pool probes all
addresses in this connection string either immediately (normal
strategy, the default) or on an as-needed basis (lazy strategy). Refer to
Pool Open Strategy in the EMC Atmos CAS Programmers Guide for
more information. You can change the default open strategy; refer to
FPPool_SetGlobalOption on page 54.
Note: If the SDK cannot connect to one or more CAS-enabled nodeswhen
the connection string includes an inaccessible node, or when a node has been
configured to replicate to an inaccessible nodethe FPPool_Open() call
will take at least 1 minute to complete.
You can globally specify how many connections can be made to a

pool by calling FPPool_SetGlobalOption(). The default value is 100
and the maximum value is 999. Refer to Connection Pooling in the
EMC Atmos CAS Programmers Guide for more information.
To free associated resources, be sure to close all pool connections
FPPool_Close on page 33 that are no longer needed.
Parameters
const char *inPoolAddress

inPoolAddress is a comma-separated string containing one or more
addresses of the available nodes with the access role of the pool. The
format is:
Pool functions
47
Pool Functions
pooladdress ::= hintlist

hintlist ::= hint ("," hint)*
hint ::= [ protocol "://" ] ipreference [ ":" port ]
protocol ::= "hpp"
port ::= [0-9]+ (default is 3218)
ipreference ::= dnsname | ip-address
dnsname ::= DNS name is a DNS maintained name that
resolves to one or more IP addresses (using
round-robin) max length is 256 chars
ip-address ::= 4-tuple address format
A hint is a single pool address and a hintlist contains one or more

hints.
Profile information
You can augment the connection string with the PEA file or
username/secret for the PAI module to be used by the application.
For example:
"10.2.3.4,10.6.7.8?c:\centera\rwe.pea"
or
"10.2.3.4,10.6.7.8?name=<username>,secret=<password>"
You also can assign multiple profiles on a connection string to access

one or more CAS-enabled nodes. For more information on PAI
modules and the syntax of connection strings, refer to the EMC Atmos
CAS Programmers Guide.
Connection failover prefixes
Addresses prefixed with primary=, called primary addresses, are
eligible for becoming the primary CAS-enabled node. Addresses
prefixed with secondary=, called secondary addresses, are not
eligible for becoming the primary CAS-enabled node. An address
without a prefix is a primary address.
For example:
"10.2.3.4,primary=10.6.7.8,secondary=10.11.12.13"
Both 10.2.3.4 and 10.6.7.8 are primary addresses, and 10.11.12.13 is a

secondary address.
If all primary connections for CAS-enabled nodes fail, the
FPPool_Open() function fails. The primary= and secondary=
prefixes are case-sensitive, and there can be no whitespace before or
after the equal sign (=).
48
Pool Functions
Example
This example specifies a connection string with multiple IP

addressesa best practice that protects against one or more
CAS-enabled nodes being unavailable.
myPool = FPPool_Open
("10.1.1.1,10.1.1.2,10.1.1.3,10.1.1.4");
This example opens a pool using the specified PEA file.

myPoolName = "10.62.69.153?c:\centera\rwe.pea";
myPool = FPPool_Open (myPoolName);
Error handling


FP_ACCESSNODE_ERR (network error)
FP_AUTHENTICATION_FAILED_ERR (server error)
Pool functions
49
Pool Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPPool_RegisterApplication (const char* inAppName,

const char* inAppVer)
void
const char* inAppName, const char* inAppVer
Unicode support
Description
This function stores an applications name and version on the Atmos

CAS log. This API call allows for improvements in the application
and customer support of integrated applications.
Note: To ensure that this application information is written to an Atmos CAS
log, you must call FPPool_RegisterApplication before calling
FPPool_Open().
Note: Using FPPool_RegisterApplication overrides the option settings

set as environment variables.
Parameters
const char* inAppName

inAppName is a string with the name of the application.
const char* inAppVer

inAppVer is a string with the application version.
Example
FPPool_RegisterApplication (inAppName, inAppVer);
Error handling

50

Pool Functions
FPPool_SetClipID
Syntax
Return value
Parameters
void FPPool_SetClipID (const FPPoolRef inPool, const

FPClipID inContentAddress);
void
Reference to a pool that has been opened by a call to the

FPPool_Open function.
const FPClipID inContentAddress
The C-Clip ID to be associated with the subtenant and UID pair.

This is the Content Address returned by a prior call to
FPClip_Create.
Description
The FPPool_SetClipID function sets the C-Clip ID for the UID

associated with a specific subtenant.
Before you call FPPool_SetClipID, you must first successfully
create a C-Clip with the FPClip_Create function and write the clip
to disk with a call to FPClip_Write.
This C-Clip ID is a Content Address that is associated with the
subtenant and UID pair.
The subtenant and UID pair contains information about the identity
of a client application and determines the operations that the client
application can perform on one or more CAS-enabled nodes. For
more information on the subtenant and UID pair, see the EMC Atmos
CAS Programmers Guide.
Note: A subtenant and UID pair can be associated with only one C-Clip ID.
Pool functions
51
Pool Functions
Example
FPClipID vID1;
FPClipID vID2;
FPPoolRef myPool = FPPool_Open("10.241.35.101");
// Create clip
FPClipRef vClipRef = FPClip_Create(myPool, "Test");
FPInt vRetVal = print_last_error();
if ( vRetVal == 0 && vClipRef )
{
//Write the clip with no data
FPClip_Write(vClipRef, vID1);
vRetVal = print_last_error();
if (vRetVal == 0)
{
//Set this clip as the profile clip
FPPool_SetClipID(myPool, vID1);
if (vRetVal == 0)
{
//Close this clip
FPClip_Close(vClipRef);
if (vRetVal == 0)
{
//Get the profile clip CA
FPPool_GetClipID(myPool, vID2);
}
}
}
}
52
Pool Functions
Error handling
The FPPool_SetClipID function returns ENOERR if successful or

the following error codes:
Note: This call fails from the SDK side if the specified subtenant and UID pair
was not previously opened, if the C-Clip ID associated with the subtenant
and UID pair was not specified, or if the C-Clip ID is not a viable Content
Address.

FP_PROFILECLIPID_NOTFOUND_ERR (server error)
FP_OPERATION_NOT_ALLOWED (client error)
FP_PACKET_FIELD_MISSING_ERR (internal error)
FP_SERVER_NOT_READY_ERR (server error)
FP_UNKNOWN_AUTH_SCHEME_ERR (server error)
FP_UNKNOWN_AUTH_PROTOCOL_ERR (server error)
FP_AUTHENTICATION_FAILED_ERR (server error)
FP_TRANSACTION_FAILED_ERR (server error)
FP_PROFILECLIPID_WRITE_ERR (client error)
Pool functions
53
Pool Functions
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPPool_SetGlobalOption (const char *inOptionName, const

FPInt inOptionValue)
void
const char *inOptionName, const FPInt inOptionValue
This function sets application-wide options. When set, the new
values take effect immediately including all running threads of the
application. However, it does not affect other applications using the
same FPLibrary.
Note: You can set any global pool option as an environment variable. The
option settings that an application sets take precedence and override those
that were previously set as environment variables.
Parameters

inOptionName is a string with the name of the option to be set.
Note: For available options and values, see Global options on page 55.
Example
const FPInt inOptionValue

inOptionValue is the value for the given option.
RetryCount = 5;
FPPool_SetGlobalOption (FP_OPTION_RETRYCOUNT,
RetryCount);
FPPool_SetGlobalOption (FP_OPTION_OPENSTRATEGY,
FP_LAZY_OPEN);
Error handling

54
Pool Functions
Global options

FP_OUT_OF_BOUNDS_ERR (program logic error)
You can set any of the following global options:
FP_OPTION_CLUSTER_NON_AVAIL_TIME The time in seconds
that one or more CAS-enabled nodes is marked as not available

before retrying with a probe. Other CAS-enabled nodes in the
pool will be used while the CAS-enabled node is unavailable. The
default value is 600 (10 minutes). The minimum is 0. The
maximum is 36000 (10 hours).
FP_OPTION_DISABLE_CLIENT_STREAMING Disables the

CLIENT_CALCID_STREAMING mode and converts it to the
SERVER_CALCID_STREAMING mode, which allows only the Atmos
CAS server (not the client) to calculate the content address of the
blob data on the server.
FP_OPTION_ENABLE_DUPLICATE_DETECTION Enables the SDK
to detect whether a duplicate blob with the same content address

exists in the CAS-enabled node.
FP_OPTION_EMBEDDED_DATA_THRESHOLD The 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.
Embedding data in the CDF can improve write performance.
However, embedded data does not benefit from single-instance
storage. Refer to the EMC Atmos CAS Programmers Guide for more
information.
When the data size is unknown (for example, when using
FP_OPTION_CLIENT_CALCID_STREAMING and the data size
exceeds the prefetch buffer), data is not embedded in the CDF
regardless of the threshold.
You can explicitly control data embedding, which overrides this
threshold setting, when you call FPTag_BlobWrite().
FP_OPTION_MAXCONNECTIONS The maximum number of
sockets that the SDK will allocate for your application. Sockets
are used to communicate with the Atmos CAS nodes managed in
each pool object. The default value is 100. The maximum value is
999.
Pool functions
55
Pool Functions
FP_OPTION_OPENSTRATEGY The approach used by

FPPool_Open() to open connections to addresses in the
connection string. Choices are:

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.
Refer to FPPool_Close on page 33 and the EMC Atmos CAS
Programmers Guide for more information.
FP_OPTION_PROBE_LIMIT The threshold for how long an
application probe is allowed to attempt communication with a

CAS-enabled access node. The maximum threshold is 60 seconds
(1 minute). If a probe exceeds the limit, the SDK returns an error.
FP_OPTION_RETRYCOUNT The 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.
If you do not want functions to retry automatically, set the retry
count to 0.
Note: Refer to the EMC Atmos CAS Programmers Guide for more
information on the retry mechanism.
FP_OPTION_RETRYSLEEP The 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.
56
Pool Functions
FPPool_SetIntOption
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPPool_SetIntOption (const FPPoolRef inPool, const char

*inOptionName, const FPInt inOptionValue)
void
const FPPoolRef inPool, const char *inOptionName, const
FPInt inOptionValue
This function sets the options for the given pool. To change global
pool settings, refer to FPPool_SetGlobalOption on page 54.
Use the FPPool_Open() function to open and set the options for that
pool.
Note: You can set global pool options as environment variables. The option
settings made by an application take precedence and override those that
were previously set as environment variables.
Parameters

inOptionName is a string with the name of the option to be set.
The following initial pool options can be set:

FP_OPTION_BUFFERSIZE The size of an internal C-Clip
buffer in bytes. The default value is 16*1024. This value must
be greater than 0.
FP_OPTION_TIMEOUT The TCP/IP connection timeout in
milliseconds. The default value is 120000 ms (2 minutes). The
maximum value is 600000 ms (10 minutes).
FP_OPTION_ENABLE_MULTICLUSTER_FAILOVER When this
option is true (the default), multicluster failover is enabled.
You can define the failover behavior for each capability using
Pool functions
57
Pool Functions
FPPool_SetGlobalOption() (refer to page 2-54). By default

this option is true (1). To turn multicluster failover off for all
capabilities, specify false (0).
FP_OPTION_DEFAULT_COLLISION_AVOIDANCE This 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 Atmos CAS Programmers 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, refer
to FPTag_BlobExists on page 148.
FP_OPTION_PREFETCH_SIZE The 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.
Example
Error handling
BufferSize = 32*1024;
FPPool_SetIntOption (myPool, FP_OPTION_BUFFERSIZE,
BufferSize);
FPPool_SetIntOption (myPool,
FP_OPTION_DEFAULT_COLLISION_AVOIDANCE, true);
58
const FPInt inOptionValue

inOptionValue is the value for the given option.

Invible Body Tag
Clip Functions
This chapter describes the various types of FPClip functions.

Clip functions ..................................................................................... 60

Clip handling functions .................................................................... 60
Clip info functions ............................................................................. 84
Clip attribute functions ................................................................... 102
Clip tag functions............................................................................. 110
Clip Functions
59
Clip Functions
Clip functions
The clip functions are a set of function calls that operate on C-Clips. A
clip function can manipulate an entire C-Clip, retrieve information
about a C-Clip, manipulate clip attributes, or manipulate a single tag
from a C-Clip. Therefore the four groups of clip functions are:
Clip handling
Clip info
Clip attribute
Clip tag
The C-Clip must be open before you can perform a clip function (do
not forget to close the C-Clip when finished).
C-Clips can be shared by multiple threads. Several threads can
perform blob and tag operations within a C-Clip simultaneously.
Clip handling functions

This section describes the FPClip functions that manipulate a C-Clip
or C-Clip ID:
60
FPClip_Close
FPClip_Create
FPClip_Delete
FPClip_EnableEBRWithClass
FPClip_EnableEBRWithPeriod
FPClip_Open
FPClip_RawOpen
FPClip_RawRead
FPClip_RemoveRetentionClass
FPClip_SetName
FPClip_SetRetentionClass
FPClip_SetRetentionPeriod
FPClip_TriggerEBREvent
FPClip_TriggerEBREventWithClass
FPClip_TriggerEBREventWithPeriod
FPClip_Write
FPClipID_GetCanonicalFormat
FPClipID_GetStringFormat
Clip Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_AuditedDelete (const FPPoolRef inPool, const

FPClipID inClipID, const char *inReason, const FPLong
inOptions)
void
const FPPoolRef inPool, const FPClipID inClipID, const
char *inReason, const FPLong inOptions)
Unicode support
Description
This function deletes the given CDF from the first CAS-enabled node
of a given pool and records audit information describing the reason
for the deletion.
Note: In Atmos CAS, the privileged deletion option generates the
FP_OPERATION_NOT_ALLOWED error.
The delete operation succeeds only if:
The "delete" capability is enabled, or in the case of a privileged

deletion, the "privileged-delete" capability is enabled. Refer to
FPPool_GetCapability on page 34 for information on the server
capabilities. The function returns FP_OPERATION_NOT_ALLOWED if
the required profile capability is false.
The retention period of the C-Clip has expired, or you have

requested and the profile capability allows privileged deletion.
Refer to FPClip_SetRetentionPeriod on page 77 and
FPClip_SetRetentionClass on page 76 for information on
retention periods. The function returns
FP_OPERATION_NOT_ALLOWED if the retention period has not
expired, or you requested but do not have permission for a
privileged deletion.
All copies of the CDF have been successfully removed.
61
Clip Functions
Note that this function does not delete associated blobs. Garbage
collection automatically deletes blobs that are no longer referenced by
any C-Clip. Refer to the EMC Atmos CAS Programmers Guide for more
information on deleting data.
Deleting a C-Clip leaves a reflectionmetadata about the deleted
C-Clipon the CAS-enabled node. Reflections are only exposed in
the SDK through the query functions. Refer to Query functions on
page 216. The audit string, if specified, is recorded in the reflection.
Parameters
const FPClipID inClipID
The ID of a C-Clip.
const char *inReason
The reason for the delete operation, which is recorded as an audit

string in the reflection. Specify NULL if you do not want to record
an audit string. An audit string is required for privileged
deletions. The string must be smaller than 16 KB.
const FPLong inOptions
Specify one of the following options:

FP_OPTION_DEFAULT_OPTIONS Specify this option if you are
not performing a privileged deletion.
FP_OPTION_DELETE_PRIVILEGED Delete the C-Clip even if
the retention period has not expired. You must specify an
inReason string when performing a privileged deletion.
Note: This unsupported option in Atmos CAS generates the
FP_OPERATION_NOT_ALLOWED error.
Example
Error handling
FPClip_AuditedDelete (myPool, myClipID, "Employee has

left the company.", FP_OPTION_DELETE_PRIVILEGED);
62

Clip Functions

FP_NUMLOC_FIELD_ERR (server error)
FP_UNKNOWN_OPTION (internal error)
FP_CLIP_NOT_FOUND_ERR (program logic error)
FP_NOT_RECEIVE_REPLY_ERR (network error)
FP_SEGDATA_ERR (internal error)
FP_SERVER_NOTREADY_ERR (server error)
FP_BLOBBUSY_ERR (server error)
63
Clip Functions
FPClip_Close
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_Close (const FPClipRef inClip)

void
const FPClipRef inClip
This function requires exclusive access to the C-Clip reference.

This function closes the given C-Clip and frees up all memory
allocated to the C-Clip. Note that calling this function on a C-Clip
that has already been closed may produce unwanted results.
Note: If you close a C-Clip before calling FPClip_Write(), then any
modifications to the C-Clip will be lost.
Parameters
The reference to a C-Clip that was opened by FPClip_Open() or

FPClip_Create().
Example
Error handling
FPClip_Close (myClip);
64

FP_OBJECTINUSE_ERR (client error)
Clip Functions
FPClip_Create
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPClip_Create (const FPPoolRef inPool, const char

*inName)
FPClipRef
const FPPoolRef inPool, const char *inName
This function creates a new, empty C-Clip in memory. This function
returns a reference to the in-memory C-Clip.
During the execution of FPClip_Create(), the SDK looks for the
environment variable CENTERA_CUSTOM_METADATA. This variable may
contain a comma-separated list of environment variables that will be
added to the CDF during FPClip_Write(). The number of metadata
items is limited by memory (100 MB). The metadata can be retrieved
using FPClip_GetDescriptionAttribute(). No error is reported if
the function cannot access a metadata item.
For example, if the CENTERA_CUSTOM_METADATA variable is defined as:
CENTERA_CUSTOM_METADATA=USER,APPLICATION,HOSTNAME
and the referenced environment variables are defined as:

USER=Doe
APPLICATION=RWE Exerciser
HOSTNAME=QA Test 15
then the SDK adds the following information to the CDF:

<custom-meta name="USER" value="Doe">
<custom-meta name="APPLICATION" value="RWE Exerciser">
<custom-meta name="HOSTNAME" value="QA Test 15">
65
Clip Functions
Parameters
Example
Error handling
myClip = FPClip_Create (myPool, "anotherclip");

66
const char *inName

inName is a string holding the name of the C-Clip. If inName is
NULL, the name of the C-Clip is untitled.

FP_SECTION_NOT_FOUND_ERR (internal error)
FP_TAGTREE_ERR (internal error)
FP_TAG_NOT_FOUND_ERR (internal error)
Clip Functions
FPClip_Delete
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_Delete (const FPPoolRef inPool, const FPClipID

inClipID)
void
const FPPoolRef inPool, const FPClipID inClipID

This function deletes the CDF for the specified Clip ID from the first
writable CAS-enabled node of a given pool if the retention period of
the C-Clip has expired and if the server capability "delete" is enabled.
Refer to FPPool_GetCapability on page 34 for more information on
the server capabilities, and to FPClip_SetRetentionPeriod on
page 77 and FPClip_SetRetentionClass on page 76 for more
information on retention periods.
To specify a reason for the deletion (an audit string) or to delete a
C-Clip before the retention period has expired, refer to
FPClip_AuditedDelete on page 61.
A C-Clip is deleted only when all copies of the CDF have been
successfully removed.
This function returns FP_OPERATION_NOT_ALLOWED if the retention
period has not yet expired or if the "delete" capability is disabled. In
that case, the CDF is not deleted.
Note that this function does not itself delete associated blobs.
Garbage collection automatically deletes blobs that are no longer
referenced by any C-Clip. Refer to the EMC Atmos CAS Programmers
Guide for more information on deleting data.
Note: The server allows the application to perform this call if the server
capability "delete" is enabled. It is imperative that your application
documentation contains server configuration details based on the EMC
Atmos CAS online help.
Deleting a C-Clip leaves a reflectionmetadata about the deleted

C-Clipon the CAS-enabled node. Reflections are only exposed in
the SDK through the query functions. Refer to Query functions on
page 216.
67
Clip Functions
Parameters
The ID of a C-Clip.
Example
Error handling
FPClip_Delete (myPool, myClipID);

68

Clip Functions
FPClip_EnableEBRWithClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_EnableEBRWithClass (const FPClipRef inClip,

const FPRetentionClassRef inClass)
void
const FPClipRef inClip, const FPRetentionClassRef inClass
This function requires exclusive access to the C-Clip reference in

memory.
Description
This function is unsupported in Atmos CAS. If used, this function

generates the FP_ADVANCED_RETENTION_DISABLED error.
Parameters

FPClip_Create().
const FPRetentionClassRef inClass
The reference to the retention class used to indirectly set the wait
period of the C-Clip.
FPClip_EnableEBRWithPeriod
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_EnableEBRWithPeriod (const FPClipRef inClip,

FPLong inSeconds)
void
const FPClipRef inClip, FPLong inSeconds

memory.
Description

Parameters

FPClip_Create().
FPLong inSeconds
69
Clip Functions
The retention period (in seconds) that is to be measured from

when the triggering event occurs.
FPClip_Open
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_Open (const FPPoolRef inPool, const FPClipID

inClipID, const FPInt inOpenMode)
FPClipRef
FPInt inOpenMode

With FPClip_Open(), you can open a stored C-Clip as a tree structure
or as a flat structure. This function reads the CDF into the memory of
the application server and returns a reference to the opened C-Clip.
The server allows the application to perform this call if the server
capability "read" is enabled. If this capability is disabled, the error
FP_OPERATION_NOT_ALLOWED is returned. Refer to
FPPool_GetCapability on page 34 for more information on server
capabilities. It is imperative that your application documentation
contains server configuration details based on the EMC Atmos CAS
online help.
Note: This function keeps the C-Clip data in a memory buffer of which the
size has been specified with FPPool_SetIntOption(buffersize). Any
overflow is temporarily stored on disk.
70
Clip Functions
Parameters

The C-Clip ID returned by FPClip_Write.()
const FPInt inOpenMode
The method of opening a C-Clip. Choices are:

FP_OPEN_ASTREE Opens the C-Clip as a tree structure in
read/write mode and enables hierarchical navigation through
the C-Clip tags. Refer to FPClip_GetTopTag on page 111 for
more information.
FP_OPEN_FLAT Opens the C-Clip as a flat structure in readonly mode and enables sequential access within the C-Clip.
This option is optimal for opening C-Clips that do not fit in
memory. Refer to FPClip_GetTopTag on page 111 for more
information.
Example
Error handling
myClip = FPClip_Open (myPool, myClipID, FP_OPEN_ASTREE);

FP_UNKNOWN_OPTION (program logic error or internal error; verify
FP_PARAM_ERR (program logic error or internal error; verify your
your code before contacting the EMC Customer Support Center)
code before contacting the EMC Customer Support Center)

FP_BLOBIDMISMATCH_ERR (server error)
71
Clip Functions
FPClip_RawOpen
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_RawOpen (const FPPoolRef inPool, const FPClipID

inClipID, const FPStreamRef inStream, const FPLong
inOptions)
FPClipRef
FPStreamRef inStream, const FPLong inOptions

This function reads the content of inStream and creates a new
in-memory C-Clip. The new C-Clip ID must match the given C-Clip
ID.
If the Storage Strategy Performance scheme is used to create the new
C-Clip, this function returns FP_OPERATION_NOT_ALLOWED
when used against C-Clips from an Atmos CAS prior to version 2.1.
When the C-Clip has been created in memory, the function returns a
reference to that C-Clip. This function returns NULL if no C-Clip has
been built.
Parameters
The C-Clip used to reference the C-Clip that has to be read from
the stream.
const FPStreamRef inStream
The reference to an input stream. Marking support is not

necessary.
Reserved for future use. Specify FP_OPTION_DEFAULT_OPTIONS.

Example
Error handling
NewClip = FPClip_RawOpen (myPool, myClipID, myStream,

FP_OPTION_DEFAULT_OPTIONS);
72
FP_PARAM_ERR (internal error)

Clip Functions

FP_STREAM_ERR (client error)
Stream-related errors (Refer to Stream functions on page 178

for more information.)
FPClip_RawRead
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_RawRead (const FPClipRef inClip, const FPStreamRef

inStream)
void
const FPClipRef inClip, const FPStreamRef inStream
This function requires exclusive access to the C-Clip reference.

This function reads the content of the CDF into inStream. If the
C-Clip has been modified, that is if FPClip_IsModified() returns
true, the function rewrites the tag tree into inStream.
By using this function, the application can store the stream content on
another device for subsequent restore operations of the C-Clip. The
application must not change the stream content as it is the source for
the input stream of FPClip_RawOpen().
Parameters
The reference to a C-Clip returned by FPClip_Open().
The reference to a stream that has been created by an

FPStream_CreateXXX() function or a generic stream for writing.
The stream is not required to support marking.
Example
Error handling
FPClip_RawRead (myClip, myStream);

FP_STREAM_ERR (client error)
Stream-related errors (Refer to Stream functions on page 178

for more information.)
73
Clip Functions
FPClip_RemoveRetentionClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_RemoveRetentionClass (const FPClipRef inClipRef)

void
const FPClipRef inClipRef,
const FPRetentionClassRef inClassRef
Description

Parameters
const FPClipRef inClipRef

FPClip_Create().
74
Clip Functions
FPClip_SetName
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_SetName (const FPClipRef inClip, const char

*inClipName)
void
const FPClipRef inClip, const char *inClipName

memory.
Unicode support
Description
This function changes the name of the given C-Clip to the name given
in inClipName.
Parameters
The reference to a C-Clip opened by FPClip_Open() or

FPClip_Create().
Example
Error handling
const char *inClipName

inClipName is a string holding the new name of the C-Clip.
FPClip_SetName (myClip, "newclipname");


75
Clip Functions
FPClip_SetRetentionClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_SetRetentionClass (const FPClipRef inClipRef,

const FPRetentionClassRef inClassRef)
void
const FPClipRef inClipRef,
Description

Parameters

FPClip_Create().
FPRetentionClassRef inClassRef
The reference to a retention class as returned by one of the

FPRetentionClassContext_GetXXX() functions.
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
76
FPClip_SetRetentionHold (const FPClipRef inClip,

const FPBool inHoldFlag, const char* inHoldID)
void
const FPClipRef inClip, const FPBool inHoldFlag,
const char* inHoldID

memory.
Description

Parameters
Clip Functions

FPClip_Create().
const FPBool inHoldFlag
The reference to the Boolean value that indicates whether the

hold state of the C-Clip is enabled or disabled.
Note: If inHoldFlag is set to False, it removes the specified retention
hold from the C-Clip.
const char* inHoldID
The reference to the ID that is the name of the hold. The hold ID
may contain up to 64 characters. You can assign multiple holds to
a single C-Clip, up to 100 in total.
FPClip_SetRetentionPeriod
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_SetRetentionPeriod (const FPClipRef inClip, const

FPLong inRetentionSecs)
void
const FPClipRef inClip, const FPLong inRetentionSecs
Description

Parameters

FPClip_Create().
const FPLong inRetentionSecs
The retention period, in seconds, or one of the following values:

FP_NO_RETENTION_PERIOD The C-Clip can be deleted at
any time.
FP_INFINITE_RETENTION_PERIOD The C-Clip can never be
deleted, except possibly by a Privileged Delete operation (refer
to FPClip_AuditedDelete on page 61).
77
Clip Functions
FP_DEFAULT_RETENTION_PERIOD The retention period is

based on the mode of the cluster that manages the C-Clip. For
a Compliance Edition Plus model, the default retention period
is infinite. For a Governance Edition model, the default is no
retention period or as defined by the system administrator.
FPClip_TriggerEBREvent
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_TriggerEBREvent (const FPClipRef inClip)

void

memory.
Description

Parameters
FPClipRef inClip

FPClip_Create().
FPClip_TriggerEBREventWithClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_TriggerEBREventWithClass (const FPClipRef inClip,

const FPRetentionClassRef inClass)
void
const FPClipRef inClip, const FPRetentionClassRef inClass

memory.
Description

Parameters

FPClip_Create().
78
const FPRetentionClassRef inClass
Clip Functions
inClass is a reference to the retention class that indirectly sets

and starts the run time of the retention period from the time this
EBR event (API call) is triggered.
FPClip_TriggerEBREventWithPeriod
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_TriggerEBREventWithPeriod (FPClipRef inClip,

FPLong inSeconds)
void
FPClipRef inClip, FP Long inSeconds

memory.
Description

Parameters
FPClipRef inClip

FPClip_Create().
FPLong inSeconds
inSeconds is a value in seconds that explicitly sets and starts the
run time of the retention period from the time this EBR event (API
call) is triggered.
FPClip_Write
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Description
FPClip_Write (const FPClipRef inClip, FPClipID outClipID)

void
FPClipID outClipID

memory.
This function writes the content of a C-Clip to the pool as a CDF and
returns the C-Clip ID (Content Address). This address is 64 bytes.
79
Clip Functions
If collision avoidance is enabled at pool level, refer to

FPPool_SetClipID on page 51, this function returns:
<C-CLIPID><REFID>
For example:
42L0M726P04T2e7QU2445E81QBK7QU2445E81QBK42L0M726P04T2.
Refer to the EMC Atmos CAS Programmers Guide for more

information on collision avoidance.
If Storage Strategy Performance is enabled on the server, files smaller
than the server-defined threshold (by default 250 KB) will have a
Content Address similar to the one that is created when Collision
Avoidance has been enabled.
The server allows the application to perform this call if the server
capability "write" is enabled. If this capability is disabled, the error
FP_OPERATION_NOT_ALLOWED is returned. This error is also returned
if the C-Clip has been opened in flat mode (read only).
the server capabilities. It is imperative that your application
documentation contains server configuration details based on the .
Note: This function keeps the C-Clip data in a memory buffer of which the
size has been specified with FPPool_SetIntOption(buffersize). Any
overflow is temporarily stored on disk.
Parameters

FPClip_Create().
FPClipID outClipID
The C-Clip ID that the function returns.

Example
Error handling
FPClip_Write (myClip, myClipID);

80
FP_ACK_NOT_RCV_ERR (server error)

FP_BLOBIDFIELD_ERR (server error)
FP_DUPLICATE_FILE_ERR (internal error)
Clip Functions

FP_OPERATION_NOT_SUPPORTED (program logic error)
FP_SERVER_NO_CAPACITY_ERR (server error)
FP_STACK_DEPTH_ERR (program logic error)
FPClipID_GetCanonicalFormat
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPClipID_GetCanonicalFormat (const FPClipID inClipID,

FPCanonicalClipID outClipID)
void
FPCanonicalClipID outClipID
Description
This function converts the string representation of a Content Address

into the platform-neutral canonical format. The canonical format is
ideal for storing Content Addresses in databases.
Parameters
The reference to a C-Clip ID that holds the string format of a

Content Address.
FPCanonicalClipID outClipID
The return of the C-Clip ID of the Content Address stored in

canonical format.
Example
FPClipID vClipID;
FPClip_Write(vClip, vClipID);
81
Clip Functions
FPCanonicalClipID vCanonicalClipID;
FPClipID_GetCanonicalFormat (vClipID, vCanonicalClipID);
Error handling


FPClipID_GetStringFormat
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPClipID_GetStringFormat (const FPCanonicalClipID

inClipID, FPClipID outClipID)
void
const FPCanonicalClipID inClipID
FPClipID outClipID
Description
This function converts the canonical representation of a Content

Address into the platform-specific string format. The string format of
a Content Address is ideal for sharing in email or in other text-based
media.
Parameters
const FPCanonicalClipID inClipID
The reference to a C-Clip ID that holds the canonical format of a

Content Address.
FPClipID outClipID
The return of the C-Clip ID of the Content Address stored in

string format.
Example
Error handling
FPClipID vClipID;
FPClipID_GetStringFormat(vCanonicalClipID, vClipID);
FPClipRef vClip = FPClip_Open(vPool, vClipID,
FP_OPEN_ASTREE);
unsuccessful, the following is a partial list of what errors can occur:
82
Clip Functions

83
Clip Functions
Clip info functions

This section describes the FPClip functions that retrieve information
about a C-Clip:
FPClip_Exists
FPClip_GetClipID
FPClip_GetCreationDate
FPClip_GetEBRPeriod
FPClip_GetName
FPClip_GetNumBlobs
FPClip_GetNumTags
FPClip_GetPoolRef
FPClip_GetRetentionHold
FPClip_GetRetentionPeriod
FPClip_GetTotalSize
FPClip_IsEBREnabled
FPClip_IsModified
FPClip_ValidateRetentionClass
FPClip_Exists
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_Exists (const FPPoolRef inPool, const FPClipID

inClipID)
FPBool
const FPPoolRef inPool, const FPClipID inClipID

This function determines if the given C-Clip exists in the given pool
and returns true or false.
capability "exist" is enabled. If this capability is disabled, the error
FP_OPERATION_NOT_ALLOWED is returned.
84
Clip Functions

documentation contains server configuration details based on the
EMC Atmos online help.
Parameters
The ID of a C-Clip.
Example
Error handling
FPClip_Exists (myPool, myClipID);


Clip info functions
85
Clip Functions
FPClip_GetClipID
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Description
FPClip_GetClipID (const FPClipRef inClip, FPClipID

outClipID)
void
FPClipID outClipID

memory.
This function retrieves the ID of the given C-Clip and returns it in
outClipID.
This function returns an empty string for a C-Clip created by

FPClip_Create() but that has not yet been written to the pool by
FPClip_Write().
Parameters

FPClip_Create().
FPClipID outClipID
The C-Clip ID as specified in the FPClip_Open() function or as

modified by the FPClip_Write() function (can be empty).
Example
Error handling
FPClip_GetClipID (myClip, myClipID);

86

Clip Functions
FPClip_GetCreationDate
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Description
FPClip_GetCreationDate (const FPClipRef inClip, char

*outDate, FPInt *ioDateLen)
void
const FPClipRef inClip, FPInt *ioDateLen
char *outDate, FPInt *ioDateLen

memory.
This function retrieves the creation date, in string format, of the
C-Clip. The time is specified in UTC (Coordinated Universal Time,
also known as GMT Greenwich Mean Time). The creation data is
based on the time of the primary CAS-enabled node when the C-Clip
was created with FPClip_Create().
For example, February 21, 2004 is expressed as: 2004.02.21
10:46:32 GMT
Parameters

FPClip_Create().
char *outDate
outDate is the buffer that will store the creation date of the
C-Clip. This date will be truncated to the buffer length as

specified by ioDateLen.
FPInt *ioDateLen
Input: The reserved length, in characters, of the outDate buffer.

Output: The actual length of the date string, in characters,
including the end-of-string character.
Example
FPInt datesize;
datesize = MAX_DATE_SIZE;
char date[MAX_DATE_SIZE];
FPClip_GetCreationDate (myClip, date, &datesize);
Clip info functions
87
Clip Functions
Error handling


Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPClip_GetEBRClassName (const FPClipRef inClip,

char* outClassName, FPInt* ioNameLen)
void
const FPClipRef inClip, char* outClassName,
FPInt* ioNameLen
FPInt* ioNameLen

memory.
Description

Parameters

FPClip_Create().
char* outClassName
The buffer to which the EBR retention class name is written.
FPInt* ioNameLen
Input: The reserved length, in characters, of the outClassName

buffer.
Output: The actual length of the retention class name, in
characters, including the end-of-string character.
88
Clip Functions
Syntax
Return value
Input parameters
Output Parameters
Concurrency
requirement
Unicode support
FPClip_GetEBREventTime (const FPClipRef inClip,

char* outEBREventTime, FPInt* ioEBREventTimeLen)
void
const FPClipRef inClip, FPInt* ioEBREventTimeLen
char* outEBREventTime, FPInt* ioEBREventTimeLen

memory.
Description

Parameters

FPClip_Create().
char* outEBREventTime
outEBREventTime is the memory buffer that will store the EBR
event time. The time is specified in YYYY.MM.DD hh:mm:ss GMT
format.
FPInt *ioEBREventTimeLen
Input: The reserved length, in characters, of the

outEBREventTime buffer.
Clip info functions
89
Clip Functions
FPClip_GetEBRPeriod
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_GetEBRPeriod (const FPClipRef inClip)

FPLong

memory.
Description

Parameters

FPClip_Create().
90
Clip Functions
FPClip_GetName
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPClip_GetName (const FPClipRef inClip, char *outName,

FPInt *ioNameLen)
void
const FPClipRef inClip, FPInt *ioNameLen
char *outName, FPInt *ioNameLen

memory.
Description
This function retrieves the name of the given C-Clip. The name is
returned in outName.
Parameters

FPClip_Create().
char *outName
outName is the buffer that will store the name of the C-Clip. The
name is truncated if necessary to the buffer length as specified by

ioNameLen.
FPInt *ioNameLen
Input: The reserved length, in characters, of the outName buffer.

Output: The actual length of the name, in characters, including
the end-of-string character. If this value is larger than the length
of the provided buffer, then the full name was not returned.
Example
FPInt namesize;
namesize = MAX_NAME_SIZE;
char name[MAX_NAME_SIZE];
FPClip_GetName (myClip, name, &namesize);
Clip info functions
91
Clip Functions
Error handling


FPClip_GetNumBlobs
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_GetNumBlobs (const FPClipRef inClip)

FPInt

memory.
Description
This function returns the number of blobs that are associated with the
given C-Clip.
Parameters

FPClip_Create().
Example
Error handling
NumBlobs = FPClip_GetNumBlobs (myClip);

92

Clip Functions
FPClip_GetNumTags
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_GetNumTags (const FPClipRef inClip)

FPInt

memory.
This function returns the number of application-specific tags that are
defined in the given C-Clip. Only tags created with FPTag_Create()
are taken into account. This function returns -1 when an error occurs.
Note: C-Clips created with an SDK version lower than 1.2 must be opened in
tree mode in order to retrieve the number of tags, otherwise the error
FP_ATTR_NOT_FOUND_ERR is returned.
Parameters

FPClip_Create().
Example
Error handling
NumTags = FPClip_GetNumTags (myClip);


FP_CLIPCLOSED_ERR (program logic error)
Clip info functions
93
Clip Functions
FPClip_GetPoolRef
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_GetPoolRef (const FPClipRef inClip)

FPPoolRef
Description
This function returns the reference to the pool in which the given
C-Clip has been opened.
Parameters

FPClip_Create().
Example
Error handling
myPool = FPClip_GetPoolRef (myClip);

94

FP_CLIPCLOSED_ERR (program logic error
Clip Functions
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPClip_GetRetentionClassName (const FPClipRef inClipRef,

char *outName, FPInt *ioNameLen)
void
const FPClipRef inClipRef, FPInt *ioNameLen
Description

Parameters

FPClip_Create().
char *outName
outName is the buffer that will store the name of the retention
class. The name will be truncated if necessary to the buffer length

as specified by ioNameLen. outName is an empty string if the
specified C-Clip has no retention class set.
FPInt *ioNameLen

FPClip_GetRetentionHold
Syntax
Return value
Input parameters
FPClip_GetRetentionHold (const FPClipRef inClip)

FPBool
Clip info functions
95
Clip Functions
Concurrency
requirement

memory.
Description

Parameters

FPClip_Create().
96
Clip Functions
FPClip_GetRetentionPeriod
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_GetRetentionPeriod (const FPClipRef inClip)

FPLong

memory.
Description

Parameters

FPClip_Create().
Clip info functions
97
Clip Functions
FPClip_GetTotalSize
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_GetTotalSize (const FPClipRef inClip)

FPLong

memory.
This function returns the total size (in bytes) of all blobs associated
with the given C-Clip.
Note: The returned size does not include the size of the CDF.
Parameters

FPClip_Create().
Example
Error handling
ClipSize = FPClip_GetTotalSize (myClip);

98

FP_WRONG_REFERENCE_ERR (internal error)
Clip Functions
FPClip_IsEBREnabled
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_IsEBREnabled (const FPClipRef inClip)

FPBool

memory.
Description

Parameters

FPClip_Create().
Clip info functions
99
Clip Functions
FPClip_IsModified
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_IsModified (const FPClipRef inClip)

FPBool

memory.
This function returns the modification status of an open C-Clip. This
function returns true if the C-Clip has been modified since it was
created, opened, or written. This function returns false if the C-Clip is
the same as the C-Clip that is written to the pool.
Note: Use this function to determine whether a C-Clip should be written to a
pool. If the function returns false, then there is no need to write the C-Clip to
the pool.
Parameters

FPClip_Create().
Example
Error handling
if (FPClip_IsModified (myClip)) {
FPClip_Write (myClip, myClipID);
}
100

Clip Functions
FPClip_ValidateRetentionClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_ValidateRetentionClass (const FPClipRef inClip,

const FPRetentionClassContextRef inContext)
FPBool
const FPClipRef inClip, const FPRetentionClassContextRef
inContext
Description

generates the error FP_WRONG_REFERENCE_ERR.
Parameters

FPClip_Create().
const FPRetentionClassContextRef inContext
The reference to a retention class context as returned by

FPPool_GetRetentionClassContext().
Clip info functions
101
Clip Functions
Clip attribute functions

This section describes the functions that define and operate on C-Clip
attributes:
FPClip_GetNumDescriptionAttributes
The size of an attribute value is limited to 100 KB. The number of

attributes allowed in a C-Clip is limited only by the maximum size of
a C-Clip, which is 100 MB.
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPClip_GetDescriptionAttribute (const FPClipRef inClip,

const char *inAttrName, const char *outAttrValue,
FPInt *ioAttrValueLen)
void
const FPClipRef inClip, const char *inAttrName, FPInt
*ioAttrValueLen
const char *outAttrValue, FPInt *ioAttrValueLen

memory.
Unicode support
Description
This function retrieves the value of the given attribute from the given
C-Clip.
Parameters

FPClip_Create().
const char *inAttrName

inAttrName is the buffer that contains the name of the attribute
for which the value is retrieved.

102
Clip Functions
const char *outAttrValue

outAttrValue is the buffer that will store the attribute value.
FPInt *ioAttrValueLen
Input: The reserved length, in characters, of the outAttrValue

buffer.
Example
char vBuffer[1024];
FPInt l=sizeof(vBuffer);
FPClip_GetDescriptionAttribute(myClip, "company",
vBuffer, &l);
Error handling


FP_ATTR_NOT_FOUND_ERR (internal error)
103
Clip Functions
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPClip_GetDescriptionAttributeIndex (const FPClipRef

inClip, const FPInt inIndex, char *outAttrName, FPInt
*ioAttrNameLen, char *outAttrValue, FPInt
*ioAttrValueLen)
void
const FPClipRef inClip, const FPInt inIndex, FPInt
*ioAttrNameLen, FPInt *ioAttrValueLen
char *outAttrName, FPInt *ioAttrNameLen, char
*outAttrValue, FPInt *ioAttrValueLen

memory.
Description
This function retrieves the name and value of an attribute from the
given C-Clip according to the given index.
Parameters

FPClip_Create().
const FPInt inIndex
The index number (zero based) of the attribute that has to be

retrieved.
char *outAttrName
outAttrName is the buffer that will store the attribute name.
char *outAttrValue
outAttrValue is the buffer that will store the attribute value.
FPInt *ioAttrNameLen
Input: The reserved length, in characters, of the outAttrName

buffer.
104
Clip Functions

buffer.
Output: The actual length of the value, in characters, including
Example
Error handling
char vName[256];
char vValue[256];
for (int i=0;
i<FPClip_GetNumDescriptionAttributes(myClip); i++)
{FPInt vNameLen = sizeof(vName);
FPInt vValueLen = sizeof(vValue);
FPClip_GetDescriptionAttributeIndex(myClip, i, vName,
&vNameLen, vValue, &vValueLen);
}

105
Clip Functions
FPClip_GetNumDescriptionAttributes
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_GetNumDescriptionAttributes (const FPClipRef

inClip)
FPInt

memory.
Description
This function returns the number of the user-defined and standard

description attributes of the given C-Clip.
Parameters

FPClip_Create().
Example
Error handling
FPInt vNum;
vNum = FPClip_GetDescriptionAttributes(myClip);
106
Clip Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPClip_RemoveDescriptionAttribute (const FPClipRef

inClip, const char *inAttrName)
void
const FPClipRef inClip, const char *inAttrName

memory.
Unicode support
Description
This function removes the given attribute from the CDF of the given
C-Clip.
Parameters

FPClip_Create().

that needs to be removed.

Example
Error handling
FPClip_RemoveDescriptionAttribute(myClip, "company");

107
Clip Functions
Syntax
Return value
FPClip_SetDescriptionAttribute (const FPClipRef inClip,

const char *inAttrName, const char *inAttrValue)
void
Input parameters
const FPClipRef inClip, const char *inAttrName, const

char *inAttrValue
Concurrency
requirement

memory.
Unicode support
Description
This function adds the given attribute (name-value pair) to the CDF
of the given C-Clip.
You can also add user-defined attributes using the environment
variable CENTERA_CUSTOM_METADATA. The SDK reads this variable
during FPClip_Create(). Refer to FPClip_AuditedDelete on
page 61 for more information.
Use FPClip_GetDescriptionAttribute() to read the user-defined
attributes. Use FPClip_GetDescriptionAttributeIndex() to see
which user-defined attributes and standard metadata attributes the
CDF contains.
Parameters

FPClip_Create().

that needs to be added.
const char *inAttrValue

inAttrValue is the buffer that contains the value of the attribute
that needs to be added. The maximum allowed attribute value

size is 100 KB.
Note: To ensure compatibility with future SDK releases, attribute values
should not contain control characters, such as newlines and tabs.
108
Clip Functions
Example
myClip = FPClip_Create(myPool, "test");

FPClip_SetDescriptionAttribute(myClip, "company",
"com.acme");
Error handling


109
Clip Functions
Clip tag functions

This section describes the FPClip functions that manipulate a single
tag from a C-Clip. Because these functions operate on the C-Clip level
and not on the tag level as described in Tag functions on
page 116 they are listed as clip functions.
FPClip_FetchNext
FPClip_GetTopTag
FPClip_FetchNext
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_FetchNext (const FPClipRef inClip)

FPTagRef

memory.
This function returns the next tag in the tag structure. If this is the
first call to the function, the first tag is returned. Call
FPClip_GetTopTag() to restart at the first tag.
If the C-Clip was opened in tree mode, the traversal order is
depth-first, which returns the tags in the same order as if the C-Clip
was opened in flat mode.
This function returns NULL if the C-Clip has no tags, or if the last tag
was already returned.
Be sure to close the tag with FPTag_Close() after you are done
processing the tag to free allocated resources.
Parameters

FPClip_Create().
Example
myClip = FPClip_Open(myPool, myClipID, FP_OPEN_FLAT);

While ((myTag = FPClip_FetchNext(myClip)) ! = 0)
{//...do something with the tag
FPTag_Close(myTag);
}
110
Clip Functions
Error handling


FPClip_GetTopTag
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPClip_GetTopTag (const FPClipRef inClip)

FPTagRef

memory.
The behavior of this function depends on whether the C-Clip is open
in tree mode or flat mode. If you are creating or modifying tags, you
must open the C-Clip in tree mode. Refer to FPPool_Close on
page 33 for more information:
Flat mode
This function returns a reference to the first user tag (as created by
FPTag_Create()) in the specified C-Clip. Call
FPClip_FetchNext() to retrieve subsequent tags.
Tree mode
This function returns a reference to the top-level tag in a C-Clip.
If the tag structure is empty, you can use the top tag as the parent
tag to create the first user tag in the tree.
If the tag structure is not empty, you can use the top tag as a
starting point for further navigation. You can use
FPTag_GetFirstChild(), then FPTag_GetSibling() and
FPTag_GetPrevSibling() to retrieve tags hierarchically, or
FPClip_FetchNext() to retrieve tags in sequential order.
Note: Unlike user tags, the top tag has no name, attributes, or associated
blob. For example, you cannot call FPTag_GetTagName() on the top tag.
Clip tag functions
111
Clip Functions
Be sure to close the tag with FPTag_Close() after you are done
processing the tag to free allocated resources.
Parameters

FPClip_Create().
Example
Error handling
myTag = FPClip_GetTopTag (myClip);

FPPool_GetLastError() returns ENOERR (zero) if successful. If
112

Invible Body Tag
Tag Functions
This chapter describes the various types of FPTag API functions.

Tag functions.....................................................................................
Tag handling functions....................................................................
Tag navigation functions.................................................................
Tag attribute functions ....................................................................
Tag Functions
116
116
126
132
115
Tag Functions
Tag functions
The tag functions operate at the level of a C-Clip tag. Tags are used to
support self-describing content. The tag functions are subdivided
into four categories based on their use:
Tag handling functions To manipulate tags.
Tag navigation functions To navigate through the C-Clip tag

structure.
Tag attribute functions To manipulate tag attributes.
Blob handling functions To manipulate blobs.
Before you can perform a tag operation, you must first create or
retrieve a tag. Close each tag after processing is complete.
Tag handling functions

This section describes the FPTag functions that handle a tag within a
C-Clip:
116
FPTag_Close
FPTag_Copy
FPTag_Create
FPTag_Delete
FPTag_GetBlobSize
FPTag_GetClipRef
FPTag_GetPoolRef
FPTag_GetTagName
Tag Functions
FPTag_Close
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_Close (const FPTagRef inTag)

void
const FPTagRef inTag
Description
This function closes the given tag and frees all allocated resources.
Note that calling this function on a tag that has already been closed
may produce unwanted results.
Parameters
The reference to a tag (as returned from FPTag_Create(),

FPTag_GetParent(), FPTag_GetFirstChild(),
FPTag_GetSibling(), FPTag_GetPrevSibling(),
FPClip_GetTopTag(), or FPClip_FetchNext()).
Example
Error handling
FPTag_Close (myTag);

117
Tag Functions
FPTag_Copy
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_Copy (const FPTagRef inTag, const FPTagRef

inNewParent, const FPInt inOptions)
FPTagRef
const FPTagRef inTag, const FPTagRef inNewParent, const
FPInt inOptions
Description
This function is unsupported in Atmos CAS and can result in data

loss if used.
Parameters
The reference to the tag that you want to copy.
const FPTag inNewParent
The reference to the new destination tag. To copy a tag, a

reference to an existing destination tag is required.
const FPInt inOptions
You can use one or more of the following options:

FP_OPTION_NO_COPY_OPTIONS Only the tag and its
attributes are copied.
FP_OPTION_COPY_BLOBDATA The tag attributes and the blob
data are copied.
Note: The blob IDs are copied and no actual data is moved.
FP_OPTION_COPY_CHILDREN The children of the tag are copied.
You must specify this option if inTag is the top tag. The top tag
itself is not copied. If inTag is a parent of inNewParent, then the
error FP_OUT_OF_BOUNDS_ERR is returned.
118
Tag Functions
FPTag_Create
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_Create (const FPTagRef inParent, const char

*inName)
FPTagRef
const FPTagRef inParent, const char *inName
Unicode support
Description
This function creates a new tag within a C-Clip that has been opened
in tree mode (refer to FPClip_Open()), and returns a reference to the
new tag. The number of tags in a C-Clip is restricted only by the
maximum size of a C-Clip: 100 MB.
Note: A reference to a parent tag is required to create a new tag.
Parameters
const FPTagRef inParent
The reference to the parent tag of the new tag that you are
creating.
const char *inName

inName is the buffer that stores the name of the new tag. The
value cannot be NULL. The characters accepted by this function are
ASCII characters in the Set [a-zA-Z0-9_-.]. The first character

must be a letter or an underscore "_". If your application requires
other characters, use FPTag_CreateW().
Note: The name must be XML compliant and cannot start with the prefix
"xml" or "eclip".
Example
myTag = FPTag_Create (Parent, "tagname");
119
Tag Functions
Error handling

FP_INVALID_NAME (program logic error)

FPTag_Delete
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_Delete (const FPTagRef inTag)

void

This function deletes a tag (and all children of the tag) in the tag
structure of a C-Clip.
If the C-Clip has been opened in flat mode, this function returns
FP_OPERATION_NOT_SUPPORTED. If the function tries to delete a top
tag, the function returns FP_TAG_READONLY_ERR.
Note: After a successful deletion, the system deallocates the memory for the
tag and inTag becomes invalid. Any function call to the tag (for example the
FPTag_Close() function) results in an FP_WRONG_REFERENCE_ERR error.
Parameters

FPTag_GetSibling(), or FPTag_GetPrevSibling()).
Example
Error handling
FPTag_Delete (myTag);
120

FP_TAG_READONLY_ERR (program logic error)
Tag Functions

FPTag_GetBlobSize
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_GetBlobSize (const FPTagRef inTag)

FPLong

This function returns the total size, in bytes, of the blob content
associated with the tag. If the tag has no associated blob content, the
return value is -1.
Note: FPTag_GetBlobSize() best supports C-Clips that are opened in tree
mode.
Parameters

FPTag_GetParent(), FPClip_GetTopTag(),
FPTag_GetFirstChild(), FPTag_GetSibling(),
FPTag_GetPrevSibling(), or FPClip_FetchNext()).
Example
Error handling
BlobSize = FPTag_GetBlobSize (myTag);

121
Tag Functions
FPTag_GetClipRef
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_GetClipRef (const FPTagRef inTag)

FPClipRef
Description
This function returns the reference to the C-Clip in which the given
tag was opened.
Parameters
The reference to a tag that any of the tag functions have navigated to
or created.
Example
Error handling
myClip = FPTag_GetClipRef (myTag);

122

Tag Functions
FPTag_GetPoolRef
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_GetPoolRef (const FPTagRef inTag)

FPPoolRef
Description
This function returns the reference to the pool in which the given tag
was opened.
Parameters
The reference to a tag that any of the tag functions have opened or
created.
Example
Error handling
myPool = FPTag_GetPoolRef (myTag);


123
Tag Functions
FPTag_GetTagName
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPTag_GetTagName (const FPTagRef inTag, char *outName,

FPInt *ioNameLen)
void
const FPTagRef inTag, FPInt *ioNameLen
Description
This function retrieves the name of the given tag.
Parameters

FPTag_GetSibling(), FPTag_GetPrevSibling(),
FPClip_FetchNext(), FPTag_Copy(), or
FPCLIP_GetTopTag()used in flat mode).
char *outName
outName is the buffer that will store the name of the tag. The name
will be truncated to the buffer length as specified by ioNameLen.
FPInt *ioNameLen

Output: The actual length of the name string, in characters,
Example
124
FPInt namesize;
FPTag_GetTagName (myTag, name, &namesize);
Tag Functions
Error handling


125
Tag Functions
Tag navigation functions

The two ways to navigate through the tag structure of a C-Clip are:
Hierarchically Open the C-Clip as a tree structure (refer to

FPClip_Open()). The C-Clip is opened in read/write mode.
Sequentially Open the C-Clip as a flat structure (refer to

FPClip_Open()). The C-Clip is opened in read-only mode. This
option avoids the use of large memory buffers and is useful for
reading C-Clips that do not fit into memory.
This section describes the FPTag functions that handle tag navigation
within a C-Clip:
FPTag_GetFirstChild
FPTag_GetParent
FPTag_GetPrevSibling
FPTag_GetSibling
Figure 1 on page 127 shows how the tags are structured hierarchically
and how the tag navigation functions operate if the C-Clip opens in
tree mode.
126
Tag Functions
Figure 1
Tag structure and navigation
127
Tag Functions
FPTag_GetFirstChild
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_GetFirstChild (const FPTagRef inTag)

FPTagRef

This function returns the first child tag of the given tag. The C-Clip
must have been opened in tree mode (refer to FPClip_Open()).
A child tag is the tag that is one level down from the given tag in the
tag hierarchy (refer to Figure 1 on page 127). This function returns
NULL if no child tag can be found.
Parameters

FPTag_GetFirstChild(), FPTag_GetSibling(), or
FPTag_GetPrevSibling()).
Example
Error handling
myChildTag = FPTag_GetFirstChild (myTag);

128

Tag Functions
FPTag_GetParent
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_GetParent (const FPTagRef inTag)

FPTagRef

This function returns the parent tag of the given tag. The C-Clip must
have been opened in tree mode (refer to FPClip_Open()).
A parent tag is one level up from the given tag in the tag hierarchy
(refer to Figure 1 on page 127). This function returns NULL if the
system cannot find a parent tag.
Parameters

FPTag_GetSibling(), or FPTag_GetPrevSibling()).
Example
Error handling
myParent = FPTag_GetParent (myTag);


129
Tag Functions
FPTag_GetPrevSibling
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_GetPrevSibling (const FPTagRef inTag)

FPTagRef

This function returns the previous sibling tag of the given tag. The
C-Clip must have been opened in tree mode (refer to
FPClip_Open()).
A previous sibling tag is at the same level as the given tag in the tag
hierarchy of the C-Clip but opposite to the sibling tag that is retrieved
by FPTag_GetSibling (refer to Figure 1 on page 127).
This function returns NULL, if the system cannot find a sibling tag.
Parameters

FPTag_GetParent(), FPTag_GetSibling(),
FPTag_GetPrevSibling(), or FPTag_GetFirstChild().
Example
Error handling
mySibling = FPTag_GetPrevSibling (myTag);

130

Tag Functions
FPTag_GetSibling
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_GetSibling (const FPTagRef inTag)

FPTagRef

This function returns the sibling tag of the given tag. The C-Clip must
have been opened in tree mode (refer to FPClip_Open()).
A sibling tag is at the same level as the given tag in the tag hierarchy
of the C-Clip but opposite to the previous sibling tag that is retrieved
by FPTag_GetPrevSibling() (refer to Figure 1 on page 127).
This function returns NULL if the system cannot find a sibling tag.
To go back to the tag where you started, use
FPTag_GetPrevSibling() or FPClip_GetParent() and
FPClip_GetFirstChild().
Parameters

FPTag_GetParent(), FPTag_GetSibling(),
FPTag_GetPrevSibling(), or FPTag_GetFirstChild().
Example
Error handling
mySibling = FPTag_GetSibling (myTag);


131
Tag Functions
Tag attribute functions

There are two sets of tag attribute functions:
Functions to set an attribute value (set attribute functions)
Functions to get an attribute value (get attribute functions)
With the set attribute functions you can assign a specified value to a
tag attribute. If the attribute does not exist yet, the function creates
the attribute. If the attribute exists, the function overwrites the
current value of that attribute. The get attribute functions are used to
retrieve the assigned attribute values.
The size of an attribute value is limited to 100 KB. The number of
attributes allowed in a tag is limited only by the maximum size of a
C-Clip, which is 100 MB.
This section describes the FPTag functions that enable the setting and
retrieval of tag attribute values:
132
FPTag_GetNumAttributes
Tag Functions
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
FPTag_GetBoolAttribute (const FPTagRef inTag, const char

*inAttrName)
FPBool
const FPTagRef inTag, const char *inAttrName
Description
This function returns a Boolean attribute of an existing tag of a

C-Clip.
Parameters

FPTag_GetSibling(), FPTag_GetPrevSibling(), or
FPClip_FetchNext()).

inAttrName is the buffer containing the name of the attribute.
Example
FPTag_GetBoolAttribute (myTag, "attribute_name");
Error handling


133
Tag Functions
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPTag_GetIndexAttribute (const FPTagRef inTag, const

FPInt inIndex, char *outAttrName, FPInt
*ioAttrNameLen, char *outAttrValue, FPInt
*ioAttrValueLen)
void
const FPTagRef inTag, const FPInt inIndex, FPInt
*ioAttrNameLen, FPInt *ioAttrValueLen
char *outAttrName, FPInt *ioAttrNameLen, char
*outAttrValue, FPInt *ioAttrValueLen
Description
This function returns an attribute name and value of an existing tag

in a C-Clip using the given index number.
Parameters
FPTagRef inTag

FPInt inIndex
inIndex is the index number (zero based) of the tag attribute that
has to be retrieved.
char *outAttrName
outAttrName is the buffer that will hold the name of the attribute.
The name will be truncated to the buffer length as specified by

ioAttrNameLen.
FPInt *ioAttrNameLen
Input: The reserved length, in characters, of the outAttrName

buffer.
Output: The actual length of the attribute name, in characters,
134
Tag Functions
char *outAttrValue
outAttrValue is the buffer that will hold the value of the
attribute. The value will be truncated to the buffer length as

specified by ioAttrValueLen.

buffer.
Output: The actual length of the attribute value, in characters,
Example
Error handling
char TagAttrName[MAX_NAME_SIZE];
char TagAttrValue[MAX_NAME_SIZE];
NumAttributes = FPTag_GetNumAttributes(Tag);
if (FPPool_GetLastError() != 0)
handle error...
for (i = 0; i < NumAttributes; i++)
{
AttrNameSize = MAX_NAME_SIZE;
AttrValueSize = MAX_NAME_SIZE;
FPTag_GetIndexAttribute(Tag, i,
TagAttrName, &AttrNameSize,
TagAttrValue, &AttrValueSize);
if (FPPool_GetLastError() != 0)
handle error
printf("Attribute #%d has name \"%s\" and value
\"%s\".\n",
i, TagAttrName, TagAttrValue);
}

135
Tag Functions
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
FPTag_GetLongAttribute (const FPTagRef inTag, const char

*inAttrName)
FPLong
Description
This function returns an FPLong attribute of an existing tag of a

C-Clip.
Parameters
The reference to a tag (as returned from the functions

FPTag_Create(), FPTag_GetParent(),
Example
Error handling
myValue = FPTag_GetLongAttribute (myTag,

"attribute_name");
136

inAttrName is the buffer containing the name of the attribute.

Tag Functions
FPTag_GetNumAttributes
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_GetNumAttributes (const FPTagRef inTag)

FPInt
Description
This function returns the number of attributes in a tag.
Parameters

Example
Error handling
NumAttrs = FPTag_GetNumAttributes (myTag);


137
Tag Functions
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPTag_GetStringAttribute (const FPTagRef inTag, const

char *inAttrName, char *outAttrValue, FPInt
*ioAttrValueLen)
void
const FPTagRef inTag, const char *inAttrName, FPInt
*ioAttrValueLen
char *outAttrValue, FPInt *ioAttrValueLen
Unicode support
Description
This function retrieves a string attribute of an existing tag in a C-Clip

and returns the value to a buffer with a specified length.
Parameters


inAttrName is the buffer containing the attribute name.
char *outAttrValue
outAttrValue is the buffer that will hold the attribute value. The
value will be truncated to the buffer length as specified by

ioAttrValueLen.

buffer.
138
Tag Functions
Example
Error handling
char outAttrValue[MAX_NAME_SIZE];
FPTag_GetStringAttribute (myTag, "name", outAttrValue,
&namesize);

Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_RemoveAttribute (const FPTagRef inTag, const char

*inAttrName)
void
Unicode support
Description
This function removes an attribute from a tag. The C-Clip containing

the tag must have been opened in tree mode (refer to
FPClip_Open()).
Parameters


inAttrName is the buffer containing the name of the attribute that
has to be removed.
139
Tag Functions
Example
Error handling
FPTag_RemoveAttribute (myTag, "attribute_name");


Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_SetBoolAttribute (const FPTagRef inTag, const char

*inAttrName, const FPBool inAttrValue)
void
const FPTagRef inTag, const char *inAttrName, const
FPBool inAttrValue
Unicode support
Description
This function sets a Boolean attribute for an existing tag in an opened

C-Clip. The C-Clip must have been opened in tree mode (refer to
FPClip_Open()). This function requires a reference to the tag that
you want to update (inTag), the attribute name (inAttrName) and the
attribute value (inAttrValue).
Parameters


inAttrName is the buffer that will hold the name of the attribute
to be created or updated.
140
Tag Functions
Note: The name must be XML compliant.
Example
Error handling
const FPBool inAttrValue

inAttrValue is the value of the attribute to be assigned.
FPBool inAttrValue;
inAttrValue = TRUE;
FPTag_SetBoolAttribute (myTag, "name", inAttrValue);

Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_SetLongAttribute (const FPTagRef inTag, const char

*inAttrName, const FPLong inAttrValue)
void
const FPTagRef inTag, const char *inAttrName, const
FPLong inAttrValue
Unicode support
Description
This function sets an FPLong attribute of the given tag in an open

FPClip_Open()). This function requires a reference to the tag that has
to be updated (inTag), the attribute name (inAttrName), and the
141
Tag Functions
Parameters


inAttrName is a string containing the name of the attribute to be
created or updated.
Example
Error handling
FPLong inAttrValue;
inAttrValue = 100;
FPTag_SetLongAttribute (myTag, "name", inAttrValue);
142
const FPLong inAttrValue

inAttrValue contains the value of the attribute to be assigned.

Tag Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPTag_SetStringAttribute (const FPTagRef inTag, const

char *inAttrName, const char *inAttrValue)
void
const FPTagRef inTag, const char *inAttrName, const char
*inAttrValue
Unicode support
Description
This function sets a string attribute of the given tag in an opened

FPClip_Open()). This function requires a reference to the tag that has
to be updated (inTag), the attribute name (inAttrName), and the
Parameters


inAttrName is the buffer containing the name of the attribute to
be created or updated.
const char *inAttrValue

inAttrValue contains the value of the attribute that will be
assigned. The value cannot be NULL or an empty string. If the
value is larger than 100 KB, EMC recommends writing the value
as a separate blob to the pool in order to increase performance.
The maximum allowed attribute value size is 100 KB.
143
Tag Functions
Note: To ensure compatibility with future SDK releases, attribute values

should not contain control characters, such as newlines and tabs.
Example
Error handling
FPTag_SetStringAttribute (myTag, "name", "value");

144

Invible Body Tag
This chapter describes FPTag blob-handling functions.

Blob handling functions .................................................................. 148
147
Blob handling functions

This section describes the FPTag functions that manipulate a blob (a
tag referring to actual data):
FPTag_BlobExists
FPTag_BlobRead
FPTag_BlobReadPartial
FPTag_BlobWrite
FPTag_BlobWritePartial
FPTag_BlobExists
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_BlobExists (const FPTagRef inTag)

FPInt

This function checks if the blob data of the given tag exists. If the blob
data of the given tag exists, the function returns 1. If the blob data is
segmented then all segments must exist. If the blob data does not
exist, the function returns 0. If the tag has no associated blob data, the
function returns -1.
capability "exist" is enabled. If this capability is disabled, the error
Parameters
FPTagRef inTag

FPTag_GetPrevSibling(), FPClip_FetchNext(), or
FPTag_GetParent()).
Example
Error handling
FPTag_BlobExists (myTag);
148

FP_TAG_HAS_NO_DATA_ERR (program logic error)
FP_FILE_NOT_STORED_ERR (program logic error)
FP_TAGCLOSED_ERR (program logic error)
FP_WRONG_STREAM_ERR (client error)
149
FPTag_BlobRead
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_BlobRead (const FPTagRef inTag, const FPStreamRef

inStream, const FPLong inOptions)
void
const FPTagRef inTag, const FPStreamRef inStream, const
FPLong inOptions
Concurrent threads cannot operate on the same stream.

This function retrieves the blob data from the pool and writes it to the
stream object (refer to Stream functions on page 178).
Note: Refer to Stream creation functions on page 181 for more information
on how a stream is opened.
FPTag_BlobRead() leaves the marker at the end of the stream. The
stream does not have to support marking. If the operation fails, the
operation continues from the point where it failed.
Note: Due to server limitations, the stream should not exceed 1 minute per
iteration to store the data received from the server. This means the
completeProc callback should not take longer than 1 minute to execute.
This function gets the Content Address from the tag, opens the blob,
reads the data in chunks of 16 Kbyte, writes the bytes to the stream,
and closes the blob.

150
Parameters
The reference to a tag (as returned from

FPTag_GetParent()).
The reference to a stream (as returned from the functions

FPStream_CreateXXX() or FPStream_CreateGenericStream()).

Example
Error handling
FPTag_BlobRead (myTag, myStream,


151
FPTag_BlobReadPartial
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_BlobReadPartial (const FPTagRef inTag, const

FPStreamRef inStream, const FPLong inOffset, const
FPLong inReadLength, const FPLong inOptions)
void
FPLong inOffset, const FPLong inReadLength, const FPLong
inOptions

This function retrieves the blob data from the pool and writes the
data to a stream object that the application provides (refer to Stream
functions on page 178). This function reads the data in chunks of 16
KB.
EMC recommends that you use FPTag_BlobReadPartial in
conjunction with FPStream_CreatePartialFileForInput and
FPStream_CreatePartialFileForOutput.
FP_OPERATION_NOT_ALLOWED is returned. Refer to
FPPool_GetCapability on page 34 for more information on the

server capabilities. It is imperative that your application
This function gets the Content Address from the tag, opens the blob,
starts reading the blob packet as specified by the given offset, writes
the specified bytes to the stream, and closes the blob.
Note: If the offset tries to read past the end of the blob, then no data is added
to the output stream and the function returns ENOERR. Use
FPTag_GetBlobSize() to verify that you are not reading past the end of
the blob.
iteration to store the data received from the server. This means the
completeProc callback should not take longer than 1 minute to execute.
152
Parameters
The reference to a tag (as returned from

FPTag_GetParent()).

const FPLong inOffset
The starting offset of the read operation.
const FPLong inReadLength
The length in bytes of the data chunk to be read. Specify -1 if you

want to read all data from the offset to the end of the blob.

Example
Read 8 Kbytes of the blob, starting at the first byte.

FPTag_BlobReadPartial(myTag, myStream, 0, 8192,
Read 8 Kbytes of the blob, starting at offset 32 Kbytes.

FPTag_BlobReadPartial(myTag, myStream, 32768, 8192,
Read the entire blob, equivalent to FPTag_BlobRead(myTag,

myStream, FP_OPTION_DEFAULT_OPTIONS).
FPTag_BlobReadPartial(myTag, myStream, 0, -1,
153
Error handling

154

FPTag_BlobWrite
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_BlobWrite (const FPTagRef inTag, const FPStreamRef

inStream, const FPLong inOptions)
void
FPLong inOptions

This function writes blob data to the pool from a stream object that
the application provides (refer to the section Stream functions on
page 178).
This function supports two methods for storing data:
Linked data If the data size is larger than the embedding

threshold (refer to FPPool_SetGlobalOption on page 54) or you
specified the FP_OPTION_LINK_DATA option, the function creates
a new attribute for the specified tag, opens a new blob, reads
bytes from the stream object, writes the data to the blob, closes
the blob, and sets the blob ID (Content Address) as the attribute
value. By default, the embedding threshold is zero (0), so no data
embedding occurs.
Embedded data If the data size is smaller than the embedding

threshold (refer to FPPool_SetGlobalOption on page 54) or you
specified the FP_OPTION_EMBED_DATA option, the function creates
an attribute for the specified tag, reads bytes from the stream
object, encodes the data as a base64 string, and sets this string as
the value of the attribute. The function also calculates and stores
the blob ID (Content Address) as the value of another tag
attribute. For more information on embedding data, refer to the
EMC Atmos CAS Programmers Guide.
The storage method is transparent to the client application The

blob functions (for example, FPTag_BlobRead()) behave identically
for embedded and linked data.
155
Parameters that you specify determine whether the Content Address

(CA) is calculated before or while sending the data to the pool. By
default, the CA is calculated by the client while the data is being sent.
Ensure that the C-Clip to which the tag belongs has been opened in
tree mode. A C-Clip opened in flat mode is read-only.

FPPool_SetClipID on page 51, this call uses an additional blob
discriminator during write and read operations of the blob. If
collision avoidance is disabled at pool level, you can enable it for this
call using FP_OPTION_ENABLE_COLLISION_AVOIDANCE.
If this function is used to restore data from a stream to the pool, the
data is only exported to the pool if inTag already has data associated
with it and the stream data is the same.
iteration to retrieve the data for transfer. In practice this means the
prepareBufferProc callback should not take longer than 1 minute to
execute.
If the generic stream returns more data than requested, the SDK
enlarges the buffer to accommodate the additional data. If the stream
cannot provide the data within 1 minute, set mTransferLen to -1 and
mAtEOF to false, which forces FPTag_BlobWrite() to issue a
keep-alive packet to the server.
Segments are exported to the server as if they are different blobs. If an
error occurs during the write operation, the function retries. The retry
operation only works properly if the stream supports marking (and
goes back to a previous position which is the beginning of the current
segment). If the stream does not support marking to a previous
position, the write operation is restarted from the beginning of the
stream.
Parameters
156

FPTag_GetParent()).
The reference to an input stream (as returned from the

FPStream_CreateXXX() functions or
FPStream_CreateGenericStream()). Refer to Stream
A variety of options that control the writing of the blob. You can
specify options from different option sets by using the OR
operator (ORing the values together).
ID Calculation Identifies how the content address should
be calculated. You must use one of the following options:
FP_OPTION_CLIENT_CALCID The client calculates the
content address before sending the data to the
CAS-enabled node. The client does not send the data if the
node already contains identical data. Consider using this
option when writing small files (smaller than 10 MB) and
identical data is likely to exist on one or more CAS-enabled
nodes. The provided stream must support marking. All
non-generic streams support marking; a generic stream
may or may not support marking.
FP_OPTION_CLIENT_CALCID_STREAMING The client
calculates the content address while sending the data to the
server. The client sends the data even if one or more
CAS-enabled nodes already contains the data. This option
is equivalent to FP_OPTION_DEFAULT_OPTIONS. Consider
using this option when writing large files (10 MB or larger),
when using many threads, or when identical data is
unlikely to exist on the CAS-enabled nodes.
You can convert CLIENT_CALCID_STREAMING to operate in
the SERVER_CALCID_STREAMING mode by setting the option
FP_OPTION_DISABLE_CLIENT_STREAMING in
FPPool_SetGlobalOption or by setting it to True as an
environment variable. If the latter, the change does not
require a recompilation of application code. The SDK then
handles and processes all references to
CLIENT_CALCID_STREAMING as
SERVER_CALCID_STREAMING.
157
FP_OPTION_SERVER_CALCID_STREAMING The Atmos

CAS server calculates the content address as the
application server sends the data. There is no client check
of the blob data before it is streamed to one or more
CAS-enabled nodes.
Collision Avoidance Specifies whether collision avoidance
is enabled for this call to FPTag_BlobWrite(). Call
FPPool_SetIntOption() to control collision avoidance at the
pool level. Collision avoidance causes a unique blob ID to be
generated for this content. Note that enabling collision
avoidance disables the Atmos CAS single-instance storage
feature. For more information refer to the EMC Atmos CAS
Programmers Guide and FPPool_SetClipID on page 51.
Option choices are:
FP_OPTION_ENABLE_COLLISION_AVOIDANCE Enables
collision avoidance.
FP_OPTION_DISABLE_COLLISION_AVOIDANCE Disables
Embedded Data Specifies whether the data is stored in the
CDF (embedded data), or as a separate blob with only the CA
stored in the CDF (linked data). Choices are:
FP_OPTION_EMBED_DATA Embed the data in the CDF.
The maximum data size that can be embedded is 100 KB.
Note: If your program attempts to write an embedded blob that is too
large, and FP_OPTION_EMBED_DATA has been set, an
FP_PARAM_ERR is returned from the call, and the blob is not written.
To avoid losing data, ensure that your program checks for this error
and that you are not attempting to write data in excess of 100 KB.
If the call fails, rewrite the blob as a linked blob.
FP_OPTION_LINK_DATA Do not embed the data in the

CDF.
These options override the default embedded-data threshold
(refer to FPPool_SetGlobalOption on page 54).
158
Example
The following example calculates the Content Address on the client

while sending the data to one or more CAS-enabled nodes and
enables collision avoidance.
FPTag_BlobWrite (myTag, myStream,
FP_OPTION_CLIENT_CALCID_STREAMING |
FP_OPTION_ENABLE_COLLISION_AVOIDANCE);
Error handling


FP_MULTI_BLOB_ERR (program logic error)
159
FPTag_BlobWritePartial
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPTag_BlobWritePartial (const FPTagRef inTag, const

FPStreamRef inStream, const FPLong inOptions, const
FPLong inSequenceID)
void
FPLong inOptions, const FPLong inSequenceID

This function can write blob data to the pool from a stream that the
application provides (refer to the section Stream functions on
page 178). Applications can use multiple threads for the write
operation and append data to existing data contained within an
existing tag. This function uses the slicing-by-size model to write
randomly accessed data. For more information on blob-slicing, refer
to the EMC Atmos CAS Programmers Guide.
EMC recommends that you use FPTag_BlobWritePartial in
conjunction with FPStream_CreatePartialFileForInput and
FPStream_CreatePartialFileForOutput.
FPTag_BlobWritePartial()does not operate in conjunction with
any of the embedded options. If you include FP_OPTION_EMBED_DATA
in the inOptions parameter, an error occurs. Similarly, if you set
FP_OPTION_EMBEDDED_DATA_THRESHOLD, the function ignores it.
Both FPTag_BlobRead() and FPTag_BlobReadPartial() can read

this data transparently, which precludes the need for additional
application coding.
The parameters you specify determine whether the Content Address
(CA) is calculated before or while sending the data to the pool. By
default, the CA is calculated by the client while the data is being sent.
Ensure that the C-Clip to which the tag belongs has been opened in
tree mode. A C-Clip opened in flat mode is read-only.
160

FPPool_SetClipID on page 51, this call uses an additional blob
discriminator during write and read operations of the blob. If
collision avoidance is disabled at pool level, you can enable it for this
call using FP_OPTION_ENABLE_COLLISION_AVOIDANCE.
Note: You cannot use FPTag_BlobWritePartial() to restore data to an
Atmos CAS.
iteration to retrieve the data for transfer. In practice this means the
prepareBufferProc callback should not take longer than 1 minute to
execute.
If the generic stream returns more data than requested, the SDK
enlarges the buffer to accommodate the additional data. If the stream
cannot provide the data within 1 minute, set mTransferLen to -1 and
mAtEOF to false, which forces FPTag_BlobWritePartial() to issue a
keep-alive packet to the server.
Segments are exported to the server as if they are different blobs. If an
error occurs during the write operation, the function retries. The retry
operation only works properly if the stream supports marking (and
goes back to a previous position which is the beginning of the current
segment). If the stream does not support marking to a previous
position, the write operation is restarted from the beginning of the
stream.
Note: If you are not using FPTag_BlobWritePartial to perform
multithreading, use FPTag_BlobWrite instead.
161
Parameters

The reference to an input stream (as returned from the

FPStream_CreateXXX() functions or
FPStream_CreateGenericStream()). Refer to Stream
A variety of options that controls the writing of the blob. You can
specify options from different option sets by using the OR
operator (ORing the values together).
ID Calculation Identifies how the Content Address should
be calculated. You must use one of the following options:
FP_OPTION_CLIENT_CALCID The client calculates the
address before sending the data to one or more
CAS-enabled nodes. The client does not send the data if the
nodes already contain identical data. Consider using this
option when writing small files (smaller than 10 MB) and
identical data is likely to exist on one or more CAS-enabled
nodes. The provided stream must support marking. All
non-generic streams support marking; a generic stream
may or many not support marking.
FP_OPTION_CLIENT_CALCID_STREAMING The client
calculates the address while sending the data to the server.
The client sends the data even if one or more CAS-enabled
nodes already contains the data. This option is equivalent
to FP_OPTION_DEFAULT_OPTIONS. Consider using this
option when writing large files (10 MB or larger), when
using many threads, or when identical data is unlikely to
exist on the nodes.
You can convert CLIENT_CALCID_STREAMING to operate in
the FP_OPTION_SERVER_CALCID_STREAMING mode by
setting the option FP_OPTION_DISABLE_CLIENT
_STREAMING in FPPool_SetGlobalOption or by setting it
to True as an environment variable. If the latter, the change
does not require a recompilation of application code. The
162
SDK then handles and processes all references to

CLIENT_CALCID_STREAMING as
SERVER_CALCID_STREAMING.
FP_OPTION_SERVER_CALCID_STREAMING The Atmos
CAS server calculates the content address as the
application server sends the data.
Collision Avoidance Specifies whether collision avoidance
is enabled for this call to FPTag_BlobWritePartial(). Call
FPPool_SetIntOption() to control collision avoidance at the
pool level. Collision avoidance causes a unique blob ID to be
generated for this content. Note that enabling collision
avoidance disables the Atmos CAS single-instance storage
feature. For more information refer to the EMC Atmos CAS
Programmers Guide and FPPool_SetClipID on page 51.
Option choices are:
FP_OPTION_ENABLE_COLLISION_AVOIDANCE Enables
FP_OPTION_DISABLE_COLLISION_AVOIDANCE Disables
const FPLong inSequenceID
The identifier that determines the sequence of the written data

when the same inTag is used by one or more threads. This
sequence sets the order in which the data is to be read back from
Atmos CAS for the purpose of reassembling the blob segments.
This read-back starts from the lowest ID to the highest ID.
If data is being written to a tag with existing data, it automatically
is written to the end of the existing data.
An inSequenceID must be greater than or equal to zero. Threads
that are using the same inTag cannot have duplicate sequence
IDs. Each ID must be unique, otherwise, an
FPParameterException is thrown.
Although sequence IDs do not need to be adjacent to one another,
a single sequence ID cannot be reused within a tag during the
same FPClip_Open/FPClip_Close operation. It can, however, be
reused in that tag if reopened in another API call.
Example
This example shows how blob-slicing works with multiple threads.

Assumptions:
POSIX pthread model
163
Variables inStream1 and inStream2, based on type FPStreamRef,

each of which holds half the data in a file, respectively.
You have an open clip and an open tag into which to write the
data (vTag is a FPTagRef type).
Data structure used to pass data to a thread:

struct myWriterArgs {
FPTagRef mTag;
FPStreamRef mStream;
FPLong mOptions;
FPInt mSequenceID;
} myWriterArgs;
Thread function:
void* myWriter (void* inArgs)
{
myWriterArgs* vArgs = (myWriterArgs*)inArgs;
if ( vArgs )
{
FPTag_BlobWritePartial(vArgs->mTag,
vArgs->mStream,
vArgs->mOptions,
vArgs->mSequenceID);
}
return NULL;
}
Example of writing the data to a tag in an open C-Clip (vTag):

// initialize the data
myWriterArgs vArgs1;
myWriterArgs vArgs2;
vArgs1.mTag = vTag;
vArgs1.mStream = inStream1;
vArgs1.mOptions = FP_OPTION_CLIENT_CALCID;
vArgs1.mSequenceID = 1;
vArgs2.mTag = vTag;
vArgs2.mStream = inStream2;
vArgs2.mOptions = FP_OPTION_CLIENT_CALCID;
vArgs2.mSequenceID = 2;
// create the threads
pthread_t myThread1;
pthread_t myThread2;
pthread_create(&myThread1, NULL, &myWriter,
(void*)&vArgs1);
pthread_create(&myThread2, NULL, &myWriter,
164
(void*)&vArgs2);
// wait for the threads to complete
pthread_join(myThread1, NULL);
pthread_join(myThread2, NULL);
Error handling


FP_DUPLICATE_ID_ERR (client error)
FP_MULTI_BLOB_ERR (program logic error)
FPParameterException (program logic error or internal error)

165
166
Invble Body Tag
This chapter describes the FPRetentionClass API functions.

Retention class functions................................................................. 168
167
Retention class functions

This section describes the FPRetentionClass functions used to
manage retention classes:
FPRetentionClass_Close
FPRetentionClassContext_Close
FPRetentionClassContext_GetFirstClass
FPRetentionClassContext_GetLastClass
FPRetentionClassContext_GetNextClass
FPRetentionClassContext_GetNumClasses
FPRetentionClassContext_GetPreviousClass
FPRetentionClass_GetPeriod
FPRetentionClass_Close
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClass_Close (FPRetentionClassRef inClassRef)

void
FPRetentionClassRef inClassRef
Description
This function closes the given retention class and frees all related
(memory) resources. Note that calling this function on a retention
class that is already closed may produce unwanted results.
Parameters

FPRetentionClassContext_GetXXXClass() functions.
Example
Error handling
FPRetentionClass_Close(vRetentionClass);
168
FPRetentionClassContext_Close
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPRetentionClassContext_Close (FPRetentionClassContext
inContextRef)
void
FPRetentionClassContext inContextRef

This function closes the given retention class context and frees all
related (memory) resources. Note that calling this function on a
retention class context that is already closed may produce unwanted
results.
Note: The retention class context returned by Atmos CAS will always be an
empty list.
Parameters
FPRetentionClassContext inContextRef
The reference to a retention class context object as returned from

Example
Error handling
FPRetentionClassContext_Close (myRetentionClassContext);
None.
169
FPRetentionClassContext_GetFirstClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClassContext_GetFirstClass (const
FPRetentionClassContextRef inContextRef)
FPRetentionClassRef
const FPRetentionClassContextRef inContextRef
Description
The retention class context returned by Atmos CAS will always be an

empty list. If called, this function generates the error
FP_WRONG_REFERENCE_ERR.
Parameters
The reference to a retention class context, as returned from the

function FPPool_GetRetentionClassContext().
FPRetentionClassContext_GetLastClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClassContext_GetLastClass (const
FPRetentionClassRef
Description

Parameters

170
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClassContext_GetNamedClass (const
FPRetentionClassContextRef inContextRef, const char
*inName)
FPRetentionClassRef
const FPRetentionClassContextRef inContextRef,
const char *inName
Unicode support
Description

Parameters
The reference to a retention class context, as returned from

const char *inName
The name of the class to be retrieved.
FPRetentionClassContext_GetNextClass
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPRetentionClassContext_GetNextClass (const
FPRetentionClassRef

171
Parameters

FPRetentionClassContext_GetNumClasses
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClassContext_GetNumClasses (const
FPInt
Description

empty list. If called, this function returns 0.
Parameters
The reference to a retention class context, as returned from

172
FPRetentionClassContext_GetPreviousClass
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClassContext_GetPreviousClass (const
FPRetentionClassRef
Description

Parameters

Syntax
Return value
Input parameters
Output Parameters
Concurrency
requirement
Unicode support
Description
FPRetentionClass_GetName (const FPRetentionClassRef

inClassRef, char *outName, FPInt *ioNameLen)
void
const FPRetentionClassRef inClassRef, FPInt *ioNameLen
This function retrieves the name of the given retention class. The
name is returned in outName.
Call FPRetentionClass_Close() when you are done with this
object.
173
Parameters

char *outName
The buffer that will store the name of the retention class. The
name will be truncated if needed to the buffer length as specified
by ioNameLen.
FPInt *ioNameLen

Example
Error handling
FPInt namesize = MAX_NAME_SIZE;

FPRetentionClass_GetName (myRetClassContext, name,
&namesize);

FPRetentionClass_GetPeriod
Syntax
Return value
Input parameters
Concurrency
requirement
FPRetentionClass_GetPeriod (const FPRetentionClassRef

inClassRef)
FPLong
Description
This function returns the retention period, in seconds, of the given

retention class.
Parameters

Example
174
vRetentionPeriod = FPRetentionClass_GetPeriod
(myRetentionClass);
Error handling


175
176
Invble Body Tag
Stream Functions
This chapter describes the FPStream API functions.

Stream functions............................................................................... 178

Stream creation functions ............................................................... 181
Stream handling functions.............................................................. 209
Stream Functions
177
Stream Functions
Stream functions
Streams are generalized input/output channels similar to the
HANDLE mechanism used in the Win32 API for files, the C++
iostream functionality, the C standard I/O FILE routines, or the Java
InputStream/OutputStream facility.
All bulk data movement in the API is achieved by first associating a
stream with a data sink or source (for example, a file, an in-memory
buffer, or the standard output channel) and then performing
operations on that stream.
The API stream functions implement streams generically. When
creating a stream, the application developer has to use method
pointers to indicate how subsequent stream functions should handle
the stream. For more information on the available method pointers
for stream functions, refer to FPStream_CreateGenericStream on
page 186.
Stackable stream support

A stackable stream is a stream that calls another stream as part of its
operation. An example is a stream that prepends bytes to another
stream, or a stream that compresses stream data. To support stackable
streams, the following functions are available to the API:
FPStream_PrepareBuffer(), FPStream_Complete(),
FPStream_SetMark(), and FPStream_ResetMark().
Generic stream operation

In SDK versions prior to v1.2, generic streams that were used for
output (for example with FPTag_BlobRead()) received a buffer with
data, which the completion callback function had to process. For SDK
v1.2 and higher, the application has the option of providing a buffer
to the output stream, to be filled by the SDK. In this case, the stream
remains the owner of the output buffer.
Foreign pointer mode
The SDK remains the owner of the pointer to the data buffer
(mBuffer). The stream completion function is only allowed to read
data from it. This mode is compatible with pre-v1.2 SDK releases.
178
Stream Functions
The following rules apply:
Do not declare prepareBufferProc. If declared, set mBuffer to

NULL.
While the function completeProc can read the data from

mBuffer to obtain the number of mTransferLen bytes, it is not
allowed to change the fields in the StreamInfo structure.
If the end of the stream has been reached, then mAtEOF is true. It is
possible that this last call to the completeProc does not pass any data
(mTransferLen is 0, and mBuffer remains NULL).
Stream buffer mode
The stream provides a buffer that the SDK will fill.
prepareBufferProc is responsible for preparing this buffer and to
set mBuffer to it. mTransferLen contains the number of bytes that
can be transferred. completeProc processes this buffer.
mTransferLen then contains the number of bytes actually transferred
into the buffer. The value of mBuffer does not change.
The following rules apply:
prepareBufferProc sets mBuffer to point to the buffer it

manages. It also sets mTransferLen to the maximum number of
bytes that the stream can receive. (Typically, mTransferLen is the
length of mBuffer.)
completeProc can process the data in mBuffer. The number of

mTransferLen bytes is actually copied into mBuffer.
The algorithm is as follows:

set vRemainInBuffer to 0
set vRemainInPacket to 0
loop until all blob data has been read
if vRemainInBuffer == 0 then
FPStream_PrepareBuffer
set vRemainInBuffer to mTransferLen

if vRemainInPacket == 0 then
ReadPacket from Centera
set vRemainInPacket to length of data
set vToCopy to min (vRemainInBuffer, vRemainInPacket)
copy vToCopy bytes from packet to mBuffer
decrease vRemainInPacket by vToCopy
decrease vRemainInBuffer by vToCopy
if vRemainInBuffer == 0 then
FPStreamComplete
Stream functions
179
Stream Functions
If the end of the stream has been reached, then mAtEOF is true. It is
possible that this last call to completeProc does not pass any data
(mTransferLen is 0).
Stream callback validation
In v3.2, the SDK performs generic stream verifications on certain
fields that can be changed in application callbacks. To enable full
validation, logging and the FP_OPTION_STREAM_STRICT_MODE option
must be enabled. (This option is enabled by default.) If only logging
is enabled, the SDK issues the appropriate warning message to the
log. If the strict mode and logging are enabled and validation fails,
the SDK generates either the FP_STREAM_VALIDATION_ERR or
FP_STREAM_BYTECOUNT_MISMATCH_ERR error message, depending on
the field.
The SDK validates the following FPStreamInfo fields:
mVersion
MStreamLen
mStreamPos
mMarkerPos
mReadFlag
Table 14 on page 189 provides more information.

Note: You can disable the strict mode by setting the
FP_OPTION_STREAM_STRICT_MODE environment variable to a non-zero
value.
180
Stream Functions
Stream creation functions

This section describes the FPStream functions for creating a stream:
FPStream_CreateBufferForInput
FPStream_CreateBufferForOutput
FPStream_CreateFileForInput
FPStream_CreateFileForOutput
FPStream_CreateGenericStream
FPStream_CreateTemporaryFile
FPStream_CreateToNull
FPStream_CreateToStdio
FPStream_CreateBufferForInput
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_CreateBufferForInput (char *inBuffer, const

unsigned long inBuffLen)
FPStreamRef
char *inBuffer, const unsigned long inBuffLen
Description
This function creates a stream to read from a memory buffer and

returns a reference to the created stream.
Parameters
const char *inBuffer

inBuffer is the memory buffer containing the data for the
stream.
Example
Error handling
const unsigned long inBuffLen

inBuffLen is the buffer length (in bytes) of inBuffer.
char myDataSource[A_BIG_SIZE];
myStream = FPStream_CreateBufferForInput (myDataSource,
A_BIG_SIZE);

FP_STREAM_VALIDATION_ERR (program logic error)
181
Stream Functions
FP_STREAM_BYTECOUNT_MISMATCH_ERR (program logic error)
FPStream_CreateBufferForOutput
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_CreateBufferForOutput (char *inBuffer, const

unsigned long inBuffLen)
FPStreamRef
const char *inBuffer, const unsigned long inBuffLen
This function is not thread safe.
Description
This function creates a stream to write to a memory buffer and

returns a reference to the created stream. When the end of the buffer
has been reached mAtEOF of pStreamInfo is set to true. Refer to
FPStream_CreateGenericStream on page 186 for more information
on pStreamInfo.
Parameters
const char *inBuffer

inBuffer is the memory buffer containing the data for the
stream.
Example
Error handling
char myDataSource[A_BIG_SIZE];
myStream = FPStream_CreateBufferForOutput (myDataSource,
A_BIG_SIZE);
182
const unsigned long inBuffLen

inBuffLen is the buffer length (in bytes) of inBuffer.

Stream Functions
FPStream_CreateFileForInput
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_CreateFileForInput (const char *inFilePath,

const char *inPerm, const long inBuffSize)
FPStreamRef
const char *inFilePath, const char *inPerm, const long
inBuffSize
Description
This function creates a stream to read from a file and returns a

reference to the created stream. The stream behaves like a file and
depending on the given permission (inPerm), you can use the stream
with most of the stream handling functions (Section Stream
handling functions on page 209).
Parameters
const char *inFilePath

inFilePath is the buffer that contains the path name of the file
for which the stream must be created.
const char *inPerm

inPerm is the buffer that contains the open permission for the file.
You can use the following permission:

rb: opens the given file for reading. If the file does not exist or the
system cannot find the file, the function returns an error.
const long inBuffSize

inBuffSize is the size of the buffer (in bytes) that is used when
reading the file. This value must be greater than 0.

Note: EMC recommends a buffer size no larger than 1 MB,
depending on the application requirements.
Example
This example shows how to stream data to a pool.
{ FPStreamRef vStream = FPStream_CreateFileForInput (pPath, "rb", 16*1024);

// open a new stream
if (vStream != 0)
{ FPTag_BlobWrite (vFileTag, vStream, 0);
// write it to the pool
FPStream_Close (vStream);
// and don't forget to close it...
}
183
Stream Functions
vStatus = FPPool_GetLastError();
}
Error handling


FP_FILESYS_ERR (program logic error)
FPStream_CreateFileForOutput
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_CreateFileForOutput (const char *inFilePath,

const char *inPerm)
FPStreamRef
const char *inFilePath, const char *inPerm
This function is not thread safe.
Description
This function creates a stream to write to a file and returns a reference

to the created stream. The stream behaves like a file and depending
on the given permission (inPerm), you can use the stream with all
stream handling functions (refer to Stream handling functions on
page 209 for more information).
Parameters

inFilePath is the buffer that contains the pathname of the file for
which the stream must be created.
const char *inPerm

inPerm is the buffer that contains the open permission for the file,
for writing this is usually wb. You can use one of the following
permissions:
wb: opens the given file for writing. This function overwrites
existing content of the file.
ab: opens the file for writing at the end of the file. If the file does
not exist, the function creates the file.
rb+: opens the given file for both reading and writing. If the file
exists, the function overwrites the content. If the file does not exist
or the system cannot find the file, the function returns an error.
184
Stream Functions
wb+: opens the given file for both reading and writing. If the
given file exists, the function overwrites the content.
ab+: opens the given file for reading and writing at the end of the
file. If the file does not exist, the function creates the file.
Example
This example shows how to write data from a pool to a stream.
{
FPStreamRef vStream = FPStream_CreateFileForOutput (pPath, "wb");
// create a new binary file for write
if (vStream == 0)
return FPPool_GetLastError();
FPTag_BlobRead (inTag, vStream, 0);
// read stream has highest performance for downloading
// close file stream
}
Error handling


185
Stream Functions
FPStream_CreateGenericStream
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPStream_CreateGenericStream (const FPStreamProc

inPrepareBufferProc, const FPStreamProc
inCompleteProc, const FPStreamProc inSetMarkerProc,
const FPStreamProc inResetMarkerProc, const
FPStreamProc inCloseProc, const void *inUserData)
FPStreamRef
const FPStreamProc inPrepareBufferProc, const
FPStreamProc inCompleteProc, const FPStreamProc
inSetMarkerProc, const FPStreamProc inResetMarkerProc,
const FPStreamProc inCloseProc, const void *inUserData

This function allocates a stream data structure (FPStreamInfo),
declares its methods, and returns a reference to the created stream.
This function returns NULL if the stream has not been created.
If you want to extend the created generic stream, you must supply
one or more function pointers.
Note: If FP_OPTION_STREAM_STRICT_MODE is enabled (the default), the
SDK validates these FPStreamInfo fields: mVersion, MStreamLen,
mStreamPos, mMarkerPos, and mReadFlag. Table 14 on page 189 provides
more information.
Parameters
const void *inUserData
Any data that the application wants to pass to the method pointers.
The callback functions are of type FPStreamProc:
typedef long (*FPStreamProc) (FPStreamInfo*)
They take a pointer to FPStreamInfo as parameter and return an

error if unsuccessful or ENOERR if successful.
Note: The application must ensure that the callback functions are thread safe
and take no more than 1 minute to execute.
186
Stream Functions
In the following tables, input stream (to Atmos CAS) refers to a

stream from which the SDK has to read data, for example, when
writing a blob to the CAS-enabled node. Output stream (from Atmos
CAS) refers to a stream to which the SDK has to write data, for
example, when reading a blob from the CAS-enabled node.
Table 12 on page 187 and Table 13 on page 188 outline the input
action or value required for the corresponding FPStreamInfo fields
of each callback function. Table 14 on page 189 provides descriptions
of these callback items.
Table 12
FPStreamInfo
Callbacks
mVersion
Initialization
Set by SDK Initialize
mUserData
PrepareBuffer
Proc
As needed
CompleteProc
As needed
SetMarkerProc
As needed
ResetMarkerProc
As needed
CloseProc
As needed
Generic stream to Atmos CAS FPStreamInfo/callbacks

mStreamPos
mMarkerPos
mStreamLen
mAtEOF
0
Set to the total
number of bytes
that make up the
data source if
known, otherwise,
use -1.
Set to true if
Set to the total
number of bytes this is the last
that make up the buffer of data.
data source if
known, otherwise,
use -1.
+=mTransfer
Length
mReadflag
mBuffer
mTransferLen
Null
Allocate (if
Number of data
necessary) and bytes in buffer
populate
transfer buffer.
Free/release
buffer (if
applicable).
=mMarkerPos
Use to reset
current position
of data source.
Free/release
buffer (if
applicable).
187
Stream Functions
Table 13
FPStreamInfo
Callbacks
mVersion
Initialization
Set by SDK Initialize
mUserData
PrepareBuffer
Proc
As needed
CompleteProc
As needed
Generic stream from Atmos CAS FPStreamInfo/callbacks

mStreamPos
mMarkerPos
mStreamLen
mAtEOF
mReadflag
mBuffer
mTransferLen
Null
Allocate buffer Set max length

or set to 0 for of buffer.
SDK-supplied
buffer.
+=mTransfer
Length
Check for true,

signaling last
data buffer.
Retrieve data
from transfer
buffer, free
buffer if
needed.
SetMarkerProc
ResetMarkerProc
CloseProc
188
As needed
Free if using
application
buffer.
Stream Functions
Table 14
FPStreamInfo field descriptions per callback (page 1 of 12)

FPStreamInfo field
Description
PrepareBufferProc
Callback behavior
This method prepares a buffer that the stream can use. If the stream is
an input buffer, the callback method prepares a buffer that contains the
data. The mBuffer field of FPStreamInfo contains a pointer to the data.
If the stream is an output buffer, the function does nothing.
If you name your function myPrepareBuffer, declare it like this:
static long myPrepareBuffer (FPStreamInfo
*pStreamInfo)
pStreamInfo is a pointer to an FPStreamInfo structure. This
structure is allocated and maintained by the generic stream. You are
allowed to read and write fields from this structure. The exact meaning
of each field depends on the purpose of the stream: input or output.
The SDK calls myPrepareBuffer prior to transferring data from
the input stream to the Atmos CAS server. The SDK expects the
callback function to make the data available and provides a pointer to it
in mBuffer. The pointer to this data is owned by the SDK until the
completeProc is called. The prepareBufferProc is also
called before data is transferred from the Atmos CAS server to the
SDK. myPrepareBuffer could then be used to prepare the
output stream to receive data. In many cases, however, it is not
necessary to implement this function for output streams (pass NULL in
FPStream_CreateGenericStream()). If used for output
streams, myPrepareBuffer can put a pointer to the buffer that it
manages in mBuffer and to its length in mTransferLen.
If the inPrepareBufferProc callback method returns a
non-zero value, the SDK terminates the operation (for example,
reading a blob) with an FP_STREAM_VALIDATION_ERR error
and logs the appropriate information. No further processing can occur
on that stream in the scope of that operation.
mVersion
(short)
For an input /output stream:

The version of the FPStreamInfo structure. Currently, the value of this
field is 3. Check this field for backward compatibility. Do not modify this
field.
This is an SDK-validated field. If logging and the
FP_OPTION_STREAM_STRICT_MODE option (enabled by
default) are both turned on and the validation fails, the
FP_STREAM_VALIDATION_ERR is thrown with the following
error message. If only strict mode is on (logging is off) and an error
occurs, only the error message is thrown but with no logging. If an error
occurs with just logging enabled, the SDK sends the same message to
the log, but only as a warning.
The callback has changed the mVersion field.
It should never change in a callback.
189
Stream Functions
Table 14

FPStreamInfo field
Description
mUserData
(void*)
Parameter passed unchanged from FPStream_Create

GenericStream to each callback function. You can use this to
pass (a pointer to) myStream-specific data to the callback instead of
relying on global variables.
mStreamPos
(FPLong)
For an input/output stream:

Initialized at 0. The current position in the stream where input occurs.
Do not change this initial value before a read/write operation occurs. It
can be updated by myPrepareBuffer if needed.
The mStreamPos was not incremented by
mTransferLen in the prepare callback.
In strict mode, the SDK checks to ensure the current stream position is
incrementally based on the value specified in mStreamLen for the
number of passes made through the stream. Validation of this field also
occurs after a reset, which is equaled to 0, or after a resetMarker
occurs if implemented by the application. In this case, the resetMarker
is equaled to the value of mMarkerPos.
mMarkerPos
(FPBool)

Initialized at 0. If the stream implementation uses an offset field to
remember the marked position, mMarkerPos contains the position
of the mark. myResetMarker sets the stream to that position. For
file-based streams, myResetMarker does an fseek() on
mMarkerPos.
The mMarkerPos was changed incorrectly by the
resetMarker callback.
In strict mode, the SDK checks for this update. An error results if the
value of mMarkerPos does not match the current streamPos after the
mark call was made.
190
Stream Functions
Table 14

FPStreamInfo field
Description
mStreamLen
((FPLong)
For an input stream:

The total length of the stream. This is 1 (unknown) by default and is
updated by myPrepareBuffer. This field must be initialized and
set to 0 before the first call to prepareBuffer is made (before
FPTag_BlobWrite is called).
For an output stream:
Initialized at 0.
More data was written than the stream contains
(known stream lengths only).
In strict mode, if the amount of data written to the stream does not
match the amount of data in the stream, including any provision for an
offset, the result is an FP_STREAM_BYTECOUNT_MISMATCH
_ERR error and the following message:
Overwrite detected. More data was written than
the stream contains (known stream lengths
only).
mAtEOF
(FPBool)

Initialized at 0. Indicates whether or not myStream has reached the
end of the stream. myPrepareBuffer returns true in this field if
the last segment is read.
191
Stream Functions
Table 14

FPStreamInfo field
Description
mReadflag
(FPBool)
Indicates if myStream is used for reading (input) or writing (output).

The behavior of myPrepareBuffer might depend on the value of
this field.
Initialized to true (1).
Initialized to false (0).
The callback has changed the mReadFlag. It
should never change in a callback.
In strict mode, the SDK detects that a change to the stream type was
made after the operation initialized.
192
mBuffer
(void*)

Initialized at NULL. myPrepareBuffer should make mBuffer
point to a buffer containing data. Possibly myPrepareBuffer
must allocate memory, read data from a device into that memory, and
set mBuffer to point to it.
Initialized at NULL. This field should either be set to a stream-managed
buffer or left set to NULL.
mTransferLen
(FPLong)

Initialized at 0. mTransferLen indicates the maximum number of
bytes that the SDK wants to receive from the input.
myPrepareBuffer returns the actual number of bytes in
mBuffer in this field. If the buffer contains no data, mTransferLen =
0. If mTransferLen = 0 and mAtEOF is true, the end of the data stream
has been reached.
Initialized at 0. If myPrepareBuffer manages the output buffer,
mTransferLen is set to the size of that output buffer. The SDK
transfers the number of bytes into the output buffer that equals its size.
If the stream does not manage the output buffer, this field is unused.
Stream Functions
Table 14

FPStreamInfo field
Description
CompleteProc
Callback behavior
The generic stream calls this method when the buffer prepared with
inPrepareBufferProc is no longer needed. If the stream was
an input stream, this means the data has been processed successfully.
If the stream was an output stream, this means the buffer contains the
requested data and it can be written to an output device.
If you name your function myComplete, declare it like this:
static long myComplete (FPStreamInfo
*pStreamInfo)
myComplete actually transfers the data pointed to by mBuffer to
the output device. For a file, this might translate into an fwrite()
operation. The mBuffer pointer can either be provided by the
stream or by the SDK.
The end of the stream behaves as follows:
If the application allocated its buffer in prepareBufferProc,
the last completeProc callback has mTransferLen >= 0
and mAtEOF is true.
If the application did not allocate its buffer, the last call to
completeProc always has mTransferLen = 0 and
mAtEOF is true.
Note: If the SDK provides the mBuffer pointer to the stream to read
the output data, the callback function should never change this data.
The callback function notifies that the SDK has finished with the input
buffer (mBuffer). It can then unlock or deallocate the buffer if
necessary. In many cases, this callback is NULL for input streams.
Note: If the inCompleteProc callback method returns a
non-zero value, the SDK terminates the operation (for example,
reading a blob) with an FP_STREAM_VALIDATION_ERR error
and logs the appropriate information. No further processing can occur
on that stream in the scope of that operation.
mVersion
(short)
See mVersion on page 189.
193
Stream Functions
Table 14

FPStreamInfo field
Description
mUserData
(void*)
See mUserData on page 190.
mStreamPos
(FPLong)

Initialized at 0. The current position in the stream where input or output
occurs. This field is updated by myComplete if needed. It initializes
when myStream is created.
The mStreamPos was not incremented by
mTransferLen in the complete callback.
mMarkerPos
(FPBool)

mMarkerPos.
mark call was made.
194
Stream Functions
Table 14

FPStreamInfo field
Description
mStreamLen
((FPLong)
The total length of the stream.

Initialized at 1 by default (unknown) and is updated by
myComplete. If known, set to the total number of bytes of the data
source. It must be initialized and set to 0 before the first call to
prepareBuffer is made (before FPTag_BlobWrite is
called).
Initialized at 0.
More data was written than the stream contains
(known stream lengths only).
In strict mode, if the amount of data written to the stream does not
match the amount of data in the stream, including any provision for an
offset, the result is an FP_STREAM_BYTECOUNT_MISMATCH
_ERR error and the following message:
Overwrite detected. More data was written than
the stream contains (known stream lengths
only).
mAtEOF
(FPBool)
Indicates that the last buffer of data will now be written. If

mTransferLen = 0, no data is passed.
Initialized at 0.
Initialized at 0.
mReadflag
(FPBool)
See mReadflag on page 192.
mBuffer
(void*)

Initialized to NULL. Contains a pointer to the data that has been read
(as provided by an earlier call from myPrepareBuffer).
Initialized to NULL. Contains the address of a memory buffer that holds
the data that has to be written. If this pointer is owned by the SDK (refer
to prepareBufferProc) then the callback function is allowed to
access this memory during the execution of myComplete only.
195
Stream Functions
Table 14

FPStreamInfo field
Description
mTransferLen
(FPLong)

Initialized at 0. Contains the number of bytes that have been read (as
provided by an earlier call from myPrepareBuffer).
Initialized at 0. Contains the number of bytes that mBuffer points to.
This value can be 0 (in which case mAtEOF is true).
SetMarkerProc
Callback behavior
This method instructs the generic stream to mark the current position in
the stream. If the stream supports marking, the function can use the
mMarkerPos field to indicate the current position.
If you name your function mySetMarker, declare it like this:
static long mySetMarker (FPStreamInfo
*pStreamInfo)
The SDK sometimes needs to return to an earlier position in the
stream. To do this, it sets a mark at the current position in the stream
(how the current position is defined depends on the stream
implementation). If necessary, the SDK can return later to that position
by calling the resetMarkerProc.
If a stream does not support marking, pass NULL in
FPStream_CreateGenericStream.
Note: This callback function returns an error if unsuccessful or
ENOERR if successful. Any error from mySetMarker is currently
ignored by the SDK as it is not a fatal condition.
mUserData
(void*)
196
Stream Functions
Table 14

FPStreamInfo field
Description
mStreamPos
(FPLong)

occurs. mySetMarker updates this field to reflect the current
position in the stream. For a file-based stream, this is often an
ftell() call.
The mStreamPos has been incorrectly changed by
the setMarker callback.
mReadflag
(FPBool)
mMarkerPos
(FPLong)

mMarkerPos.
The mMarkerPos does not equal the mStreamPos
after a setMarker callback.
mark call was made.
197
Stream Functions
Table 14

FPStreamInfo field
Description
ResetMarkerProc
Callback behavior
This method tells the stream to go back to the marked position in the
stream (mMarkerPos).
If you name your function myResetMarker, declare it like this:
static long myResetMarker (FPStreamInfo
*pStreamInfo)
When the SDK needs to return to an earlier position in the stream
(indicated by calling setMarkerProc), it calls
resetMarkerProc.
If a stream does not support marking, then pass NULL in
FPStream_CreateGenericStream. When the SDK needs
this functionality, it exits with an
FP_OPERATION_REQUIRES_MARK error.
If the SDK attempts to return to a previously marked position in the
stream and the stream returns FP_OPERATION_REQUIRES
_MARK when the attempt is made, the SDK cannot continue with the
operation and propagates the FP_OPERATION_REQUIRES
_MARK error to the application.
mVersion
(short)
mUserData
(void*)
mStreamPos
(FPLong)

occurs. mySetMarker updates this field to reflect the current
position in the stream. For a file-based stream, this is often an
ftell() call.
The mStreamPos does not equal the mStreamPos
after a resetMarker callback.
198
Stream Functions
Table 14

FPStreamInfo field
Description
mMarkerPos
(FPBool)

mMarkerPos.
mark call was made.
mReadflag
(FPBool)
CloseProc
Callback behavior

Initialized at 0. This method informs that the application has performed
its operations on the stream and that the stream can clean up the
resources that it has allocated.
If you name your function myClose, declare it like this:
static long myClose (FPStreamInfo
*pStreamInfo)
This structure is allocated and maintained by the generic stream. You
are allowed to read and write fields from this structure. The exact
meaning of each field depends on the purpose of the stream: for input
or for output.
When the SDK has finished its operations on a stream, it calls the
closeProc callback function. myClose then has the chance to
close any opened resources (for example, a file or a network socket)
and to deallocate any memory if necessary. If no close function is
needed, NULL can be passed to
FPStream_CreateGenericStream.
199
Stream Functions
Table 14
Example

FPStreamInfo field
Description
mVersion
(short)
mUserData
(void*)
mStreamLen
(FPLong)
For an input stream only

If mReadFlag = true (1) , then mStreamLen applies. See page 191.
The following sample code shows how to build a stream

implementation on top of generic streams. Error handling, parameter
checking, and special cases are omitted for clarity.
File Input
This example creates a File Input stream. The parameters are a path to
the file, the file permissions, and the buffer size. A memory buffer is
allocated to read the file data. This buffer is deallocated in the close
method. The TStreamFileInfo is a structure holding some data
specific for file streams. A pointer to it is passed along using the
mUserData field.
EXPORT FPStreamRef FPStream_CreateFileForInput (const char *inFilePath, const

char *inPerm, const long inBuffSize)
{ TStreamFileInfo *vFileInfo = NULL;
char
*vBuffer = NULL;
FPStreamRef
vResult;
vFileInfo = (TStreamFileInfo*) calloc (1, sizeof (TStreamFileInfo));
vBuffer
= (char*) malloc (inBuffSize);
vFileInfo->mBufferLen = inBuffSize;
// build the access rights from the inPerm parameter here ..
vFileInfo->mFile = CreateFile (inFilePath, access, FILE_SHARE_READ, NULL,
createMode, FILE_ATTRIBUTE_NORMAL, NULL);
vResult = FPStream_CreateGenericStream (fileInPrepBuffer, NULL,
fileSetMarker, fileResetMarker,
fileClose, vFileInfo);
// set some FPStreamInfo fields
FPStreamInfo *vInfo = FPStream_GetInfo (vResult);
if (vInfo)
{ vInfo->mReadFlag = true; // indicate its an input stream
vInfo->mBuffer
= vBuffer; // set buffer
vInfo->mStreamLen = // get the file length;
200
Stream Functions
}
return vResult;
}
A part of the file is read into the buffer.

static long fileInPrepBuffer (FPStreamInfo *pStreamInfo)
{ TStreamFileInfo *vFileInfo = (TStreamFileInfo*) pStreamInfo->mUserData;
unsigned long
l;
if (ReadFile (vFileInfo->mFile, pStreamInfo->mBuffer,
vFileInfo->mBufferLen, &l, NULL) == 0)
return GetLastError ();
pStreamInfo->mTransferLen = l;
pStreamInfo->mStreamPos += l;
if (l < vFileInfo->mBufferLen)
pStreamInfo->mAtEOF = true;
return ENOERR;
}
The marker methods use a type of seek() function to set and get the
current position in the file that is read or written. The offset is kept in
the mMarker field (which is only used by stream handling functions
and will not be changed by generic streams).
static long fileSetMarker (FPStreamInfo *pStreamInfo)
pStreamInfo->mMarkerPos = myFileSeek (vFileInfo->mFile, 0, FILE_CURRENT);
return ENOERR;
}
static long fileResetMarker (FPStreamInfo *pStreamInfo)
myFileSeek (vFileInfo->mFile, pStreamInfo->mMarkerPos, FILE_BEGIN);
pStreamInfo->mStreamPos = pStreamInfo->mMarkerPos;
return ENOERR;
}
This method deallocates the buffer (allocated in the stream creation

function) and closes the file.
static long fileClose (FPStreamInfo *pStreamInfo)
CloseHandle (vFileInfo->mFile);
if (vFileInfo->mBufferLen > 0)
free (pStreamInfo->mBuffer);
201
Stream Functions
free (vFileInfo);
return ENOERR;
}
File Output
This method is very similar to the stream creation function for File
Input. The main difference is that no memory buffer is allocated.
EXPORT FPStreamRef FPStream_CreateFileForOutput (const char *inFilePath, const
char *inPerm)
{ TStreamFileInfo *vFileInfo = NULL;
FPStreamRef
vResult;
vFileInfo = (TStreamFileInfo*) calloc (1, sizeof (TStreamFileInfo));
// get the access rights from the inPerm parameter..
vFileInfo->mFile = CreateFile (inFilePath, access, FILE_SHARE_READ, NULL,
createMode, FILE_ATTRIBUTE_NORMAL, NULL);
vResult = FPStream_CreateGenericStream (NULL, fileOutComplete,
fileSetMarker, fileResetMarker,
fileClose, vFileInfo);
FPStreamInfo *vInfo = FPStream_GetInfo (vResult);
if (vInfo)
{ vInfo->mReadFlag = false; // stream is for output
vInfo->mStreamLen = // get file length (usually = 0)
}
return vResult;
}
This method writes the data pointer to mBuffer into a file. The call
back function returns an error value to the application to stop
FPTag_BlobRead from the stream.
static long fileOutComplete (FPStreamInfo *pStreamInfo)
unsigned long
l;
if (WriteFile (vFileInfo->mFile, pStreamInfo->mBuffer,
pStreamInfo->mTransferLen, &l, NULL) == 0)
{ return FP_OPERATION_NOT_SUPPORTED1;
}
pStreamInfo->mTransferLen = l;
pStreamInfo->mStreamPos += l;
1. Or any other error value. The error value will be returned to the application.
202
Stream Functions
return ENOERR;
}
Error handling


Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPStream_CreatePartialFileForInput (const char

*inFilePath, const char *inPerm, const long
inBuffSize, const long inOffset, const long inLength)
FPStreamRef
inBuffSize, const long inOffset, const long inLength

This function creates a stream to read from a file and returns a
reference to the created stream. The stream behaves like a file and
depending on the given permission (inPerm), you can use the stream
with most of the stream handling functions (refer to Section Stream
handling functions on page 209 for more information).
This API call allows applications to simplify the handling of large
files for input into Atmos CAS by allowing a large file to be divided
into multiple streams and processed with multiple threads via
FPTag_BlobWritePartial().
Parameters

const char *inPerm

You can use the following permission:

rb: opens the given file for reading. If the file does not exist or the
system cannot find the file, the function returns an error.
203
Stream Functions

reading the file. This size represents the amount of data to

retrieve or cache from the file into memory each time the file is
touched. This value must be greater than 0.
const long inOffset

inOffset is the offset into the file (in bytes) from which Atmos
CAS starts the read.
const long inLength

inLength is the amount of data (in bytes) from the offset to be
transferred in the stream. Use FP_STREAM_EOF to request all
remaining data in the file from the given offset.

Example
This example shows how to stream the data to a pool.
{ FPStreamRef vStream = FPStream_CreatePartialFileForInput (pPath, "rb",

16*1024, 0, 100);
// Write 100 bytes from offset 0
if (vStream != 0)
{ FPTag_BlobWritePartial (vFileTag, vStream, FP_OPTION_CLIENT_CALCID,
seqID);
}
}
Error handling

204

Stream Functions
Syntax
Return value
Input parameters
FPStream_CreatePartialFileForOutput (const char

*inFilePath, const char *inPerm, const long
inBuffSize, const long inOffset, const long inLength,
const long inMaxFileLength)
FPStreamRef
inBuffSize, const long inOffset, const long inLength
Concurrency
requirement
This function is thread safe, however, with an exception. This call is

not thread safe when it writes to the same file from multiple threads.
In this case, if multiple streams are created and open the same file for
writing, an FP_FILESYS_ERR results for all created streams except the
first stream (until the initial stream closes). Only one stream may
write to a given file at a time.
Description
This function creates a stream to write to a file and returns a reference

to the created stream. The stream behaves like a file and depending
on the given permission (inPerm), you can use the stream with most
of the stream handling functions (refer to Section Stream handling
functions on page 209 for more information).
This API call allows applications to simplify the handling of large
files for output from Atmos CAS by allowing a large file to be divided
into multiple streams and processed with multiple threads via
FPTag_BlobWritePartial().
Parameters

const char *inPerm

For partial writes, ab+ is typically used. However, you can use
any of the following permissions:
wb: opens the given file for writing. This function overwrites
existing content of the file.
ab: opens the file for writing at the end of the file. If the file does
not exist, the function creates the file.
205
Stream Functions
rb+: opens the given file for both reading and writing. If the file
exists, the function overwrites the content. If the file does not exist
or the system cannot find the file, the function returns an error.
wb+: opens the given file for both reading and writing. If the
given file exists, the function overwrites the content.
ab+: opens the given file for reading and writing at the end of the
file. If the file does not exist, the function creates the file.

reading the file. This size represents the amount of data to

retrieve or cache from the data source into memory. This value
must be greater than 0.
const long inOffset

inOffset is the offset into the file (in bytes) in which Atmos CAS
begins the write.
const long inLength

inLength is the maximum amount of data (in bytes) this stream
can accept. A value of -1 indicates that this stream can accept data
up to the value specified in inMaxFileLength. If the
inMaxFileLength is out of bounds (for example, !=-1 AND <-1
or >= (inFileLength-inOffset)), the SDK generates an
FP_PARAM_ERR and returns a NULL FPStreamRef.
const long inMaxFileLength

inMaxFileLength is the maximum overall amount of data that
can be written to the underlying file, which the stream accesses.

This defines the maximum size a file may be allowed to grow. If
the file size on the disk exceeds this size, the file is truncated. A
value of -1 indicates that there is no overall maximum data
length.
Example
This example shows how to stream the data to a pool.
{ FPStreamRef vStream = FPStream_CreatePartialFileForOutput (pPath, "ab+",

16*1024, 0, 100, vFileMaxSize);
// Read 100 bytes to offset 0
if (vStream != 0)
206
Stream Functions
{ FPTag_BlobReadPartial (vFileTag, vStream, 0, 100,

}
}
Error handling


FPStream_CreateTemporaryFile
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_CreateTemporaryFile (const long inMemBuffSize)

FPStreamRef
const long inMemBuffSize
Description
This function creates a stream for temporary storage and returns a

reference to the created stream. If the length of the stream exceeds
inMemBuffSize, the overflow is flushed to a temporary file in the
platform-specific temporary directory. This temporary file is
automatically deleted when the stream closes.
Parameters
const long inMemBuffSize

inMemBuffSize is the size of the memory buffer.
Example
Error handling
myStream = FPStream_CreateTemporaryFile(2048);
* Use a 2048 byte in memory buffer for the file.

207
Stream Functions
FPStream_CreateToNull
Syntax
Return value
Concurrency
requirement
FPStream_CreateToNull (void)
FPStreamRef
Description
This function creates a stream for output but does not write the bytes.
This function returns a reference to the created stream.
Parameters
void
Error handling
FPPool_GetLastError() returns ENOERR if successful.
FPStream_CreateToStdio
Syntax
Return value
Concurrency
requirement
FPStreamRef
Description
This function creates a stream for output to the console. The stream
can be used only for writing. This function returns a reference to the
created stream.
Parameters
void
Error handling
208
FPStream_CreateToStdio (void)
FPPool_GetLastError() returns ENOERR if successful.
Stream Functions
Stream handling functions

This section describes the FPStream functions for handling a stream:
FPStream_Close
FPStream_Complete
FPStream_GetInfo
FPStream_ResetMark
FPStream_SetMark
FPStream_Close
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPStream_Close (const FPStreamRef inStream)

void

This function closes the given stream. Note that calling this function
on a stream that has already been closed may produce unwanted
results.
Note: Always use this function to close streams that are no longer needed in
order to prevent memory leaks.
Parameters

Example
Error handling
FPStream_Close (myStream);
FP_WRONG_REFERENCE_ERR (program logic error)(internal error)
209
Stream Functions
FPStream_Complete
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPStream_Complete (const FPStreamRef inStream)

FPStreamInfo*
This function is thread safe if the callback function is thread safe.

This function calls completeProc from the stream. completeProc
was previously passed to FPStream_CreateGenericStream. If no
completeProc callback is defined for this stream, then the function
does nothing.
This function returns a pointer to the StreamInfo structure. This
pointer is identical to the one that is returned by FPStream_GetInfo.
Parameters
The reference to a stream as created by

FPStream_CreateGenericStream().
Example
Error handling
Refer to the EMC Atmos CAS Programmers Guide, for information

about code examples provided with the SDK package.
210

Stream Functions
FPStream_GetInfo
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_GetInfo (const FPStreamRef inStream)

FPStreamInfo*
Description
This function returns information about the given stream.
Parameters
The reference to a stream.

Example
Error handling
Refer to the example section of FPStream_CreateGenericStream on

page 186 for an example of FPStream_GetInfo().
211
Stream Functions
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPStream_PrepareBuffer (const FPStreamRef inStream)

FPStreamInfo*

This function sets mBuffer and mTransferLen for an output stream
to NULL. The SDK can thus detect that the application has provided a
buffer. If mBuffer is NULL when the SDK wants to write data, it
provides a pointer to its own buffer.
This function then calls the prepareBufferProc from the stream.
prepareBufferProc was previously passed to
FPStream_CreateGenericStream. If no prepareBufferProc
callback is defined for this stream, then the function does nothing.
This function returns a pointer to the StreamInfo structure. This
pointer is identical to the one that is returned by FPStream_GetInfo.
Parameters

Example
Error handling

212

Stream Functions
FPStream_ResetMark
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPStream_ResetMark (const FPStreamRef inStream)

void

This function calls resetMarkerProc from the stream.
resetMarkerProc was previously passed to
FPStream_CreateGenericStream. If no resetMarkerProc callback
is defined for this stream, then the function returns the error
FP_OPERATION_REQUIRES_MARK unless the current position in the
stream equals the marked position (the fields mMarkerPos and
mStreamPos in FPStreamInfo are equal).
Parameters

Example
Error handling


FP_OPERATION_REQUIRES_MARK (program logic error)
213
Stream Functions
FPStream_SetMark
Syntax
Return value
Input parameters
Concurrency
requirement
FPStream_SetMark (const FPStreamRef inStream)

void
Description
This function calls setMarkerProc from the stream. setMarkerProc

was previously passed to FPStream_CreateGenericStream. If no
setMarkerProc callback is defined for this stream, then the function
returns the error FP_OPERATION_REQUIRES_MARK. The application
usually ignores this error.
Parameters

Example
Error handling

214

FP_OPERATION_REQUIRES_MARK (program logic error)
Invible Body Tag
Query Functions
This chapter describes the various types of FPQuery API functions.

Query functions................................................................................
Query expression functions............................................................
Pool query functions........................................................................
Query result functions.....................................................................
Query Functions
216
217
230
236
215
Query Functions
Query functions
The Access API provides functions that query C-Clips both
existing and deleted (reflections) stored on an Atmos CAS-enabled
node.
The query feature is intended for backup applications and not as a
general-purpose application feature. Refer to the EMC Atmos CAS
Programmers Guide for more information on the query feature.
This section describes the following types of query functions:
216
Query expression functions

Query Functions

This section describes the query expression functions that are used to
create, define, close, and manipulate (elements of) a query
expression:
FPQueryExpression_Close
FPQueryExpression_Create
FPQueryExpression_GetEndTime
FPQueryExpression_GetStartTime
FPQueryExpression_GetType
FPQueryExpression_SetEndTime
FPQueryExpression_SetStartTime
FPQueryExpression_SetType
217
Query Functions
FPQueryExpression_Close
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_Close (const FPQueryExpressionRef

inRef)
void
const FPQueryExpressionRef inRef
Description
This function closes the query expression and releases all allocated
resources. Call this function when your application no longer needs
the FPQueryExpressionRef object. Note that calling this function on
a query expression that has already been closed may produce
unwanted results.
Parameters
The reference to a query expression as returned from

FPQueryExpression_Create().
Example
Error handling
FPQueryExpression_Close (myQueryExp);
FPQueryExpression_Create
Syntax
Return value
Concurrency
requirement
Description
FPQueryExpression_Create (void)
FPQueryExpressionRef

This function creates a query expression, which defines the
conditions used to query the pool. You must call
FPQueryExpression_Create() before calling FPPoolQuery_Open().
You can modify the conditions for the query by calling
FPQueryExpression_SetStartTime(),
FPQueryExpression_SetEndTime(), and
218
Query Functions
FPQueryExpression_SetType(). By default, the query expression

queries all existing C-Clips (start time = 0, end time = -1, type =
FP_QUERY_TYPE_EXISTING).
You specify what description attributes, if any, you want included in

the query results by calling FPQueryExpression_SelectField(). By
default, the query returns no description attributes, so the application
only has access to the Clip ID of returned C-Clips.
When your query is complete, call FPQueryExpression_Close() to
free any allocated resources.
Parameters
Example
void
FPQueryExpressionRef myQueryExp = 0;
myQueryExp = FPQueryExpression_Create();
Error handling

FP_OUT_OF_MEMORY_ERR (client error)
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPQueryExpression_DeselectField (const
FPQueryExpressionRef inRef, const char *inAttrName)
void
const FPQueryExpressionRef inRef, const char *inAttrName

This function removes a previously selected description attribute
from being included in the query result. No error is returned if the
query expression does not contain the specified attribute; that is, the
attribute was not previously selected using
FPQueryExpression_SelectField().
Refer to FPQueryExpression_SelectField on page 224 for
information on description attributes.
Parameters

219
Query Functions
The name of a description attribute.

Example
char* Company = "Company XYZ";

FPQueryExpression_DeselectField (myQuery, Company);
Error handling

FPQueryExpression_GetEndTime
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_GetEndTime (const FPQueryExpressionRef

inRef)
FPLong
Description
This function returns the end time (latest creation or deletion date) for
which C-Clips are queried, as set by
FPQueryExpression_SetEndTime(). End time is measured in
milliseconds since 00:00:00 on January 1, 1970 (the UNIX/Java
epoch). An end time of -1 corresponds to the current time.
Parameters

Example
Error handling
EndTime = FPQueryExpression_GetEndTime (myQueryExp);

220
Query Functions
FPQueryExpression_GetStartTime
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_GetStartTime (const
FPQueryExpressionRef inRef)
FPLong
Description
This function returns the start time (earliest creation or deletion date)
for which C-Clips are queried, as set by
FPQueryExpression_SetStartTime(). Start time is measured in
milliseconds since 00:00:00 on January 1, 1970 (the UNIX/Java
epoch).
Parameters

Example
Error handling
StartTime = FPQueryExpression_GetStartTime (myQueryExp);

221
Query Functions
FPQueryExpression_GetType
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPQueryExpression_GetType (const FPQueryExpressionRef

inRef)
FPInt

This function returns the query typeexisting C-Clips, deleted
C-Clips (reflections), or bothas set by
FPQueryExpression_SetType(). Possible values are:
FP_QUERY_TYPE_EXISTING Queries only existing C-Clips, not
reflections.
FP_QUERY_TYPE_DELETED Queries only reflections.
FP_QUERY_TYPE_EXISTING | FP_QUERY_TYPE_DELETED
Queries both existing C-Clips and reflections.

Parameters

Example
Error handling
queryType = FPQueryExpression_GetType (myQueryExp);

222
Query Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_IsFieldSelected (const
FPBool
Description
This function returns true if the description attribute is included in

the query expression and false otherwise. Refer to
FPQueryExpression_SelectField on page 224 for more information.
Parameters

The name of a C-Clip description attribute.

Example
Error handling
if (FPQueryExpression_IsFieldSelected (myQuery, Company))

{...}
223
Query Functions
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPQueryExpression_SelectField (const
void

This function includes a specified description attribute in the query
result. No error is returned if the C-Clip does not contain the
specified attribute.
Note: Including a description attribute does not affect the list of C-Clips
returned by the query. Only the start time, end time, and query type affect
which C-Clips are returned. Your application must process the query results
to filter based on description attributes.
You can include both standard and user-defined attributes in a query

expression. For information on user-defined attributes, refer to
FPClip_SetDescriptionAttribute on page 108. Table 15 on page 224
lists the standard C-Clip attributes. Table 16 on page 225 lists the
standard reflection attributes.
Table 15
224
Standard C-Clip description attributes (page 1 of 2)

Attribute name
Description
name
The name of the C-Clip. Refer to FPClip_AuditedDelete

on page 61 and FPClip_GetName on page 91.
creation.date
The timestamp when the C-Clip was created. Refer to

FPClip_AuditedDelete on page 61 and
FPClip_GetCreationDate on page 87.
modification.date
The timestamp when the C-Clip was written to the

CAS-enabled node. Refer to FPClip_Write on page 79.
creation.profile
The profile used by the application that created the

C-Clip.
modification.profile
The profile used by the application that wrote the

modified C-Clip to the CAS-enabled node.
Query Functions
Table 15
Table 16
Standard C-Clip description attributes (page 2 of 2)

Attribute name
Description
numfiles
The number of referenced blobs. Refer to

FPClip_GetNumBlobs on page 92.
totalsize
The total size of referenced blobs. This size does not

include the CDF itself. Refer to
FPClip_GetRetentionClassName on page 95.
prev.clip
The Clip ID of the C-Clip that was modified to create this

C-Clipl
clip.naming.scheme
The C-Clip naming scheme: MD5 or MG.
numtags
The number of tags in the C-Clip. Refer to

FPClip_GetNumTags on page 93.
sdk.version
The version of the SDK used to create the C-Clip. Refer

to FPPool_GetComponentVersion on page 39.
retention.period
The retention period, in seconds. Only present if a

retention period has been assigned to this C-Clip. Refer
to FPClip_SetRetentionPeriod on page 77.
retention.class
The name of a retention class. Only present if a retention

class has been assigned to this C-Clip. Refer to
FPClip_SetRetentionClass on page 76.
Standard reflection description attributes (page 1 of 2)

Attribute name
Description
principal
The profile name used by the application that deleted the

C-Clip.
incomingip
The IP address of the machine hosting the application

that deleted the C-Clip.
creation.date
The timestamp of when the C-Clip was deleted (creation

date of the reflection).
225
Query Functions
Table 16
Parameters
Standard reflection description attributes (page 2 of 2)

Attribute name
Description
deletedsize
The size of the deleted C-Clip and all referenced blobs.

Note that this size may not represent the amount of data
actually deleted, because blobs referenced by multiple
C-Clips would not have been deleted.
reason
The audit string provided when the C-Clip was deleted.

Refer to FPClip_AuditedDelete on page 61 for more
information.
All standard attributes of the

deleted C-Clip.
A reflection retains all the standard attributes of the

original C-Clip.

The name of a description attribute.

Example
Error handling
char* Company = "Company";

FPQueryExpression_SelectField(myQuery, Company);
226
Query Functions
FPQueryExpression_SetEndTime
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_SetEndTime (const FPQueryExpressionRef

inRef, const FPLong inTime)
void
const FPQueryExpressionRef inRef, const FPLong inTime
Description
This function sets the query condition that C-Clips retrieved by the
query result have a creation or deletion time no later than the
specified time. If an end time is not set, the default is -1 (current time).
The storage time refers to the time that a C-Clip is actually stored on a
CAS-enabled node when the C-Clip was written or replicated. In the
case of querying a replica cluster, the time used in a query for any
replicated C-Clips is based on the storage time of when those C-Clips
arrived at the replica node.
Parameters

const FPLong inTime
The latest storage or deletion time (not inclusive) of C-Clips to be

returned by the query. Specify the time in milliseconds since
00:00:00 on January 1, 1970 (the UNIX/Java epoch). The time is
based on the UTC (Coordinated Universal Time, also known as
GMTGreenwich Mean Time) of the system clock of the Atmos
CAS cluster that stores the C-Clips. A value of -1 or
FP_QUERY_END_TIME_UNBOUNDED corresponds to the current time.
Note: For more information on timestamps, refer to Chapter 6, Best Practices,
in the EMC Atmos CAS Programmers Guide.
Example
Error handling
FPQueryExpression_SetEndTime (myQueryExp,
FP_QUERY_END_TIME_UNBOUNDED);
227
Query Functions
FPQueryExpression_SetStartTime
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_SetStartTime (const
FPQueryExpressionRef inRef, const FPLong inTime)
void
const FPQueryExpressionRef inRef, const FPLong inTime
Description
This function sets the query condition that C-Clips retrieved by the
query have a storage or deletion time later than the specified time. If a
start time is not set, the default is 0 (the earliest possible time). The
storage time refers to the time that a C-Clip is actually stored on a
CAS-enabled node when the C-Clip was written or replicated. In the
case of querying a replica CAS-enabled node, the time used in a
query for any replicated C-Clips is based on the storage time of when
those C-Clips arrived at the replica node.
Parameters

const FPLong inTime
The earliest storage or deletion time (inclusive) of C-Clips to be

returned by the query. Specify the time in milliseconds since
00:00:00 on January 1, 1970 (the UNIX/Java epoch). The time is
based on the UTC (Coordinated Universal Time, also known as
GMTGreenwich Mean Time) of the system clock of the Atmos
CAS-enabled node that stores the C-Clips. If inTime is 0 or
FP_QUERY_START_TIME_UNBOUNDED, the function queries all
C-Clips stored or deleted on one or more CAS-enabled nodes up
to the specified stop time. Refer to
FPQueryExpression_SetEndTime().
Note: For more information on timestamps, refer to Chapter 4, Best Practices,
in the EMC Atmos CAS Programmers Guide.
Example
Error handling
228
FPQueryExpression_SetStartTime (myQueryExp, 10000);

Query Functions
FPQueryExpression_SetType
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryExpression_SetType (const FPQueryExpressionRef

inRef, const FPInt inType)
void
const FPQueryExpressionRef inRef, const FPInt inType
Description
This function specifies what C-Clip types to query: existing C-Clips,

deleted C-Clips (reflections), or both.
Parameters

const FPInt inType
The type of C-Clips to query. Choices are:

FP_QUERY_TYPE_EXISTING Query only existing C-Clips,
not reflections.
FP_QUERY_TYPE_DELETED Query only reflections.
FP_QUERY_TYPE_EXISTING | FP_QUERY_TYPE_DELETED
Query both existing C-Clips and reflections.
Example
Error handling
FPQueryExpression_SetType (myQueryExp,
FP_QUERY_TYPE_EXISTING | FP_QUERY_TYPE_DELETED);
229
Query Functions

This section describes the pool query functions that act upon an
existing pool query:
230
FPPoolQuery_Close
FPPoolQuery_FetchResult
FPPoolQuery_GetPoolRef
FPPoolQuery_Open
Query Functions
FPPoolQuery_Close
Syntax
Return value
Input parameters
Concurrency
requirement
FPPoolQuery_Close (const FPPoolQueryRef inPoolQueryRef)

void
const FPPoolQueryRef inPoolQueryRef
Description
This function closes a query on the pool and frees all associated
(memory) resources. Note that calling this function on a pool query
that has already been closed may produce unwanted results.
Parameters

The reference to a pool query opened by FPPoolQuery_Open().
Example
Error handling
FPPoolQuery_Close (myPoolQuery);
FPPoolQuery_FetchResult
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPPoolQuery_FetchResult (const FPPoolQueryRef

inPoolQueryRef, const FPInt inTimeout)
FPQueryResultRef
const FPPoolQueryRef inPoolQueryRef, const FPInt
inTimeout

This function returns a query result. This function queries each
C-Clip or reflection in time ascending order (from earliest to latest
creation or deletion date). This function returns the query result in a
QueryResult object. Process the query results with the
FPQueryResult_XXX() functions.
231
Query Functions
Check the query status after each call to

FPPoolQuery_FetchResult(). Refer to
FPQueryResult_GetResultCode on page 239.
Call FPQueryResult_Close() after each call to
FPPoolQuery_FetchResult() to free all associated (memory)
resources.
Parameters

const FPInt inTimeout
The time in milliseconds that the function waits for the next
result. If inTimeout = -1, the function uses the default timeout of
120000 ms (2 minutes). The maximum timeout is 600000 (10
minutes).
Note: Specifying a timeout value that is less than the default timeout of
120000 ms (2 minutes) may result in the system error code
FP_QUERY_RESULT_CODE_ERROR.
Example
Error handling
myQueryResult = FPPoolQuery_FetchResult (myPoolQuery,

600000);
232

Query Functions
FPPoolQuery_GetPoolRef
Syntax
Return value
Input parameters
Concurrency
requirement
FPPoolQuery_GetPoolRef (const FPPoolQueryRef

inPoolQueryRef)
FPPoolRef
Description
This function returns the pool associated with a pool query. Refer to
FPPoolQuery_Close on page 231 for more information.
Parameters

Example
Error handling
myPool = FPPoolQuery_GetPoolRef (myPoolQuery);


FP_QUERYCLOSED_ERR (client error)
233
Query Functions
FPPoolQuery_Open
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPPoolQuery_Open (const FPPoolRef inPoolRef,

FPQueryExpressionRef inQueryExpressionRef)
FPPoolQueryRef
const FPPoolRef inPoolRef, FPQueryExpressionRef
inQueryExpressionRef)

This function returns a reference to an open PoolQuery object. This
function initiates a pool query. Iteratively call
FPPoolQuery_FetchResult() to return query results.
The query conditions are specified by a query expression that you
previously defined with FPQueryExpression_xxx functions. Refer to
FPQueryExpression_Close on page 218 for more information.
Note: The CAS-enabled node allows the application to perform this call only
if the "clip-enumeration" capability is enabled. If this capability is disabled,
the error FP_OPERATION_NOT_ALLOWED is returned.
Note: The maximum number of parallel queries to one or more CAS-enabled

nodes is 10.
When your query is complete, call FPPoolQuery_Close() to free any

allocated resources.
Parameters
FPQueryExpressionRef inQueryExpressionRef
The reference to a query expression created by

FPQueryExpression_Create(). The query expression defines
the conditions for the query.
234
Query Functions
Example
FPPoolQueryRef myPoolQuery = 0;
myPoolQuery = FPPoolQuery_Open(myPool, myQueryExp);
Error handling


235
Query Functions

This section describes the query result functions that retrieve a query
result, including one that closes a query result.
FPQueryResult_Close
FPQueryResult_GetClipID
FPQueryResult_GetResultCode
FPQueryResult_GetTimestamp
FPQueryResult_GetType
FPQueryResult_Close
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPQueryResult_Close (const FPQueryResultRef

inQueryResultRef)
void
const FPQueryResultRef inQueryResultRef

This function closes a query result as returned by
FPPoolQuery_FetchResult() and frees all associated (memory)
resources. Call this function after each call to

FPPoolQuery_FetchResult(). Note that calling this function on a
query result that has already been closed may produce unwanted
results.
Parameters
A reference to a query result as returned by

FPPoolQuery_FetchResult().
Example
Error handling
FPQueryResult_Close (myQueryResult);
236
Query Functions
FPQueryResult_GetClipID
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPQueryResult_GetClipID (const FPQueryResultRef

inQueryResultRef, FPClipID outClipID)
void
FPClipID outClipID
Description
This function retrieves the ID of the C-Clip associated with the

specified query result.
Parameters

FPClipID outClipID
The C-Clip ID associated with the query result.

Example
Error handling
FPClipID myClipID;
FPQueryResult_GetClipID (myQueryResult, myClipID);

237
Query Functions
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPQueryResult_GetField (const FPQueryResultRef

inQueryResultRef, const char *inAttrName, char
*outAttrValue, FPInt *ioAttrValueLen)
void
const FPQueryResultRef inQueryResultRef, const char
*inAttrName, FPInt *ioAttrValueLen
char *outAttrValue, FPInt *ioAttrValueLen
Description
This function retrieves the value of the given attribute from the
C-Clip or reflection associated with the given query result. The
application must have called FPQueryExpression_SelectField()
to indicate that the attribute should be returned by the query.
Parameters

The buffer that contains the name of the attribute for which the
value is retrieved.
const char *outAttrValue
The buffer that will hold the attribute value.
Input: The length in characters of outAttrValue.

Example
Error handling
char vBuffer[1024];
FPInt len=sizeof(vBuffer);
FPQueryResult_GetField(myQueryResult, "Company",
vBuffer, &len);
238

Query Functions
FPQueryResult_GetResultCode
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPQueryResult_GetResultCode (const FPQueryResultRef

inQueryResultRef)
FPInt

This function returns the result code of the specified query result, as
returned by FPPoolQuery_FetchResult(). Possible values are:
FP_QUERY_RESULT_CODE_OK The query result is valid and can
be processed by the application.
FP_QUERY_RESULT_CODE_INCOMPLETE The query result may be
incomplete because one or more nodes could not be queried. It is

recommended that the query be restarted from the last valid
timestamp before FP_QUERY_RESULT_CODE_INCOMPLETE was
returned.
FP_QUERY_RESULT_CODE_COMPLETE This value is always

returned after FP_QUERY_RESULT_CODE_INCOMPLETE. Although
the results of the query are complete, they may not be valid
because one or more nodes could not be queried. This value
indicates that all nodes can be queried again.
FP_QUERY_RESULT_CODE_END The query is finished; no more
query results are expected.
FP_QUERY_RESULT_CODE_ABORT The query has aborted due to
a problem on one or more CAS-enabled nodes or because the

start time for the query expression is later than the current server
time. Check the start time and retry the query.
FP_QUERY_RESULT_CODE_PROGRESS The query is in progress.
FP_QUERY_RESULT_CODE_ERROR An error has been detected

during the execution of this call. Check FPPool_GetLastError()
to get the Atmos CAS error code. In the case where

FP_SOCKET_ERR has been returned, call
FPPool_GetLastErrorInfo() to check the OS-dependent error
code. If this error refers to a timeout (for example, 10060 on
Windows), it is recommended that you retry the query.
Otherwise, return the error code when the call has been executed.
239
Query Functions
Note: A call to FPPoolQuery_FetchResult that specifies a timeout

value less than the default timeout of 120000 ms (2 minutes) may result
in this system error code.
Parameters

Example
Error handling
ResultCode = FPQueryResult_GetResultCode (myQueryResult);

FPQueryResult_GetTimestamp
Syntax
Return value
Input parameters
Concurrency
requirement
FPQueryResult_GetTimestamp (const FPQueryResultRef

inQueryResultRef)
FPLong
Description
This function returns the timestamp from the query result. For
existing C-Clips, the timestamp is when the C-Clip was created on
one or more CAS-enabled nodes. For reflections (deleted C-Clips), the
timestamp is when the C-Clip was deleted from the nodes. This
function returns the timestamp in milliseconds since 00:00:00 on
January 1, 1970 (the UNIX/Java epoch).
Parameters

Example
Error handling
myTime = FPQueryResult_GetTimestamp (myQueryResult);

240
Query Functions
FPQueryResult_GetType
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPQueryResult_GetType (const FPQueryResultRef

inQueryResultRef)
FPInt

This function returns the type of C-Clip, existing or deleted,
associated with the query result. Possible values are:
FP_QUERY_TYPE_EXISTING The C-Clip exists on one or more
CAS-enabled nodes.
Parameters
FP_QUERY_TYPE_DELETED The C-Clip has been deleted from

one or more CAS-enabled nodes.

Example
Error handling
CClipType = FPQueryResult_GetType (myQueryResult);

241
Query Functions
242
Invible Body Tag
Time Functions
This chapter describes the time API functions.

Time functions .................................................................................. 244
Time Functions
243
Time Functions
Time functions
This section describes the following time formats used by the SDK to
convert Atmos CAS time strings to integral time values marking the
time since the epoch 1 January 1970 00:00:00.000 GMT. These API
calls represent integral units in either seconds or milliseconds.
The SDK supports two string formats when converting the integral
values to time strings. These string formats are defined as options
FP_OPTION_MILLISECONDS_STRING and
FP_OPTION_SECONDS_STRING with a flag argument. The inOptions
argument produces a time string with or without a milliseconds field.
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
FPTime_MillisecondsToString (FPLong inTime,

char* outString, int* ioStringLen, int inOptions)
void
FPLong inTime
char* outString, int* ioStringLen, int inOptions
Unicode support
Description
This function converts an FPLong that represents the number of

milliseconds since the epoch 1 January 1970 00:00:00.000 GMT
(Greenwich Mean Time) to a date-time string of the form YYYY.MM.DD
hh:mm:ss.ms GMT. The function does not support time strings before
the epoch.
For example, March 31, 2005 might be expressed as 2005.03.31
15:14:30.585 GMT.
244
Time Functions
Parameters
const FPLong inTime
The reference to the number of milliseconds since the epoch.
char* outString
A pointer to a user-allocated buffer that holds the resulting time

string.
int* ioStringLen
Input: The pointer to an integer that holds the length of the buffer
allocated for outString.
Output: The integer is updated to hold the length of the resulting
string.
int inOptions
Specify either FP_OPTION_MILLISECONDS_STRING to produce a
string containing a milliseconds field or

FP_OPTION_SECONDS_STRING to produce a string without a
milliseconds field.
Example
Error handling
char vTimeString[MAX_STRING_LEN];
FPInt vTimeStringLen = MAX_STRING_LEN;
FPTime_LongToString(vTimeInSeconds, vTimeString,
&vTimeStringLen);

Time functions
245
Time Functions
Syntax
Return value
Input parameters
Output parameters
Concurrency
requirement
Unicode support
FPTime_SecondsToString (FPLong inTime,

char* outString, int* ioStringLen, int inOptions)
void
FPLong inTime, int inOptions
char* outString, int* ioStringLen

Description
This function converts an FPLong that represents the number of

seconds since the epoch 1 January 1970 00:00:00.000 GMT to a
date-time string of the form YYYY.MM.DD hh:mm:ss.ms GMT.
The function does not support time strings before the epoch.
Parameters
const FPLong inTime
The reference to the number of seconds since the epoch.
char* outString
A pointer to a user-allocated buffer that holds the resulting time

string.
int* ioStringLen
Input: The pointer to an integer that holds the length of the buffer
allocated for outString.
Output: The integer is updated to hold the length of the resulting
string.
int inOptions
Specify either FP_OPTION_MILLISECONDS_STRING to produce a
string containing a milliseconds field or

FP_OPTION_SECONDS_STRING to produce a string without a
milliseconds field.
Example
246
FPPool_GetClusterTime(vPool, vTimeString,
&vTimeStringLen);
FPLong vTimeInSeconds = FPTime_StringToLong(vTimeString);
Time Functions
Error handling


Syntax
Return value
Input parameters
Concurrency
requirement
FPTime_StringToMilliseconds (const char* inTime)

FPLong
const char* inTime
Unicode support
Description
This function converts a date/time string to an FPLong, a return value

that represents the number of milliseconds since the epoch 1 January
1970 00:00:00.000 GMT. The function does not support time strings
before the epoch.
Parameters
inTime
The time string of the format in YYYY.MM.DD HH:MM:SS[.ms]

GMT, in which the milliseconds field is optional.
Note: The milliseconds field is optional.
Example
Error handling
&vTimeStringLen);
FPLong vTimeInSeconds =
FPTime_StringToMilliseconds(vTimeString);

Time functions
247
Time Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPTime_StringToSeconds (const char* inTime)

FPLong
const char *inTime
Unicode support
Description
This function converts a date/time string to an FPLong, a return value

that represents the number of seconds since the epoch 1 January 1970
00:00:00.000 GMT. The function does not support time strings before
the epoch.
Parameters
inTime
The time string of the format in YYYY.MM.DD HH:MM:SS[.ms]

GMT, in which the milliseconds field is optional.
Note: The milliseconds field is optional.
Example
Error handling
&vTimeStringLen);
FPLong vTimeInSeconds =
FPTime_StringToSeconds(vTimeString);
248

Invble Body Tag
10
Logging Functions
This chapter describes the logging API functions, including logging

behavior and the use of logging environment variables.
Logging overview ............................................................................

FPLogging functions........................................................................
FPLogState functions.......................................................................
Environment variables ....................................................................
Logging Functions
250
255
262
277
249
Logging Functions
Logging overview
For application debugging of supported platforms, the SDK provides
thread-safe logging of its activities via log API functions or logging
environment variables. Logging does not create new threads.
The SDK logging interface allows logging to be configurable via API,
configuration file (which may be optionally polled), and environment
variables. Application developers can dynamically control logging
features with a control class. This logging interface consists of the
FPLogging mechanism and the FPLogState object.
FPLogging mechanism
FPLogging is a logging framework that enables SDK logging and
logging control on each CAS-enabled node. The FPLogging
mechanism uses the FPLogState object, which is the control class
that defines the conditions for determining logging behavior.
FPLogging is also the factory from which other instances of
FPLogState objects may be created.
You can use various log API functions to perform the following
actions:
Start and stop logging anytime during runtime
Modify SDK log settings in (dynamic) real time
Write application-defined log messages to the SDK log file
Use a callback function to capture SDK log data directly for

application logs
When checking for log state settings, the FPLogging mechanism

observes the following order of priority, from highest to lowest:
1. FPLogState settings applied by FPLogging_Start() calls
2. FPLogState.cfg in the working directory
3. FP_LOG_STATE_PATH environment variable
4. Logging environment variables
For example, during application startup, FPLogging first checks for
the presence of the FPLogState.cfg properties file in the working
directory. If this file exists, the SDK automatically reads and uses the
settings contained in that file, including the log path for the logging
250
Logging Functions
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 SDK ignores the log path
specified in the FP_LOGPATH environment variable.
If FP_LOG_STATE_PATH is not defined, the SDK uses the values
specified in the logging environment variables. For example, the path
set in the FP_LOGPATH is where the SDK directs the logging output.
Polling behavior on page 252 describes how the SDK handles poll
events.
FPLogState
FPLogState is the control class object that defines the conditions for
logging behavior and logging control. You create an FPLogState
object by calling FPLogging_CreateLogState(), which is then
passed to the FPLogging mechanism.
This log state object contains the following logging configurations:
FP_LOGPATH
FP_LOGKEEP
FP_LOGLEVEL
FP_LOGFILTER
FP_LOGFORMAT
FP_LOG_DISABLE_CALLBACK
FP_LOG_MAX_OVERFLOWS
FP_LOG_MAX_SIZE
FP_LOG_STATE_POLL_INTERVAL
Note: Environment variables on page 277 provides definitions of each

configuration setting.
After creating an FPLogState object, you can save it by calling

FPLogState_Save(). You can set the path to this properties file in the
FP_LOG_STATE_PATH environment variable. Example: FPLogState
configuration file on page 281 shows an example.
Note: If you explicitly load an existing log state, the settings associated with
that log state override any settings found in the environment variables (as
described in FPLogging_OpenLogState on page 257).
Logging overview
251
Logging Functions
Logging environment variables

The set of logging environment variables (as listed in Environment
variables on page 277) allows application administrators to control
logging behavior 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 SDK 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.
Environment variables on page 277 provides definitions of each

configuration setting.
Note: For optimal debugging practice, EMC recommends the use of the
logging API calls to manage the SDK logging.
Polling behavior
The 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:
252
If you specify a log state configuration file with either the

FPLogging_OpenLogState() API call or FP_LOG_STATE_PATH
environment variable, the SDK 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 SDK 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 SDK immediately redirects the log
output to the new file based on the settings specified in
FP_LOGFORMAT and FP_LOGKEEP.
Logging Functions
When a poll event interval occurs, any updates made to the

following configuration file fields are applied:
FP_LOGPATH
FP_LOGLEVEL
FP_LOGFORMAT
FP_LOGFILTER
FP_LOGKEEP
FP_LOG_MAX_SIZE
Log file format

The 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.
Application strings in SDK log

Using FPLogging_Log(), applications can directly insert
application-defined strings into the SDK log. You can filter these
messages at the application level by including the APP component in
the FPLogState_SetLogFilter() API call or alternatively, by setting
it in the FP_LOGFILTER environment variable. FPLogging_Log on
page 256 and Environment variables on page 277 provide more
information.
Logging overview
253
Logging Functions
Redirecting log output

Conversely, applications can integrate SDK logging into their own
log by redirecting the output of the SDK logging activity. To do this,
applications use the FPLogging_RegisterCallback()call (page 258)
to establish a callback routine that allows the SDK to pass the logging
string to the registered callback. It can be disabled via the
FPLogState_SetDisableCallback()function (page 269).
The FP_LOG_DISABLE_CALLBACK environment variable (page 277) can
be set to disable or enable the callback.
254
Logging Functions
FPLogging functions
The FPLogging functions determine the initial state of the
FPLogState object and control logging operations.
FPLogging_CreateLogState
FPLogging_Log
FPLogging_RegisterCallback
FPLogging_Start
FPLogging_Stop
FPLogState_Delete
FPLogState_Save
FPLogging_CreateLogState
Syntax
Return value
Concurrency
requirement
Description
FPLogging_CreateLogState()
FPLogStateRef

This function creates an FPLogState object. This object contains all
default field values. When building a new FPLogState object, the
SDK checks to see if any logging environment variables are set. If yes,
it uses the values of the set environment variables to initialize the
corresponding fields in the FPLogState object. If no logging
environment variables are set, the object is given the default field
values.
When you no longer need the reference, use FPLogState_Delete()
to release the resources allocated by this method.
Example
Error handling
// Create a log state object (all defaults)

FPLogStateRef vLogState = FPLogging_CreateLogState();

FP_OUT_OF_MEMORY_ERR (program logic error)
FPLogging functions
255
Logging Functions
FPLogging_Log
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
FPLogging_Log (const FPLogLevel inLogLevel, const char

*inMessage)
void
const FPLogLevel inLogLevel, const char *inMessage

character routines on page 23.
Description
This function writes a message to the configured SDK log

components at the specified logging level.
Parameters
const FPLogLevel inLogLevel
The level at which to log the message. The following log levels are
available:
FP_LOGLEVEL_ERROR: Log error messages
FP_LOGLEVEL_WARN: Log warnings and error messages.
FP_LOGLEVEL_LOG: Log API calls, warnings, and errors
FP_LOGLEVEL_DEBUG: Debug log level
const char *inMessage
A null-terminated string to write to the log.

Example
Error handling
// Write a message to the FP_LOGGING_COMPONENT_APP

component in the log
FPLogging_Log(FP_LOGLEVEL_ERROR, "This is a fatal
error");
256
Logging Functions
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
Description
FPLogging_OpenLogState(char * inPathName)
FPLogStateRef
char * inPathName

This function loads an FPLogState properties file into an
FPLogState object. When you no longer need the reference, use
FPLogState_Delete to release the resources allocated by this
method.
Note: If you use this method to open an FPLogState file from disk, the log
state file is polled every 5 minutes (default). You can specify (or disable) the
poll interval using the FPLogState_SetPollInterval API call.
Parameters
char * inPathName
The full path to a serialized FPLogState properties file.

Example
Error handling
// Open an existing log state object from an FPLogState

properties file
FPLogStateRef vLogState =
FPLogging_OpenLogState("C:\\MyLogState.cfg");

FPLogging functions
257
Logging Functions
FPLogging_RegisterCallback
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogging_RegisterCallback(FPLogProc inCallback)
void
FPLogProc inCallback

This function registers an application callback method with the
logging mechanism.
If you specify this callback, the logging mechanism uses the method
pointed to by inCallback to log an event, instead of directing the
output to a file. If you already enabled logging before calling this
method, all log output is redirected to the callback and does not
appear in the log file. If you disable the callback, subsequent log
output continues to appear in the log file.
You can disable the callback by passing NULL to this method, or by
using the disable_callback field in an active FPLogState object
(see FPLogState_SetDisableCallback on page 269).
Parameters
FPLogProc inCallback
A reference to the logging callback method to log an event.

Example
// Define a logging callback method

FPInt appStdoutLogger(char* inString)
{
printf(inString);
return(0);
}
// Register the appStdoutLogger callback with the logging
mechanism
// The appStdoutLogger callback will be called instead of
being logged to the file.
FPLogging_RegisterCallback(appStdoutLogger);
Error handling

258
FP_LOGGING_CALLBACK_ERR
Logging Functions
FPLogging_Start
Syntax
Return value
Input parameters
Concurrency
requirement
FPLogging_Start(FPLogStateRef inLogState)
void
FPLogStateRef inLogState
Description
This function enables the logging mechanism based on the given log
configuration. If logging is already configured via environment
variables, this method restarts the logging mechanism using the new
settings (potentially closing the old log file and opening a new one).
Parameters
Example
Error handling
A reference to an FPLogState object containing log configuration
details. Pass FPREF_NULL to use all default state settings.
// Start logging using the given FPLogState settings

FPLogging_Start(vLogState);
FPLogging_Stop
Syntax
Return value
Concurrency
requirement
Description
Example
FPLogging_Stop()
void

This function disables the logging mechanism. If any log files created
with logging are open, this call flushes and closes them. Similarly, any
polling by log state files is also disabled.
// Stop all logging
FPLogging_Stop();
FPLogging functions
259
Logging Functions
FPLogState_Delete
Syntax
Return value
Input parameters
Concurrency
requirement
void
FPLogStateRef inLogState)
Description
This function releases all resources associated with an FPLogState

object. Use this method in combination with
FPLogging_CreateLogState() and FPLogging_OpenLogState() to
delete an allocated FPLogState object.
Parameters
Example
260
FPLogState_Delete(FPLogStateRef inLogState)
A reference to an FPLogState object.
// Delete the FPLogState object when done

FPLogState_Delete(vLogState);
Logging Functions
FPLogState_Save
Syntax
Return value
Input parameters
Concurrency
requirement
Unicode support
FPLogState_Save(FPLogStateRef inLogState, char

*inPathName)
void

Description
This function saves the settings of an FPLogState object to a

properties (configuration) file.
Parameters
char * inPathName
The full path to a serialized FPLogState properties file.

Example
Error handling
// Save an FPLogState properties file to disk based on

these settings
FPLogState_Save(vLogState, "C:\\MyLogState.cfg");

FPLogging functions
261
Logging Functions
FPLogState functions
The FPLogState Get functions return a specific logging value:
FPLogState_GetAppendMode
FPLogState_GetDisableCallback
FPLogState_GetLogFilter
FPLogState_GetLogFormat
FPLogState_GetLogLevel
FPLogState_GetLogPath
FPLogState_GetMaxLogSize
FPLogState_GetMaxOverflows
FPLogState_GetPollInterval
The FPLogState Set functions update the FPLogState control class

object with the latest logging settings:
FPLogState_SetAppendMode
FPLogState_SetDisableCallback
FPLogState_SetLogFilter
FPLogState_SetLogFormat
FPLogState_SetLogLevel
FPLogState_SetMaxLogSize
FPLogState_SetMaxOverflows
FPLogState_SetPollInterval
FPLogState_GetAppendMode
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetAppendMode(FPLogStateRef inLogState)
FPBool

This function gets the current value of the append mode field of the
FPLogState object. See FPLogState_SetAppendMode on page 268.
Parameters
Example
262
FPLogStateRef ioLogState
FPBool vAppend = FPLogState_GetAppendMode (vLogState);
Logging Functions
Error handling

FPLogState_GetDisableCallback
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetDisableCallback(FPLogStateRef inLogState)
FPBool

This function gets the current value of the disable callback field of the
FPLogState object. See FPLogState_SetDisableCallback on
page 269.
Parameters
Example
Error handling
FPBool vDisableCallback = FPLogState_GetDisableCallback

(vLogState);
263
Logging Functions
FPLogState_GetLogFilter
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetLogFilter(FPLogStateRef inLogState)
FPInt

This function gets the current value of the filter field of the
FPLogState object. See FPLogState_SetLogFilter on page 270.
Parameters
Example
Error handling
FPInt vFilterMask = FPLogState_GetLogFilter (vLogState);

FPLogState_GetLogFormat
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetLogFormat(FPLogStateRef inLogState)
FPLogFormat

This function gets the current value of the formatter field of the
FPLogState object. See FPLogState_SetLogFormat on page 271.
Parameters
Example
264
FPLogFormat vFormat = FPLogState_GetLogFormat

(vLogState);
Logging Functions
Error handling

FPLogState_GetLogLevel
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetLogLevel(FPLogStateRef inLogState)
FPLogLevel

This function gets the current value of the log level field of the
FPLogState object. See FPLogState_SetLogLevel on page 272.
Parameters
Example
Error handling
FPLogLevel vLevel = FPLogState_GetLogLevel (vLogState);

FPLogState_GetLogPath
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetLogPath(FPLogStateRef ioLogState)
const char*

This function gets the current value of the log path field of the
FPLogState object. See FPLogState_SetLogPath on page 273.
Parameters
265
Logging Functions
Example
Error handling
const char* vLogPath = FPLogState_GetLogPath(vLogState);

FPLogState_GetMaxLogSize
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetMaxLogSize(FPLogStateRef inLogState)
FPLong

This function gets the current value of the max log size field of the
FPLogState object. See FPLogState_SetMaxLogSize on page 274.
Parameters
Example
Error handling
FPLong vMaxLogSize = FPLogState_GetMaxLogSize

(vLogState);
266
Logging Functions
FPLogState_GetMaxOverflows
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetMaxOverflows(FPLogStateRef inLogState)
FPInt

This function gets the current value of the max overflows field of the
FPLogState object. See FPLogState_SetMaxOverflows on page 275.
Parameters
Example
Error handling
FPInt vMaxOverflows = FPLogState_GetMaxOverflows

(vLogState);
FPLogState_GetPollInterval
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_GetPollInterval(FPLogStateRef inLogState)
FPInt

This function gets the current value of the poll interval field of the
FPLogState object. See FPLogState_SetPollInterval on page 276.
Parameters
Example
FPInt vPollIntervalInMin = FPLogState_GetPollInterval

(vLogState);
267
Logging Functions
Error handling

FPLogState_SetAppendMode
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetAppendMode(FPLogStateRef ioLogState,
FPBool inAppendMode)
void
FPLogStateRef ioLogState, FPBool inAppendMode

This function updates the AppendMode field of the FPLogState object.
This field indicates whether or not the logging mechanism is to
append any existing file found at the given LogPath.
You can initialize the default value of LogPath by setting the
FP_LOGKEEP environment variable.
Parameters
FPBool inAppendMode
If set to true, an append is allowed, otherwise, false for an

overwrite (default).
Example
Error handling
FPLogState_SetAppendMode(vLogState, false); // overwrite

268

Logging Functions
FPLogState_SetDisableCallback
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetDisableCallback(FPLogStateRef ioLogState,
FPBool inDisableCallback)
void
FPLogStateRef ioLogState, FPBool inDisableCallback

This function updates the disable callback field of the FPLogState
object, and disables (or allows) the use of any application callback
registered with the FPLogging_RegisterCallback API method.
You can initialize the default value of disable callback by setting
the FP_LOG_DISABLE_CALLBACK environment variable.
Parameters
FPBool inDisableCallback
If set to true, registered callback is disabled. If set to false,

registered callback is enabled (default).
Example
Error handling
FPLogState_SetDisableCallback(vLogState, false);
// Allow callback registration

269
Logging Functions
FPLogState_SetLogFilter
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetLogFilter(FPLogStateRef ioLogState, FPInt

inLogComponents)
void
FPLogStateRef ioLogState, FPInt inLogComponents

This function updates the LogFilter field of the FPLogState object,
and defines which SDK components are to be logged.
You can initialize the default value of LogFilter by setting the
FP_LOGFILTER environment variable. For the list of possible SDK
components to include for logging, see FP_LOGFILTER inTable 17 on
page 277.
Parameters
FPInt inLogComponents
A bitmask that defines the active components. To enable full

logging, use the FP_LOGGING_COMPONENT_ALL mask. To log only
API level calls, use the FP_LOGGING_COMPONENT_API mask.
Example
Error handling
FPLogState_SetLogFilter(vLogState,
FP_LOGGING_COMPONENT_ALL);
270

Logging Functions
FPLogState_SetLogFormat
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetLogFormat(FPLogStateRef ioLogState,
FPLogFormat inLogFormat)
void
FPLogStateRef ioLogState, FPLogFormat inLogFormat

This function updates the LogFormat field of the FPLogState object,
and determines which log format is to be used for logging.
You can initialize the default value of LogFormat by setting the
FP_LOGFORMAT environment variable.
Parameters
FPLogFormat inLogFormat
The log format to be used for logging either

FP_LOGGING_LOGFORMAT_XML or FP_LOGGING_LOGFORMAT_TAB
(default).
Example
Error handling
FPLogState_SetLogFormat(vLogState,
FP_LOGGING_LOGFORMAT_TAB);

271
Logging Functions
FPLogState_SetLogLevel
Syntax
Return value
Input parameters
Concurrency
requirement
FPLogState_SetLogLevel(FPLogStateRef ioLogState,
FPLogLevel inLogLevel)
void
FPLogStateRef ioLogState, FPLogLevel inLogLevel
Description
This function updates the LogLevel field of the FPLogState object.

This field controls the log level used when the logger writes output.
You can initialize the default value of LogLevel by setting the
FP_LOGLEVEL environment variable.
Parameters
FPLogLevel inLogLevel
The level at which to log the message. The following log levels are
available:
FP_LOGLEVEL_ERROR: Log error messages
FP_LOGLEVEL_WARN: Log warnings and error messages
FP_LOGLEVEL_LOG: Log API calls, warnings, and errors
FP_LOGLEVEL_DEBUG: Debug log level
Example
Error handling
FPLogState_SetLogLevel(vLogState, FP_LOGLEVEL_DEBUG);
272

Logging Functions
Syntax
Return value
Input parameters
Concurrency
requirement
FPLogState_SetLogPath(FPLogStateRef ioLogState, char

*inPathName)
void
FPLogStateRef ioLogState, char *inPathName
Unicode support
Description
This function updates the LogPath field of the FPLogState object.

This field directs the logging mechanism to write to the file specified
in inPathName.
You can initialize the default value of the LogPath field by setting the
FPLogPath environment variable.
Parameters
char *inPathName
The string containing a full log file path.

Example
Error handling
FPLogState_SetLogPath(vLogState, "C:\\MyLogFile.txt");

273
Logging Functions
FPLogState_SetMaxLogSize
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetMaxLogSize(FPLogStateRef ioLogState,
FPLong inSizeInKilobytes)
void
FPLogStateRef ioLogState, FPLong inSizeInKilobytes

This functionupdates the MaxLogSize field of the FPLogState object,
and determines the maximum size (in KB) that the log file may grow
before rolling over to an overflow file. The default is 1048576 (1 GB).
You can initialize the default value of the LogPath field by setting the
FPLogPath environment variable.
Parameters
FPLong inSizeInKilobytes
The maximum size (in KB) that a log file may grow. For no limit
on the size, specify FP_LOG_SIZE_UNBOUNDED.
Example
Error handling
FPLogState_SetMaxLogSize(vLogState, 1048576); // 1 GB
274

Logging Functions
FPLogState_SetMaxOverflows
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetMaxOverflows(FPLogStateRef ioLogState,
FPInt inCount)
void
FPLogStateRef ioLogState, FPInt inCount

This function updates the MaxOverflows field of the FPLogState
object, and determines the maximum number of backup log files to
be generated (with an .# extension) if the log file size exceeds the
MaxLogSize value. The default value is 1.
You can initialize the default value of the MaxOverflows field by
setting the FP_LOG_MAX_OVERFLOWS environment variable.
Parameters
FPInt inCount
The maximum number of rollover files to be generated.

Example
Error handling
FPLogState_SetMaxOverflows(vLogState, 2);
// Save most recent 3 GB

275
Logging Functions
FPLogState_SetPollInterval
Syntax
Return value
Input parameters
Concurrency
requirement
Description
FPLogState_SetPollInterval(FPLogStateRef ioLogState,
FPInt inPollIntervalInMin)
void
FPLogStateRef ioLogState, FPInt inPollIntervalInMin

This function updates the log state polling interval field of the
FPLogState object, and defines the number of minutes between
config file poll events for FPLogState if a log state config file was
opened. If a state file exists, it is reread and the log configuration
modified accordingly at each interval.
You can initialize the default value of the log state polling
interval field by setting the FP_LOG_STATE_POLL_INTERVAL
environment variable.
Parameters
FPInt inPollIntervalInMin
The number of minutes between readings of the configuration

file. The default is 5 and must be greater than or equal to -1.
Example
Error handling
FPLogState_SetPollInterval(vLogState, 5);
// Poll state file every 5 min
276

Logging Functions
Environment variables
If set, the logging environment variables listed in Table 17, Logging
environment variables,determine the initial configuration of the
FPLogState control class object. They also allow legacy applications
to enable logging services without making code changes.
Table 17
Logging environment variables (page 1 of 2)
Environment variable
Description
Possible values or data type
Disables any registered log callback when set.

The default is FALSE.
TRUE or 1
FALSE or 0
The value is not case-sensitive.
Determines the maximum number of backup

(overflow) files to retain.
The default is 1.
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_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
Defines the interval at which a log state configuration

file is polled (in minutes). If the log interval is set to 0,
the SDK polls the log configuration file prior to every
log event.
The default is 5 (minutes).
FPInt
FP_LOGFILTER
Determines which SDK 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).
277
Logging Functions
Table 17
Logging environment variables (page 2 of 2)
Environment variable
Description
Possible values or data type
FP_LOGFORMAT
Determines the log file formateither XML or TAB. By

default, the SDK API generates a tab-delimited log file,
including upon error.
XML log format per line
XML
TAB
<log level tID=ProcessID.ThreadID

sec=timestamp comp=component API=high
level API><![CDATA[message]]></log
level>
Tab-delimited log format per line

where:
\t = tab
\s = space
\n = newline
MS TimeStamp\tDate\sTime\t[LogLevel]
\tProcessID.ThreadID\t[Component]\t
Message\n
\s\sPacketInfo\n //when applicable
FP_LOGKEEP
Determines how the file is generated.

If a log file does not exist, the SDK automatically
creates a log file as named in FP_LOGPATH
regardless of the set value. If the log file exists, the
SDK API 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_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)
Defines the full path to the log file on disk. This is

required to enable logging. If unset to indicate logging
is disabled, this field is set to the <NULL> string.
Path and file name of the log

Example C:\MyLog.txt
FP_LOGPATH
278
Logging Functions
Example: XML-formatted log

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<SDKLog SDKVersion="3.1.544">
<log procID="3368" tID="1996" msec="1177102381059" usec="qu" comp="API"><![CDATA[
Start FPPool_GetComponentVersion(1,-,128)
]]></log>
<log procID="3368" tID="1996" msec="1177102381059" usec="qu" comp="API"
API="FPPool_GetComponentVersion(1,-,128)"><![CDATA[
End FPPool_GetComponentVersion(1,@version.full@,15)
]]></log>
<log procID="3368" tID="1996" msec="1177102382912" usec="qu" comp="API"><![CDATA[
Start FPPool_Open(sdk2)
]]></log>
<debug procID="3368" tID="1996" msec="1177102382912" usec="qu" comp="LIB"
API="FPPool_Open(sdk2)"><![CDATA[
Attempting to load MD5 lib: "FPMD5_Lib.dll"
]]></debug>
<warn procID="3368" tID="1996" msec="1177102382912" usec="qu" comp="LIB"
MD5 lib not found! Using internal MD5 algorithm instead.
]]></warn>
<debug procID="3368" tID="1996" msec="1177102382922" usec="qu" comp="LIB"
Attempting to load SHA256 lib: "FPSHA256_Lib.dll"
]]></debug>
.
.
.
</SDKLog>
279
Logging Functions
Example: Tab-formatted log

Note: Because of space limitations on the page, the following example
displays the 6-column log information as two 3-column segments on the
page.
Time
1177082804380
1177082804380
1177082804380
1177082806122
1177082806122
1177082806142
1177082806142
1177082806142
1177082806142
1177082806142
1177082806233
1177082806233
PID.Thread
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
3360.1812
.
.
.
280
FormattedTime
2007-04-20 15:26:44.380
2007-04-20 15:26:44.380
2007-04-20 15:26:44.380
2007-04-20 15:26:46.122
2007-04-20 15:26:46.122
2007-04-20 15:26:46.142
2007-04-20 15:26:46.142
2007-04-20 15:26:46.142
2007-04-20 15:26:46.142
2007-04-20 15:26:46.142
2007-04-20 15:26:46.233
2007-04-20 15:26:46.233
LogLevel
[none]
[log]
[log]
[log]
[debug]
[warn]
[debug]
[warn]
[debug]
[debug]
[log]
[debug]
Module Message
[---]
SDK Version 3.1.544
[API]
Start FPPool_GetComponentVersion(1,-,128)
[API]
End FPPool_GetComponentVersion(1,@version.full@,15)
[API]
Start FPPool_Open(sdk7)
[LIB]
Attempting to load MD5 lib: "FPMD5_Lib.dll"
[LIB]
MD5 lib not found! Using internal MD5 algorithm instead.
[LIB]
Attempting to load SHA256 lib: "FPSHA256_Lib.dll"
[LIB] SHA256 lib not found! Using internal SHA256 algorithm instead.
[LIB]
Attempting to load FPIntercept lib: "FPIntercept_g.dll"
[LIB]
FPIntercept lib not found! (Using all default API calls.)
[CORE] Start ClusterCloud::createClusterInterfaceHelper
(-,-,false,true,false,-,120000,false)
[RETRY] AN(sdk7) Access Role (enabled)
Logging Functions
Example: FPLogState configuration file

##################################
# FPLogState Configuration File
##################################
FP_LOGPATH=C:\Logs\MyLogFile.log
FP_LOGLEVEL=4
FP_LOGFORMAT=TAB
FP_LOGFILTER=ALL
FP_LOGKEEP=OVERWRITE
FP_LOG_DISABLE_CALLBACK=TRUE
FP_LOG_STATE_POLL_INTERVAL=5
FP_LOG_MAX_SIZE=FP_LOG_SIZE_UNBOUNDED
FP_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).
Special defines that the API supports (for example,

FP_LOG_SIZE_UNBOUNDED) are supported as values where
applicable.
281
Logging Functions
282
Invible Body Tag
11
Error Codes
This chapter describes the set of SDK error codes.

Error codes ........................................................................................ 284
Error Codes
283
Error Codes
Error codes
The API reports both Centera-specific and operating-system errors. If
the API returns an error code that is not listed in Table 18 on
page 284, refer to a list of platform-specific error codes (for example,
Windows error code 10055 means that no buffer space is available).
Note that all Atmos CAS error codes are negative values.
Refer to the EMC Atmos CAS Programmers Guide for more
information on error handling. Also refer to FPPool_GetLastError
on page 42 and FPPool_GetLastErrorInfo on page 43.
If you want to access the errors described in this section, you must
include FPErrors.h.
Table 18
Error codes (page 1 of 8)
Value
Error name
Description and action
-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
-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.
284
Error Codes
Table 18
Value
Error name
-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.)
-10009
FP_SEGDATA_ERR

Segdatafield missing error.
This internal error was generated because the required
field containing the blob data was not found in the packet.
Try again.
-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.
-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.
Error codes
285
Error Codes
Table 18
286
Value
Error name
-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
-10015
FP_NUMLOC_FIELD_ERR

Numlockfield missing error.
This internal error was generated because the numlock
field was not found in the packet. Try again.
-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.
-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.

If FPTag_GetXXXAttribute() returned this
error, then the attribute was not found in the tag.
If FPTag_GetIndexAttribute() returned this
error, then the index parameter is larger than the number
of attributes in the tag.
-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 one or

more CAS-enabled nodes.
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 CAS-enabled nodes could be found
that has the required capability. Verify your LAN
connections, server settings, and try again.
Error Codes
Table 18
Value
Error name
-10021
FP_CLIP_NOT_FOUND_ERR
Could not find the referenced C-Clip in the CAS-enabled

nodes.
Returned by FPClip_Open(), it means 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.
-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 C-Clip 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.
Error codes
287
Error Codes
Table 18
288
Value
Error name
-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 function
FPPool_SetGlobalOption() 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.
-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 FPClip_Open() returns this error, it means the
blob data or metadata of the C-Clip 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.
-10038
FP_CLIPCLOSED_ERR
(Java only.) You tried to perform an operation on a closed

C-Clip. This operation requires access to an open C-Clip.
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 one or more CAS-enabled nodes 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.
Error Codes
Table 18
Value
Error name
-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 CAS-enabled
nodes are running but the slave nodes have not been
initialized yet. This error can also occur when not enough
mirror groups are found on the server.
Allow the SDK to perform the automatic number of
configured retries.
-10042
FP_SERVER_NO_CAPACITY_ERR
The server has no capacity to store data.

Enlarge the servers 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 with FPPool_Open().
-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-based retention (EBR) and
retention hold.
Error codes
289
Error Codes
Table 18
290
Value
Error name
-10159
FP_NON_EBR_CLIP_ERR
An attempt was made to trigger an EBR event on a

C-Clip that is not eligible to receive an event.
-10160
FP_EBR_OVERRIDE_ERR
An attempt was made to trigger or enable the

event-based retention period/class of a C-Clip a second
time. You can set EBR information only once.
-10161
FP_NO_EBR_EVENT_ERR
The C-Clip is under event-based retention protection and

cannot be deleted.
-10162
FP_RETENTION_OUT_OF_BOUNDS_ERR
The event-based 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.
-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
An SDK internal programming error has been detected.
-10206
FP_OUT_OF_MEMORY_ERR
The system ran out of memory. Check the systems

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.
Error Codes
Table 18
Value
Error name
-10214
FP_INVALID_XML_ERR
The specified string is not valid XML.
-10215
FP_UNABLE_TO_GET_LAST_ERROR
The call to FPPool_GetLastError() or

FPPool_GetLastErrorInfo() 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.
Error codes
291
Error Codes
292
Invisible Body Tag
This appendix lists deprecated Atmos CAS API functions and

options. Deprecated functions and options are not supported; client
applications should not use them. If you need information about
these functions or optionsfor example, to interpret existing
coderefer to the Javadoc or Doxygen documentation included with
this release.
The sections in this appendix are:
Deprecated functions....................................................................... 294

Deprecated options .......................................................................... 295
293
Deprecated functions
Table 19 on page 294 lists deprecated Atmos CAS API functions.
Table 19
294
Deprecated functions
Function name
Deprecated
release
FPTime_LongToString
3.1
Use the FPTime_SecondsToString or FPTime_MillisecondsToString

function. Refer to Time functions on page 244.
FPTime_StringToLong
3.1
Use the FPTime_StringToSeconds or FPTime_StringToMilliseconds

function. Refer to Time functions on page 244.
FPClip_Purge
2.3
Use the FP_OPTION_DELETE_PRIVILEGED option of

FPClip_AuditedDelete() (page 61) to delete content before the retention
period has expired.
FPTag_BlobPurge
2.3
Garbage collection purges unreferenced blobs automatically.
FPQuery_Open
2.3
Use the FPQueryExpression, FPPoolQuery, and FPQueryResult functions.

Refer to Query functions on page 216.
FPQuery_GetPoolRef
2.3

FPQuery_FetchResult
2.3

FPQuery_Close
2.3

FPStream_CreateWithBuffer
1.1
Use FPStream_CreateBufferForInput( ) (page 181) and

FPStream_CreateBufferForOutput( ) (page 182).
FPStream_CreateWithFile
1.1
Use FPStream_CreateFileForInput( ) (page 183) and

FPStream_CreateFileForOutput( ) (page 184).
FPStream_Read
1.1
Use the generic stream facility. Refer to Stream functions on page 178.
FPStream_Write
1.1
FPStream_SetMarker
1.1
FPStream_GetMarker
1.1
Comments
Deprecated options
Table 20 on page 295 lists deprecated Atmos CAS API options.
Table 20
Deprecated options
Option name
Deprecated
release
Comments
FP_OPTION_ENABLE_DUPLICATE_DETECTION
2.1
Was used by FPTag_BlobWrite( ).
FP_OPTION_CALCID_NOCHECK
2.1
Was used by FPTag_BlobWrite( ), FPTag_BlobRead( ),

and FPTag_BlobReadPartial( ). There is now always
end-to-end checking of the Content Address on the
client and the server to verify the content.
Deprecated options
295
296
Glossary
This glossary contains terms used in this manual that are related to
disk storage subsystems.
A
Application
Programming
Interface (API)
A set of function calls that enables communication between

applications or between an application and an operating system.
B
Blob
The Distinct Bit Sequence (DBS) of user data. The DBS represents the
actual content of a file and is independent of the filename and
physical location.
Note: Do not confuse this term with the term Binary Large Object
that exists in the database sector.
C
C-Clip
C-Clip Descriptor File

(CDF)
A package containing the users data and associated metadata. When

a user presents a file to the Atmos CAS system, the system calculates
a unique Content Address (CA) for the data and then stores the file.
The system also creates a separate XML file containing the CA of the
users file and application-specific metadata. Both the XML file and
the users data are stored in the C-Clip.
The additional XML file that the system creates when making a
C-Clip. This file includes the Content Addresses for all referenced
blobs and associated metadata.
297
Glossary
C-Clip ID
Cluster time
The Content Address that the system returns to the client. It is also
referred to as a C-Clip handle or C-Clip reference.
The synchronized time of all the nodes within a cluster.
Content Address
(CA)
An identifier that uniquely addresses the content of a file and not its
location. Unlike location-based addresses, Content Addresses are
inherently stable and, once calculated, they never change and always
refer to the same content.
Content Address
resolution
The process of discovering the IP address of a node containing a blob

with a given Content Address.
Content Address
verification
The process of checking data integrity by comparing the CA

calculations that are made on the application server (optional) and
the nodes that store the data.
Content Addressed
Storage (CAS)
The generic term for an Atmos CAS node and its software. In the
same way that a Symmetrix is considered a SAN device, a cluster is
considered a CAS device.
D
Distinct Bit Sequence
(DBS)
Dynamic Host
Configuration Protocol
(DHCP)
The actual content of a file independent of the filename and physical

location. Every file consists of a unique sequence of bits and bytes.
The DBS of a users file is referred to as a blob in the Atmos CAS
system.
An internet protocol used to assign IP addresses to individual
workstations and peripherals in a LAN.
E
End-to-end checking
Extensible Markup
Language
(XML)
298
The process of verifying data integrity from the application end

down to the second node with the storage role. See also Content
Address Verification.
A flexible way to create common information formats and share both
the format and the data on the World Wide Web, intranets, and
elsewhere. Refer to http://www.xml.com for more information.
Glossary
F
Failover
Commonly confused with failure. It actually means that a failure is

transparent to the user because the system will fail over to another
process to ensure completion of the task; for example, if a disk fails,
then the system will automatically find another one to use instead.
I
Input parameter
The required or optional information that has to be supplied to a

function.
L
Load balancing
The process of selecting the least-loaded node for communication.

Load balancing is provided in two ways: first, an application server
can connect to the cluster by selecting the least-loaded node with the
access role; second, this node selects the least loaded node with the
storage role to read or write data.
Local Area Network

(LAN)
A set of linked computers and peripherals in a restricted area such as

a building or company.
M
Message Digest 5
(MD5)
A unique 128-bit number that is calculated by the Message Digest

5-hash algorithm from the sequence of bits (DBS) that constitute the
content of a file. If a single byte changes in the file then any resulting
MD5 will be different.
MultiCast Protocol
(MCP)
A network protocol used for communication between a single sender

and multiple receivers.
N
Node
Logically, a network entity that is uniquely identified through a

system ID, IP address, and port. Physically, a node is a computer
system that is part of the Atmos system.
O
Output parameter
The information that a function returns to the application that called

the function.
299
Glossary
P
Pool
A set of separate clusters that are linked together to constitute one

Content Addressed Storage device.
Pool Transport
Protocol
(PTP)
A further evolution of the UniCast Protocol (UCP) used for

communication over the Internet between the application server and
a node with the access role.
Probing
A process where the application server requests information from the

cluster to determine if it should start a PTP session.
R
Redundancy
A process where data objects are duplicated or encoded such that the
data can be recovered given any single failure.
Regeneration
The process of creating a data copy if a mirror copy or fragmented

segment of that data is no longer available.
Retention period
The time that a C-Clip and the underlying blobs have to be stored
before the application is allowed to delete them.
Return value
The outcome of a function that the system returns to the application

calling the function.
S
Segmentation
The process of splitting very large files or streams into smaller chunks
before storing them. Segmentation is an invisible client-side feature
and supports storage of very large files such as rich multimedia.
Stream
Generalized input/output channels that provide a way to handle

incoming and outgoing data without having to know where that data
comes from or goes to.
T
Time to First Byte (TTFB)
300
The time between the request to the system to retrieve a C-Clip and
the retrieval of the first byte of the blob.
Glossary
U
UniCast Protocol
(UCP)
User Datagram
Protocol (UDP)
A network protocol used for communication between multiple

senders and one receiver.
A standard Internet protocol used for the transport of data.
W
Wide Area Network
(WAN)
Write Once Read
Many
(WORM)
A set of linked computers and peripherals that are not in one

restricted area but that can be located all over the world.
A technique that stores data that will be accessed regularly, for
example, a tape device.
301
Glossary
302
Index
A
Access Node error 289
acknowledgement error 285
API 297
Application Programming Interface. See API
attribute error 286
authentication error 289
authentication protocol error 289
authentication scheme error 289
B
blob 297
error 286, 288
functions 148
BlobID mismatch 288
buffer size pool setting 57
C
CA 298
duplicate 285
capabilities server 35
CAS 298
C-Clip 297
error 287
functions 60
handle 298
ID 298
reference 298
C-Clip Descriptor File. See CDF
C-Clips and multithreading 60
CDF 297
CENTERA_CUSTOM_METADATA 65, 109
child tag 129

closed C-Clip error 288
closed pool error 288
cluster
capacity 44
failover eligibility 57
free space 44
identifier 44
name 44
replication address 45
software version 44
cluster time 298
connection error 286
Content Address Resolution 298
Content Address Verification 298
Content Address. See CA
Content Addressed Storage. See CAS
Coordinated Universal Time (UTC) 38, 88
customer metadata 65, 109
D
data
embedded 155
error 287
handle incoming/outgoing 300
linked 155
data integrity check 298
data packet error 289
DBS 298
defaultcollisionavoidance pool setting 58
deprecated functions 294
FPClip_Purge() 294
FPQuery_Close() 294
303
Index
FPQuery_FetchResult() 294
FPQuery_GetPoolRef() 294
FPQuery_Open() 294
FPQuery_OpenW() 294
FPStream_CreateWithBuffer() 294
FPStream_CreateWithFile() 294
FPStream_GetMarker() 294
FPStream_Read() 294
FPStream_SetMarker() 294
FPStream_Write() 294
FPTime_LongToString() 294
FPTime_StringToLong() 294
deprecated options
FP_OPTION_CALCID_NOCHECK 295
FP_OPTION_ENABLE_DUPLICATE_DETE
CTION 295
options
deprecated 295
DHCP 298
directory error 287
Distinct Bit Sequence. See DBS
duplicate CA 285
Dynamic Host Configuration Protocol. See DHCP
E
embedded data 155
end-to-end checking 298
error
acknowledgement 285
attribute 286
authentication 289
authentication protocol 289
authentication scheme 289
blob 286
capacity server 289
C-Clip 287
connection 286
data 287
data packet 289
descriptions 284
directory 287
file system 287
generic stream 290
network socket 289
node with the access role 289
number 284
304
object in use 290

object not open 290
packet field 289
parameter 284
path 285
protocol 288
SDK internal 290
section 286
send request 284
server 284
socket 288
stack depth 287
system memory 290
tag 286, 287
tag tree 287
thread 290
wrong reference 286
Extensible Markup Language. See XML
F
failover 299
file system error 287
FP_ACCESSNODE_ERR 289
FP_ACK_NOT_RCV_ERR 285
FP_ADVANCED_RETENTION_DISABLED_ERR
289
FP_ATTR_NOT_FOUND_ERR 286
FP_AUTHENTICATION_FAILED_ERR 289
FP_BLOBBUSY_ERR 288
FP_BLOBIDFIELD_ERR 288
FP_BLOBIDMISMATCH_ERR 288
FP_BLOBNAMING 35
FP_CLIP_NOT_FOUND_ERR 287
FP_CLIPCLOSED_ERR 288
FP_CLIPENUMERATION 35
FP_COMPLIANCE 35
FP_CONTROLFIELD_ERR 285
FP_DEFAULT_RETENTION_PERIOD 78
FP_DELETE 35
FP_DELETIONLOGGING 35
FP_DUPLICATE_FILE_ERR 285
FP_DUPLICATE_ID_ERR 289
FP_EBR_OVERRIDE_ERR 290
FP_EXIST 35
FP_FILE_NOT_STORED_ERR 286
FP_FILESYS_ERR 287
Index
FP_INFINITE_RETENTION_PERIOD 77
FP_INVALID_NAME 284
FP_INVALID_XML_ERR 291
FP_ISNOT_DIRECTORY_ERR 287
FP_LAZY_OPEN 56
FP_LOGGING_CALLBACK_ERR 291
FP_METADATA_MISMATCH_ERR 290
FP_MODE 35
FP_MONITOR 35
FP_MULTI_BLOB_ERR 287
FP_NO_EBR_EVENT_ERR 290
FP_NO_POOL_ERR 286
FP_NO_RETENTION_PERIOD 77
FP_NO_SOCKET_AVAIL_ERR 288
FP_NON_EBR_CLIP_ERR 290
FP_NORMAL_OPEN 56
FP_NOT_RECEIVE_REPLY_ERR 284
FP_NOT_SEND_REQUEST_ERR 284
FP_NOTYET_OPEN_ERR 290
FP_NUMLOC_FIELD_ERR 286
FP_OBJECTINUSE_ERR 290
FP_OFFSET_FIELD_ERR 285
FP_OPCODE_FIELD_ERR 289
FP_OPEN_ASTREE 71
FP_OPEN_FLAT 71
FP_OPERATION_NOT_ALLOWED 290
FP_OPERATION_NOT_SUPPORTED 285
FP_OPERATION_REQUIRES_MARK 290
FP_OPTION_BUFFERSIZE 57
FP_OPTION_CALCID_NOCHECK 295
FP_OPTION_CLIENT_CALCID 157, 162
FP_OPTION_CLIENT_CALCID_STREAMING
157, 162
FP_OPTION_CLUSTERNONAVAILTIME 55
FP_OPTION_COPY_BLOBDATA 119
FP_OPTION_COPY_CHILDREN 119
FP_OPTION_DEFAULT_COLLISION_AVOIDA
NCE 58
FP_OPTION_DEFAULT_OPTIONS 72, 151, 153
FP_OPTION_DELETE_PRIVILEGED 62
FP_OPTION_DISABLE_CLIENT_STREAMING
55
FP_OPTION_DISABLE_COLLISION_AVOIDAN
CE 158, 163
FP_OPTION_EMBED_DATA 158
FP_OPTION_EMBEDDED_DATA_THRESHOLD
55
FP_OPTION_ENABLE_COLLISION_AVOIDAN
CE 158, 163
FP_OPTION_ENABLE_DUPLICATE_DETECTIO
N 55, 295
FP_OPTION_ENABLE_MULTICLUSTER_FAILO
VER 57
FP_OPTION_LINK_DATA 158
FP_OPTION_MAXCONNECTIONS 55
FP_OPTION_MULTICLUSTER_READ_CLUSTE
RS 57
FP_OPTION_NO_COPY_OPTIONS 118
FP_OPTION_OPENSTRATEGY 56
FP_OPTION_PREFETCH_SIZE 58
FP_OPTION_PROBE_LIMIT 56
FP_OPTION_RETRYCOUNT 56
FP_OPTION_RETRYSLEEP 56
FP_OPTION_TIMEOUT 57
FP_OUT_OF_BOUNDS_ERR 287
FP_OUT_OF_MEMORY_ERR 290
FP_PACKET_FIELD_MISSING_ERR 289
FP_PACKETDATA_ERR 289
FP_PARAM_ERR 284
FP_PATH_NOT_FOUND_ERR 285
FP_POOL_POOLMAPPINGS 35
FP_POOLCLOSED_ERR 288
FP_POOLS 35, 36
FP_PRIVILEGED_DELETE 35
FP_PROBE_TIME_EXPIRED_ERR 290
FP_PROBEPACKET_ERR 288
FP_PROFILECLIPID_NOTFOUND_ERR 289
FP_PROFILECLIPID_WRITE_ERR 290
FP_PROFILES 35
FP_PROTOCOL_ERR 288
FP_PURGE 35
FP_QUERY_RESULT_CODE_ABORT 239
FP_QUERY_RESULT_CODE_COMPLETE 239
FP_QUERY_RESULT_CODE_END 239
FP_QUERY_RESULT_CODE_ERROR 239
FP_QUERY_RESULT_CODE_INCOMPLETE 239
FP_QUERY_RESULT_CODE_OK 239
FP_QUERY_RESULT_CODE_PROGRESS 239
FP_QUERY_TYPE_DELETED 229
FP_QUERY_TYPE_EXISTING 229
FP_QUERYCLOSED_ERR 290
FP_READ 35
FP_RETENTION 36
FP_RETENTION_HOLD 36
305
Index
FP_RETENTION_HOLD_COUNT_ERR 290
FP_RETENTION_OUT_OF_BOUNDS_ERR 290
FP_SDK_INTERNAL_ERR 290
FP_SECTION_NOT_FOUND_ERR 286
FP_SEGDATA_ERR 285
FP_SERVER_ERR 284
FP_SERVER_NO_CAPACITY_ERR 289
FP_SERVER_NOTREADY_ERR 289
FP_SOCKET_ERR 289
FP_STACK_DEPTH_ERR 287
FP_STREAM_BYTECOUNT_MISMATCH_ ERR
289
FP_STREAM_ERR 290
FP_STREAM_VALIDATION_ERR 289
FP_TAG_CLOSED_ERR 290
FP_TAG_HAS_NO_DATA_ERR 287
FP_TAG_NOT_FOUND_ERR 286
FP_TAG_READONLY_ERR 287
FP_TAGTREE_ERR 287
FP_THREAD_ERR 290
FP_TRANSACTION_FAILED_ERR 289
FP_UNABLE_TO_GET_LAST_ERROR 291
FP_UNEXPECTEDTAG_ERR 287
FP_UNKNOWN_AUTH_SCHEME_ERR 289
FP_UNKNOWN_OPTION 284
FP_VERSION_ERR 287
FP_WRITE 36
FP_WRONG_REFERENCE_ERR 286
FP_WRONG_STREAM_ERR 290
FPBool 25
FPChar16 25
FPChar32 25
FPClip_AuditedDelete() 61
FPClip_Close() 82
FPClip_Create() 61
FPClip_Delete() 67
FPClip_EnableEBRWithClass() 69
FPClip_EnableEBRWithPeriod() 69
FPClip_Exists() 103
FPClip_FetchNext() 116
FPClip_GetClipID() 87
FPClip_GetCreationDate() 88
FPClip_GetDescriptionAttribute() 103
FPClip_GetDescriptionAttributeIndex() 105
FPClip_GetEBRClassName() 89
FPClip_GetEBREventTime() 90
FPClip_GetEBRPeriod() 91
306
FPClip_GetName() 92
FPClip_GetNumBlobs() 93
FPClip_GetNumDescriptionAttributes() 107
FPClip_GetNumTags() 94
FPClip_GetPoolRef() 87
FPClip_GetRetentionClassName() 96
FPClip_GetRetentionHold() 96
FPClip_GetRetentionPeriod() 98
FPClip_GetTopTag() 112
FPClip_GetTotalSize() 96
FPClip_IsEBREnabled() 100
FPClip_IsModified() 103
FPClip_Open() 70
FPClip_Purge() 294
FPClip_RawRead() 73
FPClip_RemoveDescriptionAttribute() 108
FPClip_RemoveRetentionClass() 74
FPClip_SetDescriptionAttribute() 109
FPClip_SetName() 67
FPClip_SetRetentionClass() 76
FPClip_SetRetentionHold() 76
FPClip_SetRetentionPeriod() 74, 76
FPClip_TriggerEBREvent() 79
FPClip_TriggerEBREventWithClass() 79
FPClip_TriggerEBREventWithPeriod() 80
FPClip_ValidateRetentionClass() 101
FPClip_Write() 71
FPClipID 25
FPClipID_GetCanonicalFormat() 82
FPClipID_GetStringFormat() 84
FPErrorInfo 25
FPEventCallback_Close() 244
FPInt 25
FPLogging_CreateLogState( ) 255
FPLogging_Log( ) 256
FPLogging_OpenLogState( ) 257
FPLogging_RegisterCallback( ) 258
FPLogging_Start( ) 259
FPLogging_Stop( ) 259
FPLogState_Delete( ) 260
FPLogState_GetAppendMode( ) 262
FPLogState_GetDisableCallback( ) 263
FPLogState_GetLogFilter( ) 264
FPLogState_GetLogFormat( ) 264
FPLogState_GetLogLevel( ) 265
FPLogState_GetLogPath( ) 265
FPLogState_GetMaxLogSize( ) 266
Index
FPLogState_GetMaxOverflows( ) 267
FPLogState_GetPollInterval( ) 267
FPLogState_Save( ) 261
FPLogState_SetAppendMode( ) 268
FPLogState_SetDisableCallback( ) 269
FPLogState_SetLogFilter( ) 270
FPLogState_SetLogFormat( ) 271
FPLogState_SetLogLevel( ) 272
FPLogState_SetLogPath( ) 273
FPLogState_SetMaxLogSize( ) 274
FPLogState_SetMaxOverflows( ) 275
FPLogState_SetPollInterval( ) 276
FPLong 25
FPMonitor_GetAllStatistics() 244
FPPool_Close() 33
FPPool_GetCapability() 34
FPPool_GetClipID 37
FPPool_GetClusterTime() 46
FPPool_GetComponentVersion() 39
FPPool_GetGlobalOption() 40
FPPool_GetIntOption() 46
FPPool_GetLastError() 42
FPPool_GetLastErrorInfo() 43
FPPool_GetPoolInfo() 44
FPPool_GetRetentionClassContext() 46
FPPool_Open() 33
FPPool_SetClipID 51
FPPool_SetGlobalOption() 54
FPPool_SetIntOption() 51
FPPoolInfo 25
FPPoolQuery_Close() 231
FPPoolQuery_FetchResult() 236
FPPoolQuery_GetPoolRef() 236
FPPoolQuery_Open() 231
FPQuery_Close() 294
FPQuery_FetchResult() 294
FPQuery_GetPoolRef() 294
FPQuery_Open() 294
FPQuery_OpenW() 294
FPQueryExpression_Close() 218
FPQueryExpression_Create() 218
FPQueryExpression_DeselectField() 231
FPQueryExpression_GetEndTime() 220
FPQueryExpression_GetStartTime() 221
FPQueryExpression_GetType() 224
FPQueryExpression_IsFieldSelected() 231
FPQueryExpression_SelectField() 224
FPQueryExpression_SetEndTime() 227
FPQueryExpression_SetStartTime() 219
FPQueryExpression_SetType() 229
FPQueryResult_Close() 236
FPQueryResult_GetClipID() 237
FPQueryResult_GetField() 238
FPQueryResult_GetResultCode() 239
FPQueryResult_GetTimestamp() 238
FPQueryResult_GetType() 240
FPRetentionClass_Close() 178
FPRetentionClass_GetName() 173
FPRetentionClass_GetPeriod() 174
FPRetentionClassContext_Close() 168
FPRetentionClassContext_GetFirstClass() 170
FPRetentionClassContext_GetLastClass() 170
FPRetentionClassContext_GetNamedClass() 171
FPRetentionClassContext_GetNextClass() 171
FPRetentionClassContext_GetNumClasses() 170
FPRetentionClassContext_GetPreviousClass()
171
FPShort 25
FPStream_Close() 209
FPStream_Complete() 210
FPStream_CreateBufferForInput() 181
FPStream_CreateBufferForOutput() 182
FPStream_CreateFileForInput( ) 183
FPStream_CreateFileForInput() 183
FPStream_CreateFileForOutput() 184
FPStream_CreateGenericStream( ) 186
FPStream_CreatePartialFileForInput( ) 203
FPStream_CreatePartialFileForOutput( ) 205
FPStream_CreateTemporaryFile() 207
FPStream_CreateToNull( ) 208
FPStream_CreateToStdio( ) 208
FPStream_CreateWithBuffer() 294
FPStream_CreateWithFile() 294
FPStream_GetInfo() 211
FPStream_GetMarker() 294
FPStream_PrepareBuffer( ) 212
FPStream_Read() 294
FPStream_ResetMark() 213
FPStream_SetMark() 214
FPStream_SetMarker() 294
FPStream_Write() 294
FPStreamInfo 25
FPTag_BlobExists() 168
FPTag_BlobPurge() 294
307
Index
308
FPTag_BlobRead() 150
FPTag_BlobReadPartial() 168
FPTag_BlobWrite() 148
FPTag_BlobWritePartial() 160
FPTag_Close() 117
FPTag_Copy() 118
FPTag_Create() 117
FPTag_Delete() 127
FPTag_GetBlobSize() 122
FPTag_GetBoolAttribute() 134
FPTag_GetClipRef() 125
FPTag_GetFirstChild() 129
FPTag_GetIndexAttribute() 135
FPTag_GetLongAttribute() 137
FPTag_GetNumAttributes() 148
FPTag_GetParent() 133
FPTag_GetPoolRef() 121
FPTag_GetPrevSibling() 131
FPTag_GetSibling() 130
FPTag_GetStringAttribute() 139
FPTag_GetTagName() 125
FPTag_RemoveAttribute() 140
FPTag_SetBoolAttribute() 148
FPTag_SetLongAttribute() 142
FPTime_MillisecondsToString() 244
FPTime_SecondsToString() 246
FPTime_StringToMilliseconds() 247
FPTime_StringToSeconds() 248
function outcome 300
functions
blob 148
C-Clip 60
deprecated 294
pool 32
query 216
retention class 168
stream 178
tag 116
generic stream
create 186
operation 178
generic stream error 290
Greenwich Mean Time (GMT) 38, 88
name
error 284
navigate through tags 127
network socket error 289
node 299
incoming data, handle 300

input parameter 299
input stream 187
input/output channels 178
invalid name 284
J
Java classes 23
L
LAN 299
linked data 155
load balancing 299
Local Area Network. See LAN
logging environment variables 277
FP_LOG_DISABLE_CALLBACK 277
FP_LOG_MAX_OVERFLOWS 277
FP_LOG_MAX_SIZE 277
FP_LOG_STATE_PATH 277
FP_LOG_STATE_POLL_INTERVAL 277
FP_LOGFILTER 277
FP_LOGFORMAT 278
FP_LOGKEEP 278
FP_LOGLEVEL 278
FP_LOGPATH 278
logging functions 250
M
MCP 299
MD5 299
Message Digest 5. See MD5
mismatch BlobID 288
MultiCast Protocol. See MCP
multiclusterfailover pool setting 57
multithreading and C-Clips 60
Index
O
operation, not supported 285
option as environment variable 54
option name, unknown 284
options as environment variables 57
out of bounds, options parameter 287
outgoing data, handle 300
output parameter 299
output stream 187
P
packet field error 289
parameter
error 284
unknown 284
parent tag 130
path error 285
pool 300
functions 32
pool functions 26, 32
pool setting
buffer size 57
defaultcollisionavoidance 58
multiclusterfailover 57
prefetchsize 58
timeout 57
Pool Transport Protocol. See PTP
prefetchsize pool setting 58
probing 300
protocol
error 288
unknown 288
PTP 300
replication address 45
retention class
functions 168
getting name of 96
getting the period of 174
removing 74
setting 76
validating 102
retention period 77, 300
getting 98
setting 77
return value 300
S
SDK internal error 290
segmentation 300
send request error 284
server capabilities 35
server capacity error 289
server error 284
server not ready error 289
set attribute functions 133
sibling tag 131, 132
size internal buffers 57
socket error 288
splitting files 300
stack depth error 287
stackable stream support 178
stream 178, 300
functions 178
support of stackable streams 178
system memory error 290
T
Q
query
functions 216
query functions 216
R
read-only tag 287
redundancy 300
reflection 62, 68
regeneration 300
Tab-formatted log 280

tag
functions 116
read-only 287
unexpected 287
tag error 286, 287
tag tree error 287
thread error 290
Time to First Byte. See TTFB
timeout setting pool 57
TTFB 300
309
Index
U
UCP 301
UDP 301
unexpected tag 287
UniCast Protocol. See UCP
unknown
option name 284
parameter 284
protocol 288
User Datagram Protocol. See UDP
V
version error 287
W
WAN 301
Wide Area Network. See WAN
WORM 301
Write Once Read Many. See WORM
wrong reference error 286
X
XML 298
XML-formatted log 279
310

Atmos CAS 2.0 API Reference Guide 300-012-505 A01

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Atmos CAS 2.0 API Reference Guide 300-012-505 A01

Caricato da

Copyright:

Formati disponibili

EMC Atmos

CAS API Reference Guide

Copyright 2008 - 2011 EMC Corporation. All rights reserved.

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

Blob Handling Functions

Retention Class Functions

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

Mapping of terms between Centera and Atmos......................................... 18

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

As part of an effort to improve and enhance the performance and capabilities

This guide is for experienced programmers who are developing

Content Addressed Storage (CAS)

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Release Notes

EMC Atmos CAS Programmers Guide

EMC Atmos CAS for XAM VIM Reference Guide

EMC Atmos Administrators Guide

EMC Atmos Programmers Guide

EMC Atmos System Management API Guide

EMC Atmos Security Configuration Guide

EMC Atmos Non-EMC Software License Agreements

EMC Atmos Hardware Guide

EMC Atmos online help

EMC uses the following conventions for special notices.

Used in running (nonprocedural) text for:

Used in running (nonprocedural) text for:

EMC Atmos Version 2.0 CAS API Reference Guide

Where to get help

Used in all text (including procedures) for:

Used in procedures for:

Angle brackets enclose parameter or variable values supplied by

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

EMC support, product, and licensing information can be obtained as

Technical support For technical support, go to Powerlink and

Your suggestions will help us continue to improve the accuracy,

EMC Atmos Version 2.0 CAS API Reference Guide

EMC Atmos Version 2.0 CAS API Reference Guide

Invible Body Tag

This chapter introduces the C API function types and syntax

Function syntax ..................................................................................

In this guide, the following Centera terms in Table 1 are mapped to

Mapping of terms between Centera and Atmos

A combination of subtenant ID and user ID (UID)

CAS-enabled access nodes

PEA file or the shared secret of the UID

EMC Atmos Version 2.0 CAS API Reference Guide

Function names consist of a prefix followed by the actual function.

API function types

Function name prefix

Retention Class functions

Time format functions

FPPool_Open() opens a pool, FPClip_Open() opens a C-Clip.