This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?


class %Archive.Session extends %Library.RegisteredObject

API for data archiving

Sample script that initiates a connection to an archive server

     Set SessionOref = ##class(%Archive.Session).%New() 
     Set SessionOref.Host = // IP address of the archive server 
     Set SessionOref.AuthFile = AuthFilePath // path of the .pea file (for Centera) 
     Set Status = SessionOref.Connect() 
Once connected, here is a sample script that stores a content (cf. %Archive.Content):
     // create a content object as source, whose handle is ContentOref (see %Archive.Content)
     Set Status = SessionOref.Store(ContentOref, .ContentUID) 
After Store() returns successfully, you need to save the ContentUID value somewhere (say, in a Cache database) for future retrieval purpose.
Here is a sample script to retrieve the file from the archive server, using the ContentUID and open connection above:
     // create a content object as target, whose handle is ContentOref (see %Archive.Content)
     Set Status = SessionOref.Retrieve(ContentOref, ContentUID) 

Property Inventory (Including Private)

Method Inventory (Including Private)


parameter TYPE = Centera;
Type of the archive system (EMC Centera)
parameter VERSION = 0.1;
Version of the API


property ApplicationName as %String;
Name of the application, default to something like "Cache for Windows (x86-32)" (from $zv)
Property methods: ApplicationNameDisplayToLogical(), ApplicationNameGet(), ApplicationNameIsValid(), ApplicationNameLogicalToDisplay(), ApplicationNameLogicalToOdbc(), ApplicationNameNormalize(), ApplicationNameSet()
property ApplicationVersion as %String;
Version of the application, default to something like "2008.2 (Build 366U)" (from $zv)
Property methods: ApplicationVersionDisplayToLogical(), ApplicationVersionGet(), ApplicationVersionIsValid(), ApplicationVersionLogicalToDisplay(), ApplicationVersionLogicalToOdbc(), ApplicationVersionNormalize(), ApplicationVersionSet()
property AuthFile as %String;
The path of a Pool Entry Authorization file (*.pea)
Property methods: AuthFileDisplayToLogical(), AuthFileGet(), AuthFileIsValid(), AuthFileLogicalToDisplay(), AuthFileLogicalToOdbc(), AuthFileNormalize(), AuthFileSet()
property BufferSizeInKB as %Integer [ Private , InitialExpression = 64 ];
The size of an internal C-Clip buffer in bytes. This value must be greater than 0. The SDK default value is 16KB. The default value we use here is 64KB.
Property methods: BufferSizeInKBDisplayToLogical(), BufferSizeInKBGet(), BufferSizeInKBIsValid(), BufferSizeInKBLogicalToDisplay(), BufferSizeInKBNormalize(), BufferSizeInKBSet()
property EmbeddedDataThreshold as %Integer (MAXVAL = 102400) [ Private , InitialExpression = 102400 ];
The maximum data size, in bytes, for data to be embedded in the CDF instead of being stored as separate blobs. The SDK default value is 0 bytes, meaning data is never embedded in the CDF. The maximum value is 102400 bytes (100 KB), which is the default value we use here. The value for the embedded data threshold can be set to less than or equal to 102400 bytes.
Property methods: EmbeddedDataThresholdDisplayToLogical(), EmbeddedDataThresholdGet(), EmbeddedDataThresholdIsValid(), EmbeddedDataThresholdLogicalToDisplay(), EmbeddedDataThresholdNormalize(), EmbeddedDataThresholdSet()
property Host as %String;
Connection information, a comma-delimited list of IP addresses
For example, ","
Property methods: HostDisplayToLogical(), HostGet(), HostIsValid(), HostLogicalToDisplay(), HostLogicalToOdbc(), HostNormalize(), HostSet()
property Password as %String;
Property methods: PasswordDisplayToLogical(), PasswordGet(), PasswordIsValid(), PasswordLogicalToDisplay(), PasswordLogicalToOdbc(), PasswordNormalize(), PasswordSet()
property PrefetchSizeInKB as %Integer (MAXVAL = 1024) [ Private , InitialExpression = 1024 ];
The size of the prefetch buffer. This buffer is used to assist in determining the size of the blob. The SDK default size is 32 KB. The maximum size is 1 MB, which is the default value we use here.
Property methods: PrefetchSizeInKBDisplayToLogical(), PrefetchSizeInKBGet(), PrefetchSizeInKBIsValid(), PrefetchSizeInKBLogicalToDisplay(), PrefetchSizeInKBNormalize(), PrefetchSizeInKBSet()
property UserName as %String;
An alternative to a PEA file is a pair of UserName and Password
Property methods: UserNameDisplayToLogical(), UserNameGet(), UserNameIsValid(), UserNameLogicalToDisplay(), UserNameLogicalToOdbc(), UserNameNormalize(), UserNameSet()


private method %OnClose() as %Status
Unload DLL
private method %OnNew() as %Status
Load DLL
method AccessContent(ContentUID As %String) as %Status
Test the existence of a content (C-Clip) by its UID (ContentAddress)
private method CheckVersion() as %Status
private method Close() as %Status
private method Commit(ByRef ContentUID As %String) as %Status
method Connect() as %Status
Connect to the server
private method Create(ContentOref As %Archive.Content) as %Status
method DeleteContent(ContentUID As %String) as %Status
Delete a content (C-Clip) by its UID (ContentAddress)
method Disconnect() as %Status
Disconnect from the server
private method GetAuthorization() as %String
Create a string based on AuthFile or UserName and Password. The string will be part of the connection argument for opening the pool.
private method GetErrorDetail() as %Status
private method LookUpDLLFunc(FuncName) as %Integer
private method NewTag(Name) as %Status
private method NextTag(ByRef Name As %String) as %Status
private method Open(ContentOref As %Archive.Content, ContentUID As %String) as %Status
private method ReadFile(Path As %String) as %Status
Read the blob associated with the tag by the name 'TagName' to the file given by 'Path' If TagName is not specified, use the current tag (either the first tag or the tag pointed to by GetNextTag()) If TagName is not unique in the content, use the first matching tag. May generate error
private method ReadNext(DataSink As %String) as %Status
private method ReadStream(StreamOref As %Stream, TagName As %String) as %Status
Similar to ReadFile, except that the data sink is a Cache %Stream object. NOT IMPLEMENTED.
private method Register() as %Status
method Retrieve(ContentOref As %Archive.Content, ContentUID As %String) as %Status
Retrieve an entire content from server
private method SetAttribute(AttribName As %String, AttribValue As %String) as %Status
private method SetBufferSize() as %Status
private method SetEmbeddedDataThreshold() as %Status
method Store(ContentOref As %Archive.Content, ByRef ContentUID As %String) as %Status
Store an entire content to server, commit and return a UID by reference
private method Write(DataSource As %String, TagName As %String) as %Status
A name for the data is required and cannot be NULL
private method WriteFile(Path As %String) as %Status
Create a tag with a 'TagName' and stream the given file to the blob associated with the tag Acceptable characters for a TagName are ASCII characters in the Set [a-zA-Z0-9_-.]. [No restriction in Unicode version] The first character must be a letter or an underscore "_". The name must be XML compliant and cannot start with the prefix "xml" or "eclip". May generate error
private method WriteStream(StreamOref As %Stream, TagName As %String = "_") as %Status
Similar to WriteFile, except that the data source is a Cache %Stream object. NOT IMPLEMENTED.

Inherited Members

Inherited Methods (Including Private)